Directions API

GET Async Route Matrix - Retrieve Results enterprise only

Once the job status is completed, use this endpoint to retrieve the computed travel time and distance matrix. The response is streamed directly to the client without server-side buffering, which is critical for large result sets (potentially GBs).

Resource URL

https://www.mapquestapi.com/directions/v2/routematrix/jobs/{jobId}/results

Resource Information

Response Formats	JSON (streamed)
Authentication	Yes (Requires Key)
Rate Limited	Yes

Request Parameters

Request Parameter	Description	Required
key String	The API Key, which is needed to make requests to MapQuest services.	Yes

Note: The jobId is specified in the URL path, not as a query parameter.

Response Object

matrix.numOrigins	The number of origin locations in the matrix.
matrix.numDestinations	The number of destination locations in the matrix.
matrix.travelTimes	Flattened 1D array of travel times in seconds. See Understanding the Response.
matrix.distances	Flattened 1D array of distances in meters. See Understanding the Response.
matrix.errorCodes	Optional. Flattened 1D array of error codes for each origin-destination pair. See Error Codes.

Understanding the Response

Units:

• travelTimes: Always in seconds
• distances: Always in meters

Array format:

The travelTimes and distances arrays are flattened 1D arrays representing a 2D matrix (origins × destinations).

The indices used in the formula below are 0-based:

• origin ranges from 0 to numOrigins - 1
• destination ranges from 0 to numDestinations - 1

To find the value for a specific origin-destination pair:

index = origin × numDestinations + destination

For example, with 2 origins (A, B) and 2 destinations (C, D), the flattened array contains: [A→C, A→D, B→C, B→D].

The mapping from matrix coordinates to array indices is:

origin index	destination index	origin-destination	array index
0	0	A→C	0
0	1	A→D	1
1	0	B→C	2
1	1	B→D	3

Error Codes

An errorCodes array may be present alongside the matrix data. Each value corresponds to an entry in the matrix:

Code	Meaning
0	Calculation successful
1	No route exists between the origin and destination
2	Could not match the origin or destination to a routable location
3	Route found but contains violations (e.g. avoided road type used, traffic blockage crossed)
4	Waypoint is outside the region limits

Transaction / Billing

TIP

This endpoint is non-billable (0 transactions). Retrieving results does not incur additional costs beyond the initial Submit Job request.

Example Request

curl -o results.json "https://www.mapquestapi.com/directions/v2/routematrix/jobs/YWJjMTIzLWRlZjQ1Ni1naGk3ODk6dXMtZWFzdC0xOm0/results?key=YOUR_API_KEY"

Example Response

{
  "matrix": {
    "numOrigins": 2,
    "numDestinations": 2,
    "travelTimes": [0, 268, 337, 0],
    "distances": [0, 36610, 17880, 0]
  }
}

Important Notes

• Streaming response: Results are streamed directly without server-side buffering. For large results (potentially GBs), use curl -o to write directly to a file rather than printing to stdout.
• Job must be completed: This endpoint only returns results when the job status is completed. Check status first via the Poll Job Status endpoint.
• Error codes: When some origin-destination pairs fail to route, the errorCodes array indicates which pairs succeeded and which failed. Successful pairs have code 0.