Distance Matrix Service

European Economic Area (EEA) developers
Note: Server-side libraries

Overview

Google's Distance Matrix service computes travel distance and journey duration between multiple origins and destinations using a given mode of travel.

This service does not return detailed route information. Route information, including polylines and textual directions, can be obtained by passing the desired single origin and destination to the Directions Service.

Getting started

Before using the Distance Matrix service in the Maps JavaScript API, first ensure that the Distance Matrix API (Legacy) is enabled in the Google Cloud console, in the same project you set up for the Maps JavaScript API.

To view your list of enabled APIs:

  1. Go to the Google Cloud console.
  2. Click the Select a project button, then select the same project you set up for the Maps JavaScript API and click Open.
  3. From the list of APIs on the Dashboard, look for Distance Matrix API (Legacy).
  4. If you see the API in the list, you're all set. If the API is not listed, enable it at https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

Pricing and policies

Pricing

To learn about pricing and usage policies for the JavaScript Distance Matrix service, see Usage and Billing for the Distance Matrix API (Legacy).

Note: Each query sent to the Distance Matrix service is limited by the number of allowed elements, where the number of origins times the number of destinations defines the number of elements.

Policies

Use of the Distance Matrix service must be in accordance with the policies described for the Distance Matrix API (Legacy).

Distance Matrix Requests

Accessing the Distance Matrix service is asynchronous, since the Google Maps API needs to make a call to an external server. For that reason, you need to pass a callback method to execute upon completion of the request, to process the results.

You access the Distance Matrix service within your code via the google.maps.DistanceMatrixService constructor object. The DistanceMatrixService.getDistanceMatrix() method initiates a request to the Distance Matrix service, passing it a DistanceMatrixRequest object literal containing the origins, destinations, and travel mode, as well as a callback method to execute upon receipt of the response.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

View example

The DistanceMatrixRequest contains the following fields:

  • origins (required) — An array containing one or more address strings, google.maps.LatLng objects, or Place objects from which to calculate distance and time.
  • destinations (required) — An array containing one or more address strings, google.maps.LatLng objects, or Place objects to which to calculate distance and time.
  • travelMode (optional) — The mode of transport to use when calculating directions. See the section on travel modes.
  • transitOptions (optional) — Options that apply only to requests where travelMode is TRANSIT. Valid values are described in the section on transit options.
  • drivingOptions (optional) specifies values that apply only to requests where travelMode is DRIVING. Valid values are described in the section on Driving Options.
  • unitSystem (optional) — The unit system to use when displaying distance. Accepted values are:
    • google.maps.UnitSystem.METRIC (default)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (optional) — If true, the routes between origins and destinations will be calculated to avoid highways where possible.
  • avoidTolls (optional) — If true, the directions between points will be calculated using non-toll routes, wherever possible.

Travel Modes

When calculating times and distances, you can specify which transportation mode to use. The following travel modes are currently supported:

  • BICYCLING requests bicycling directions via bicycle paths & preferred streets (currently only available in the US and some Canadian cities).
  • DRIVING (default) indicates standard driving directions using the road network.
  • TRANSIT requests directions via public transit routes. This option may only be specified if the request includes an API key. See the section on transit options for the available options in this type of request.
  • WALKING requests walking directions via pedestrian paths & sidewalks (where available).

Transit Options

The Transit Service is currently 'experimental'. During this phase, we will be implementing rate limits to prevent API abuse. We will eventually enforce a cap on total queries per map load based on fair usage of the API.

The available options for a distance matrix request vary across travel modes. In transit requests, the avoidHighways and avoidTolls options are ignored. You can specify transit-specific routing options through the TransitOptions object literal.

Transit requests are time sensitive. Calculations will only be returned for times in the future.

The TransitOptions object literal contains the following fields:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

These fields are explained below:

  • arrivalTime (optional) specifies the desired time of arrival as a Date object. If arrival time is specified, departure time is ignored.
  • departureTime (optional) specifies the desired time of departure as a Date object. The departureTime will be ignored if arrivalTime is specified. Defaults to now (that is, the current time) if no value is specified for either departureTime or arrivalTime.
  • modes (optional) is an array containing one or more TransitMode object literals. This field may only be included if the request includes an API key. Each TransitMode specifies a preferred mode of transit. The following values are permitted:
    • BUS indicates that the calculated route should prefer travel by bus.
    • RAIL indicates that the calculated route should prefer travel by train, tram, light rail, and subway.
    • SUBWAY indicates that the calculated route should prefer travel by subway.
    • TRAIN indicates that the calculated route should prefer travel by train.
    • TRAM indicates that the calculated route should prefer travel by tram and light rail.
  • routingPreference (optional) specifies preferences for transit routes. Using this option, you can bias the options returned, rather than accepting the default best route chosen by the API. This field may only be specified if the request includes an API key. The following values are permitted:
    • FEWER_TRANSFERS indicates that the calculated route should prefer a limited number of transfers.
    • LESS_WALKING indicates that the calculated route should prefer limited amounts of walking.

Driving Options

Use the drivingOptions object to specify a departure time for calculating the best route to your destination given the expected traffic conditions. You can also specify whether you want the estimated time in traffic to be pessimistic, optimistic, or the best estimate based on historical traffic conditions and live traffic.

The drivingOptions object contains the following fields:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

These fields are explained below:

  • departureTime (required for the drivingOptions object literal to be valid) specifies the desired time of departure as a Date object. The value must be set to the current time or some time in the future. It cannot be in the past. (The API converts all dates to UTC to ensure consistent handling across time zones.) If you include the departureTime in the request, the API returns the best route given the expected traffic conditions at the time, and includes the predicted time in traffic (duration_in_traffic) in the response. If you don't specify a departure time (that is, if the request does not include drivingOptions), the returned route is a generally good route without taking traffic conditions into account.
  • trafficModel (optional) specifies the assumptions to use when calculating time in traffic. This setting affects the value returned in the duration_in_traffic field in the response, which contains the predicted time in traffic based on historical averages. Defaults to best_guess. The following values are permitted:
    • bestguess (default) indicates that the returned duration_in_traffic should be the best estimate of travel time given what is known about both historical traffic conditions and live traffic. Live traffic becomes more important the closer the departureTime is to now..
    • pessimistic indicates that the returned duration_in_traffic should be longer than the actual travel time on most days, though occasional days with particularly bad traffic conditions may exceed this value.
    • optimistic indicates that the returned duration_in_traffic should be shorter than the actual travel time on most days, though occasional days with particularly good traffic conditions may be faster than this value.

Below is a sample DistanceMatrixRequest for driving routes, including a departure time and traffic model:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Distance Matrix Responses

A successful call to the Distance Matrix service returns a DistanceMatrixResponse object and a DistanceMatrixStatus object. These are passed to the callback function you specified in the request.

The DistanceMatrixResponse object contains distance and duration information for each origin/destination pair for which a route could be calculated.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Distance Matrix Results

The supported fields in a response are explained below.

  • originAddresses is an array containing the locations passed in the origins field of the Distance Matrix request. The addresses are returned as they are formatted by the geocoder.
  • destinationAddresses is an array containing the locations passed in the destinations field, in the format returned by the geocoder.
  • rows is an array of DistanceMatrixResponseRow objects, with each row corresponding to an origin.
  • elements are children of rows, and correspond to a pairing of the row's origin with each destination. They contain status, duration, distance, and fare information (if available) for each origin/destination pair.
  • Each 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. The textual value is formatted according to the unitSystem specified in the request (or in metric, if no preference was supplied).
    • duration_in_traffic: The length of time it takes to travel this route taking into account current traffic conditions, expressed in seconds (the value field) and as text. The textual value is formatted according to the unitSystem specified in the request (or in metric, if no preference was supplied). The duration_in_traffic is only returned where traffic data is available, the mode is set to driving, and departureTime is included as part of the distanceMatrixOptions field in the request.
    • distance: The total distance of this route, expressed in meters (value) and as text. The textual value is formatted according to the unitSystem specified in the request (or in metric, if no preference was supplied).
    • fare: Contains the total fare (that is, the total ticket costs) on this route. This property is only returned for transit requests and only for transit providers where fare information is available. The information includes:
      • currency: An ISO 4217 currency code indicating the currency that the amount is expressed in.
      • value: The total fare amount, in the currency specified above.

Status Codes

The Distance Matrix response includes a status code for the response as a whole, as well as a status for each element.

Response Status Codes

Status codes that apply to the DistanceMatrixResponse are passed in the DistanceMatrixStatus object and include:

  • OK — The request is valid. This status can be returned even if no routes were found between any of the origins and destinations. See Element Status Codes for the element-level status information.
  • INVALID_REQUEST — The provided request was invalid. This is often due to missing required fields. See the list of supported fields above.
  • MAX_ELEMENTS_EXCEEDED — The product of origins and destinations exceeds the per-query limit.
  • MAX_DIMENSIONS_EXCEEDED — Your request contained more than 25 origins, or more than 25 destinations.
  • OVER_QUERY_LIMIT — Your application has requested too many elements within the allowed time period. The request should succeed if you try again after a reasonable amount of time.
  • REQUEST_DENIED — The service denied use of the Distance Matrix service by your web page.
  • UNKNOWN_ERROR — A Distance Matrix request could not be processed due to a server error. The request may succeed if you try again.

Element Status Codes

The following status codes apply to specific DistanceMatrixElement objects:

  • NOT_FOUND — The origin and/or destination of this pairing could not be geocoded.
  • OK — The response contains a valid result.
  • ZERO_RESULTS — No route could be found between the origin and destination.

Parsing the Results

The DistanceMatrixResponse object contains one row for each origin that was passed in the request. Each row contains an element field for each pairing of that origin with the provided destination(s).

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}