The Route Matrix function allows for a quick and easy calculation of the distances and driving times between a set of points.
http://open.mapquestapi.com/directions/v2/routematrix
Response Formats | JSON, XML |
---|---|
Authentication | Yes (Requires Key) |
Rate Limited | Yes |
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 |
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 |
Options | ||
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 |
Please refer to the normal Route documentation for the full list of acceptable Advanced Parameters.
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.
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 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. |
POST
http://open.mapquestapi.com/directions/v2/routematrix?key=KEY
{
"locations": [
"Denver, CO",
"Westminster, CO",
"Boulder, CO"
],
"options": {
"allToAll": true
}
}
{
"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": "© 2018 MapQuest, Inc.",
"imageUrl": "http://api.mqcdn.com/res/mqlogo.gif",
"imageAltText": "© 2018 MapQuest, Inc."
},
"statuscode": 0,
"messages": []
}
}