Skip to content

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

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

Resource Information

Response FormatsJSON, XML
AuthenticationYes (Requires Key)
Rate LimitedYes

Request Parameters

Request ParameterDescriptionRequired
key
String
The API Key, which is needed to make requests to MapQuest services.Yes
inFormatSpecifies the format of the request body. Must be one of the following, if supplied:
  • json
  • xml
Default: json
No
outFormatSpecifies the format of the response. Must be one of the following, if supplied:
  • json
  • xml
Default: json
No
callbackA 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

ParameterDescriptionRequired
locationsA 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

ParameterDescriptionRequired
allToAllIf 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
manyToOneIf 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 FieldDescription
allToAllReturns the allToAll parameter, echoed for clarity.
manyToOneReturns the manyToOne parameter, echoed for clarity.
distanceAn 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.
timeAn 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.
locationsSame as with a normal Route response.
infoThis 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>&copy; 2023 MapQuest, Inc.</imageAltText>
      <text>&copy; 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>