Developer Guide

Distance Matrix API

Introduction
Before you begin
This document is intended for developers who wish to compute travel distance and time between a number of points. It provides an introduction to using the API and reference material on the available parameters.

The Distance Matrix API is an HTTP API service that provides travel distance and time for a locations matrix. Calculations are made for all possible combinations between the origin and destination. The API returns information is based on the recommended route between start and end points, as calculated by Distance Matrix API, and consists of rows containing duration and distance values for each pair.

The API response contains a distance matrix in JSON format, as well as information about the duration of each constructed route section in the matrix. The calculated travel time for a route section always accounts for current traffic conditions and the traffic forecast. The Distance Matrix API works worldwide and is available for the driving profile.

You can use the API to find the destination point that is the closest to the point of origin or for any other purpose. The Matrix API will always return a duration and a distance on the fastest route for each element in the matrix, where an element is an origin-destination pair in the matrix.

For example, given three origin locations A, B, and C, and three destination locations E, B, and D, the Matrix API will return the matrix of all travel times in seconds and distances in meters between the locations:
The Matrix API returns durations in seconds and distances in meters. It does not return route geometries.

Durations and distances between points may not be symmetric, since the routes may differ by direction due to one-way streets or turn restrictions. For example, A to B may have a different duration than B to A.
Distance Matrix Requests
Request Parameters
The Distance Matrix API request was created specifically to be similar to the Google Distance Matrix API request format. You can get more information on the Migrate to DistanceMatrix.ai API page.
A Distance Matrix API request takes the following form:
GET
https://api.distancematrix.ai/maps/api/distancematrix/json
?origins=<origin_location_1|origin_location_2|...|origin_location_n>
&destinations=<destination_location_1|destination_location_2|...|destination_location_n>
&key=<your_access_token>
A Distance Matrix API request example:
GET
https://api.distancematrix.ai/maps/api/distancematrix/json?origins=51.4822656,-0.1933769&destinations=51.4994794,-0.1269979&key=<your_access_token>
Required Parameters
  • origins — The starting point for calculating travel distance and time. You can supply one or more locations separated by the pipe character (|) in the form of an address or latitude/longitude coordinates:
    • If you pass an address, the service geocodes the string and converts it to a latitude/longitude coordinate to calculate distance. This coordinate may be different from that returned by the Geocoding API, for example, a building entrance rather than its center.
    • If you pass latitude/longitude coordinates, they are used unchanged to calculate distance. Ensure that no space exists between the latitude and longitude values
  • destinations — One or more locations to use as the finishing point for calculating travel distance and time. The options for the destinations parameter are the same as for the origins parameter, described above.
  • key — Your application's API key
Optional Parameters
  • mode (defaults to driving) — Specifies the mode of transport to use when calculating distance. Valid values and other request details are specified in the Travel Modes section of this document.

  • language — The language in which to return results.

  • avoid — Introduces restrictions to the route. Valid values are specified in the Restrictions section of this document. Only one restriction can be specified.

  • units — Specifies the unit system to use when expressing distance as text. See the Unit Systems section of this document for more information.

  • arrival_time — Specifies the desired time of arrival for transit requests, in seconds since midnight, January 1, 1970 UTC. You can specify either departure_time or arrival_time, but not both. Note that arrival_time must be specified as an integer.

  • departure_time — The desired time of departure. You can specify the time as an integer in seconds since midnight, January 1, 1970 UTC. Alternatively, you can specify a value of now, which sets the departure time to the current time (correct to the nearest second). If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time). The departure_time must be set to the current time or some time in the future. It cannot be in the past. Results for a given request may vary over time due to changes in the road network, updated average traffic conditions, and the distributed nature of the service. Results may also vary between nearly-equivalent routes at any time or frequency.
Travel Modes
For the calculation of distances, you may specify the transportation mode to use. By default, distances are calculated for driving mode. The following travel modes are supported:

  • driving (default) indicates distance calculation using the road network.
  • walking requests distance calculation for walking via pedestrian paths & sidewalks (where available).
  • bicycling requests distance calculation for bicycling via bicycle paths & preferred streets (where available).
Traffic Information
Traffic information is used when all the following apply (these are the conditions required to receive the duration_in_traffic field in the Distance Matrix response):

  • The travel mode parameter is driving, or is not specified ( driving is the default travel mode).
  • The request includes a valid departure_time parameter. The departure_time can be set to the current time or some other time.
Optionally, you can include the traffic_model parameter in your request to specify the assumptions to use when calculating time in traffic.
Restrictions
Distances may be calculated that adhere to certain restrictions. Restrictions are indicated by use of the avoid parameter, and an argument to that parameter indicating the restriction to avoid. The following restrictions are supported:

  • avoid=tolls
  • avoid=highways
  • avoid=ferries
  • avoid=indoor
Unit Systems
Distance Matrix results contain text within distance fields to indicate the distance of the calculated route. The unit system to use can be specified:

  • units=metric (default) returns distances in kilometers and meters.
  • units=imperial returns distances in miles and feet.
* Note: this unit system setting only affects the text displayed within distance fields. The distance fields also contain values which are always expressed in meters.
Distance Matrix Responses
Response example
The response contains an array of rows objects, each row containing one origin paired with each destination. Each elements object in the array contains the properties of a single route variant. For detailed descriptions of elements, see the section Distance Matrix Response Elements.
Response
BODY
{
  "destination_addresses": [
    "Westminster Abbey, Westminster, London SW1P 3PA, UK"
  ],
  "origin_addresses": [
    "Chapel, Fulham, London SW6 1BA, UK"
  ],
  "rows": [
    {
      "elements": [
        {
          "distance": {
            "text": "4.7 miles",
            "value": 7565
          },
          "duration": {
            "text": "22 min",
            "value": 1306
          },
          "status": "OK"
        }
      ]
    }
  ],
  "status": "OK"
}
Distance Matrix Response Elements
Distance Matrix responses contain the following root elements
  • status contains metadata on the request. See Status Codes below.
  • origin_addresses contains an array of addresses as returned by the API from your original request. These are formatted by the geocoder and localized according to the language parameter passed with the request.
  • destination_addresses contains an array of addresses as returned by the API from your original request. As with origin_addresses, these are localized if appropriate.
  • rows contain an array of elements, which in turn each contain status, duration, and distance element.
Status Codes
The status fields within the response object contain the status of the request and may contain useful debugging information. The Distance Matrix API returns a top-level status field, with information about the request in general, as well as a status field for each element field, with information about that particular origin-destination pairing.
Top-level Status Codes
  • OK indicates the response contains a valid result.
  • INVALID_REQUEST indicates that the provided request was invalid.
  • MAX_ELEMENTS_EXCEEDED indicates that the product of origins and destinations exceeds the per-query limit.
  • OVER_DAILY_LIMIT indicates any of the following:
    • The API key is missing or invalid.
    • Billing has not been enabled on your account.
    • A self-imposed usage cap has been exceeded.
    • The provided method of payment is no longer valid (for example, a credit card has expired).
  • OVER_QUERY_LIMIT indicates the service has received too many requests from your application within the allowed time period.
  • REQUEST_DENIED indicates that the service denied the use of the Distance Matrix service by your application.
  • UNKNOWN_ERROR indicates a Distance Matrix request could not be processed due to a server error. The request may succeed if you try again.
Element-level Status Codes
  • OK indicates the response contains a valid result.
  • NOT_FOUND indicates that the origin and/or destination of this pairing could not be geocoded.
  • ZERO_RESULTS indicates no route could be found between the origin and destination.
  • MAX_ROUTE_LENGTH_EXCEEDED indicates the requested route is too long and cannot be processed.
Error Messages
When the top-level status code is other than OK, there may be an additional error_message field within the Distance Matrix response object. This field contains more detailed information about the reasons behind the given status code.
Rows
When the Distance Matrix API returns results, it places them within a JSON rows array. Even if no results are returned (such as when the origins and/or destinations don't exist), it still returns an empty array.

Rows are ordered according to the values in the origin parameter of the request. Each row corresponds to an origin, and each element within that row corresponds to a pairing of the origin with a destination value.

Each row array contains one or more element entries, which in turn contain the information about a single origin-destination pairing.
Elements
The information about each origin-destination pairing is returned in an element entry. An element contains the following fields:

  • status: See Status Codes for a list of possible status codes.
  • duration: The length of time it takes to travel this route, expressed in seconds (the value field) and as text.
  • duration_in_traffic: The length of time it takes to travel this route, based on current and historical traffic conditions.
  • distance: The total distance of this route, expressed in meters (value) and as text.
Easy To Integrate Distance Matrix API
Fill in the form and get a free 7 days trial period for Distance Matrix API
Tell us more about your project and we'll help you to choose the best solution and pricing plan.
Name
Link to your website or your company name and job position
Email where to send a token and instructions
What is the most comfortable channel to communicate with you?
How many requests do you want to make per month?
Have you ever used Google Distance Matrix API or any other similar API before?
You agree with our Terms and Conditions
Made on
Tilda