Open 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

http://open.mapquestapi.com/directions/v2/routematrix

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
  • xml
Default: json 		No
outFormat Specifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
Default: 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
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.

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.

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

http://open.mapquestapi.com/directions/v2/routematrix?key=KEY

Example Request Body

{
  "locations": [
    "Denver, CO",
    "Westminster, CO",
    "Boulder, CO"
  ],
  "options": {
    "allToAll": true
  }
}

Example Response

{
  "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": "© 2017 MapQuest, Inc.",
      "imageUrl": "http://api.mqcdn.com/res/mqlogo.gif",
      "imageAltText": "© 2017 MapQuest, Inc."
    },
    "statuscode": 0,
    "messages": []
  }
}