Directions API
POST Route Matrix
The Route Matrix function allows for a quick and easy calculation of the distances and driving times between a set of points.
Resource URL
Resource Information
| Response Formats | JSON, XML |
| 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 |
| inFormat | Specifies the format of the request body. Must be one of the following, if supplied:
json | No |
| outFormat | Specifies the format of the response. Must be one of the following, if supplied:
json | No |
| callback | A JavaScript function name. The JSON-formatted response will be wrapped in a call to the supplied callback function name to provide JSONP functionality. This functionality might be needed to do cross-site scripting. See the Wikipedia.org entry for JSON for more details. | No |
Body Parameters
| Parameter | Description | Required |
|---|---|---|
| locations | A set of at least 2 locations specifying the route origin and destination. Refer to the Locations documentation on how to properly form locations in all formats. | Yes |
Body Parameter Options
| Parameter | Description | Required |
|---|---|---|
| allToAll | If this parameter is not present, or false, the response will contain a one-dimensional list of times/distances from the first location to each location. If the allToAll parameter is set to true, the response will contain a two-dimensional list of times/distances from each location to every other location. | No |
| manyToOne | If this parameter is not present, or false, the response will contain a one-dimensional list of times/distances from the first location to each location. If the manyToOne parameter is set to true, this indicates that the method will compute time and distance from many origins to a single destination (the first location in lc). This flag is only valid if allToAll is false. | No |
TIP
Time/distances values are not always symmetric. That is, the distance from A to B might not be the same as the distance from B to A.
Please refer to the normal Route documentation for the full list of acceptable Advanced Parameters.
Route Matrix Limits
There are time and distance limits in place on the route matrix call because this can become a very expensive request. The route matrix is not intended for computing extremely long distances from a large number of locations.
TIP
A One to Many route matrix call can handle up to 100 locations.
TIP
A Many to One matrix call can handle up to 50 locations.
TIP
An all to all route matrix call can handle up to 25 locations.
Route matrix methods use what is called multi-destination path search. It expands from the origin location and marks each destination it finds. This search gets more expensive as the distance from the origin location increases, so the search is limited by a setting called MaxMatrixSearchTime. This is set to 180 minutes. Any destinations that lie outside this limit are found using regular "point to point" routes. However, the server limits the number of outlying locations (outside the MaxMatrixSearch limit) with a setting called MaxMatrixPointToPoint. This value is set to 25.
Route matrix methods are intended to support many destinations within a short distance of each other. These limits allow several locations to be farther away, but still protect the server from matrix requests that would take an exceptionally long time to compute. A user should break such requests into smaller sets to allow them to complete within the limits.
Response
| Response Field | Description |
|---|---|
| allToAll | Returns the allToAll parameter, echoed for clarity. |
| manyToOne | Returns the manyToOne parameter, echoed for clarity. |
| distance | An array of distances between locations. The array will have dimension 1xN (where N is the number of locations supplied) if the allToAll parameter was false, or NxN otherwise.When allToAll is false, element i of the array will be the distance from the first location to location i.When allToAll is true, element i,j of the array will be the distance from location i to location j. |
| time | An array of times (in seconds) between locations. The array will have dimension 1xN (where N is the number of locations supplied) if the allToAll parameter was false, or NxN otherwise.When allToAll is false, element i of the array will be the time from the first location to location i.When allToAll is true, element i,j of the array will be the time from location i to location j. |
| locations | Same as with a normal Route response. |
| info | This field contains information about the response. The statuscode subfield is an integer return value. See the Status Codes page for more details on our status codes and error messages.The messages subfield is an array of error messages which describe the status. |
Example Request
POST https://www.mapquestapi.com/directions/v2/routematrix?key=KEY
Example Request Body
JSON
{
"locations": [
"Denver, CO",
"Westminster, CO",
"Boulder, CO"
],
"options": {
"allToAll": true
}
}XML
<route>
<locations>
<location>Denver, CO</location>
<location>Westminster, CO</location>
<location>Boulder, CO</location>
</locations>
<options>
<allToAll>true</allToAll>
</options>
</route>Example Response
JSON
{
"allToAll": true,
"distance": [
[
0,
13.052,
29.369
],
[
11.67,
0,
17.06
],
[
28.441,
17.783,
0
]
],
"time": [
[
0,
1037,
2150
],
[
1068,
0,
1253
],
[
2119,
1242,
0
]
],
"locations": [
{
"latLng": {
"lng": -104.984853,
"lat": 39.738453
},
"adminArea4": "Denver County",
"adminArea5Type": "City",
"adminArea4Type": "County",
"adminArea5": "Denver",
"street": "",
"adminArea1": "US",
"adminArea3": "CO",
"type": "s",
"displayLatLng": {
"lng": -104.984853,
"lat": 39.738453
},
"linkId": 282041090,
"postalCode": "",
"sideOfStreet": "N",
"dragPoint": false,
"adminArea1Type": "Country",
"geocodeQuality": "CITY",
"geocodeQualityCode": "A5XAX",
"adminArea3Type": "State"
},
{
"latLng": {
"lng": -105.050335,
"lat": 39.863462
},
"adminArea4": "City and County of Broomfield",
"adminArea5Type": "City",
"adminArea4Type": "County",
"adminArea5": "Westminster",
"street": "",
"adminArea1": "US",
"adminArea3": "CO",
"type": "s",
"displayLatLng": {
"lng": -105.050335,
"lat": 39.863462
},
"linkId": 282040216,
"postalCode": "",
"sideOfStreet": "N",
"dragPoint": false,
"adminArea1Type": "Country",
"geocodeQuality": "CITY",
"geocodeQualityCode": "A5XAX",
"adminArea3Type": "State"
},
{
"latLng": {
"lng": -105.27927,
"lat": 40.015831
},
"adminArea4": "Boulder County",
"adminArea5Type": "City",
"adminArea4Type": "County",
"adminArea5": "Boulder",
"street": "",
"adminArea1": "US",
"adminArea3": "CO",
"type": "s",
"displayLatLng": {
"lng": -105.27927,
"lat": 40.015831
},
"linkId": 282039983,
"postalCode": "",
"sideOfStreet": "N",
"dragPoint": false,
"adminArea1Type": "Country",
"geocodeQuality": "CITY",
"geocodeQualityCode": "A5XAX",
"adminArea3Type": "State"
}
],
"manyToOne": false,
"info": {
"copyright": {
"text": "© 2023 MapQuest, Inc.",
"imageUrl": "https://api.mqcdn.com/res/mqlogo.gif",
"imageAltText": "© 2023 MapQuest, Inc."
},
"statuscode": 0,
"messages": []
}
}XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<info>
<statusCode>0</statusCode>
<messages/>
<copyright>
<imageUrl>https://api.mqcdn.com/res/mqlogo.gif</imageUrl>
<imageAltText>© 2023 MapQuest, Inc.</imageAltText>
<text>© 2023 MapQuest, Inc.</text>
</copyright>
</info>
<allToAll>true</allToAll>
<manyToOne>false</manyToOne>
<locations>
<location>
<street/>
<adminArea5 type="City">Denver</adminArea5>
<adminArea3 type="State">CO</adminArea3>
<adminArea4 type="County">Denver County</adminArea4>
<postalCode/>
<adminArea1 type="Country">US</adminArea1>
<geocodeQuality>CITY</geocodeQuality>
<geocodeQualityCode>A5XAX</geocodeQualityCode>
<dragPoint>false</dragPoint>
<sideOfStreet>N</sideOfStreet>
<displayLatLng>
<latLng>
<lat>39.738453</lat>
<lng>-104.984853</lng>
</latLng>
</displayLatLng>
<linkId>282041090</linkId>
<type>s</type>
<latLng>
<lat>39.738453</lat>
<lng>-104.984853</lng>
</latLng>
</location>
<location>
<street/>
<adminArea5 type="City">Westminster</adminArea5>
<adminArea3 type="State">CO</adminArea3>
<adminArea4 type="County">City and County of Broomfield</adminArea4>
<postalCode/>
<adminArea1 type="Country">US</adminArea1>
<geocodeQuality>CITY</geocodeQuality>
<geocodeQualityCode>A5XAX</geocodeQualityCode>
<dragPoint>false</dragPoint>
<sideOfStreet>N</sideOfStreet>
<displayLatLng>
<latLng>
<lat>39.863462</lat>
<lng>-105.050335</lng>
</latLng>
</displayLatLng>
<linkId>282040216</linkId>
<type>s</type>
<latLng>
<lat>39.863462</lat>
<lng>-105.050335</lng>
</latLng>
</location>
<location>
<street/>
<adminArea5 type="City">Boulder</adminArea5>
<adminArea3 type="State">CO</adminArea3>
<adminArea4 type="County">Boulder County</adminArea4>
<postalCode/>
<adminArea1 type="Country">US</adminArea1>
<geocodeQuality>CITY</geocodeQuality>
<geocodeQualityCode>A5XAX</geocodeQualityCode>
<dragPoint>false</dragPoint>
<sideOfStreet>N</sideOfStreet>
<displayLatLng>
<latLng>
<lat>40.015831</lat>
<lng>-105.27927</lng>
</latLng>
</displayLatLng>
<linkId>282039983</linkId>
<type>s</type>
<latLng>
<lat>40.015831</lat>
<lng>-105.27927</lng>
</latLng>
</location>
</locations>
<time>
<time0>0,1037,2150</time0>
<time1>1068,0,1253</time1>
<time2>2119,1242,0</time2>
</time>
<distance>
<distance0>0.0,13.052,29.369</distance0>
<distance1>11.67,0.0,17.06</distance1>
<distance2>28.441,17.783,0.0</distance2>
</distance>
</response>