Directions API

POST Async Route Matrix - Submit Job enterprise only

The Async Route Matrix API computes large-scale travel time and distance matrices between sets of origins and destinations, supporting up to 10,000 x 10,000 location pairs. It uses a 3-step asynchronous flow: submit, poll, retrieve.

This endpoint submits a matrix calculation request and returns a job ID used to poll status and retrieve results.

Resource URL

https://www.mapquestapi.com/directions/v2/routematrix/jobs

Resource Information

Response Formats	JSON
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

Body Parameters

Parameter	Type	Description	Required
origins	Array	Array of {lat, lng} objects representing origin locations. Min 1, max 10,000.	Yes
destinations	Array	Array of {lat, lng} objects representing destination locations. Min 1, max 10,000.	Yes
options.transport	String	Transport mode: car, truck, pedestrian, bicycle. Case-insensitive.	No, defaults to car
options.mode	String	Routing mode: fastest or shortest. Case-insensitive.	No, defaults to fastest
options.departureTime	String	ISO 8601 datetime with timezone offset (e.g. 2026-08-06T11:20:00+02:00), or "any" for time-independent routing. Only supported when options.region is provided.	No
options.region	Object	GeoJSON Polygon constraining the routing area. See Region Parameter below.	No

Response Object

id	The unique job identifier. Use this value as-is in subsequent status and results requests.
status	The current job status (accepted).
href	URL to poll the job status.

Transport and Mode Combinations

The following transport and mode combinations are supported:

Transport	Mode
car (default)	fastest (default)
car	shortest
truck	fastest
pedestrian	any
bicycle	any

Unsupported combinations when no region is provided

• truck + shortest returns a 400 error
• taxi, scooter, bus, privateBus are not supported without a region and return a 400 error

Region Parameter

The options.region field defines a GeoJSON Polygon that constrains the routing area. When provided, routes are computed only within the polygon boundary, which can improve performance for regional matrices.

When to use a region vs. not:

• With region (polygon): Best for smaller, focused matrices. Supports transport, mode, and departureTime options. The polygon must have a diameter under 400 km.
• Without region: Routing is unbounded and supports large matrices (e.g. 10,000 x 10,000). Does not support departureTime.

Polygon constraints:

• Must be a closed ring: first and last coordinate must be identical
• Minimum 3 vertices (4 coordinates including closing point)
• Maximum 100 vertices (101 coordinates including closing point)
• Coordinates are in GeoJSON order: [longitude, latitude]
• Maximum diameter of ~400 km. If exceeded, a 400 error is returned.

Example polygon (bounding box):

{
  "type": "Polygon",
  "coordinates": [[
    [-106.545, 38.532],
    [-103.55, 38.532],
    [-103.55, 40.928],
    [-106.545, 40.928],
    [-106.545, 38.532]
  ]]
}

Transaction / Billing

Each call to the submit endpoint counts as one or more transactions depending on the number of origins (S) and destinations (D):

• If S or D is less than 5: transactions = S × D
• If S and D are both 5 or greater: transactions = max(S, D) × 5

Origins (S)	Destinations (D)	Transactions	Rule Applied
3	4	12	S × D (one side < 5)
2	10	20	S × D (one side < 5)
10	20	100	max(10, 20) × 5 (both ≥ 5)
100	100	500	max(100, 100) × 5 (both ≥ 5)
5	5	25	max(5, 5) × 5 (both ≥ 5)

Example Request

curl -X POST "https://www.mapquestapi.com/directions/v2/routematrix/jobs?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origins": [
      {"lat": 39.7392, "lng": -104.9903},
      {"lat": 40.7128, "lng": -74.0060}
    ],
    "destinations": [
      {"lat": 34.0522, "lng": -118.2437},
      {"lat": 41.8781, "lng": -87.6298}
    ],
    "options": {"transport": "car", "mode": "fastest"}
  }'

Example Response

{
  "id": "YWJjMTIzLWRlZjQ1Ni1naGk3ODk6dXMtZWFzdC0xOm0",
  "status": "accepted",
  "href": "https://www.mapquestapi.com/directions/v2/routematrix/jobs/YWJjMTIzLWRlZjQ1Ni1naGk3ODk6dXMtZWFzdC0xOm0"
}

Error Handling

• Validation error (400): Returned for invalid request bodies (e.g. missing origins, invalid coordinates, unclosed polygon ring). The response includes a descriptive message.
• Region too large (400): Returned when the polygon region exceeds the ~400 km diameter limit.
• Unsupported transport/mode (400): Returned for transport/mode combinations not supported without a region (e.g. truck + shortest, or taxi).

Important Notes

• Matrix size: Up to 10,000 × 10,000 (100 million calculations) without a region. With a polygon region, smaller matrices are recommended to avoid per-segment waypoint limits.
• Processing time: Large matrices may take minutes to hours to compute.
• Units: Distances are always in meters. Travel times are always in seconds.
• Job ID: The id returned by the API encodes all context needed for polling and retrieval. Use it as-is in subsequent requests.
• 3-step flow: This endpoint only submits the job. Use Poll Job Status to check progress, and Retrieve Results once complete.