Stay organized with collections Save and categorize content based on your preferences.
IntroductionA Distance Matrix API request takes the following form:
https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
where outputFormat
may be either of the following values:
json
(recommended) indicates output in JavaScript Object Notation (JSON).xml
indicates output as XML.Certain parameters are required while others are optional. As is standard in URLs, all parameters are separated using the ampersand (&
) character. All reserved characters (for example the plus sign "+") must be URL-encoded. The list of parameters and their possible values are enumerated below.
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.
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 a place ID, an address, or latitude/longitude coordinates:
place_id:
.Note: using place IDs is preferred over using addresses or latitude/longitude coordinates. Using coordinates will always result in the point being snapped to the road nearest to those coordinates - which may not be an access point to the property, or even a road that will quickly or safely lead to the destination. Using the address will provide the distance to the center of the building, as opposed to an entrance to the building.
849VCWC8+R9
is encoded to 849VCWC8%2BR9
).CWC8+R9 Mountain View, CA, USA
is encoded to CWC8%2BR9%20Mountain%20View%20CA%20USA
).enc:
and followed by a colon :
. For example: origins=enc:gfo}EtohhU:
|
. For example:
origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
Specifies the desired time of arrival for transit directions, 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.
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:
tolls
indicates that the calculated route should avoid toll roads/bridges.highways
indicates that the calculated route should avoid highways.ferries
indicates that the calculated route should avoid ferries.indoor
indicates that the calculated route should avoid indoor steps for walking and transit directions.It's possible to request a route that avoids any combination of tolls, highways and ferries by passing both restrictions to the avoid parameter. For example avoid=tolls|highways|ferries
.
Note: The addition of restrictions does not preclude routes that include the restricted feature; it biases the result to more favorable routes.
Specifies the desired time of departure. You can specify the time as an integer in seconds since midnight, January 1, 1970 UTC. If a departure_time
later than 9999-12-31T23:59:59.999999999Z is specified, the API will fall back the departure_time
to 9999-12-31T23:59:59.999999999Z. Alternatively, you can specify a value of now, which sets the departure time to the current time (correct to the nearest second). The departure time may be specified in two cases:
departure_time
or arrival_time
. If neither time is specified, the departure_time
defaults to now (that is, the departure time defaults to the current time).departure_time
to receive a route and trip duration (response field: duration_in_traffic) that take traffic conditions into account. The departure_time
must be set to the current time or some time in the future. It cannot be in the past.Note: If departure time is not specified, choice of route and duration are based on road network and average time-independent traffic conditions. 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.
Note: Distance Matrix requests specifying departure_time
when mode=driving
are limited to a maximum of 100 elements per request. The number of origins times the number of destinations defines the number of elements.
The language in which to return results.
language
is not supplied, the API attempts to use the preferred language as specified in the Accept-Language
header.For the calculation of distances and directions, you may specify the transportation mode to use. By default, DRIVING
mode is used. By default, directions are calculated as driving directions. The following travel modes are supported:
driving
(default) indicates standard driving directions or distance using the road network.walking
requests walking directions or distance via pedestrian paths & sidewalks (where available).bicycling
requests bicycling directions or distance via bicycle paths & preferred streets (where available).transit
requests directions or distance using public transit routes (where available). If you set the mode to transit, you can optionally specify either a departure_time
or an arrival_time
. If neither time is specified, the departure_time
defaults to now (that is, the departure time defaults to the current time). You can also optionally include a transit_mode
and/or a transit_routing_preference
.Note: Both walking and bicycling directions may sometimes not include clear pedestrian or bicycling paths, so these directions will return warnings in the returned result which you must display to the user.
Note: Transit trips are available for up to 7 days in the past or up to 100 days in the future, subject to availability of transit information supplied by data providers. Transit schedules change frequently, available transit trips may change over time and there is no guarantee to provide consistent results for predictions far in advance.
The region code, specified as a ccTLD ("top-level domain") two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland").
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. The traffic_model
parameter may only be specified for driving directions where the request includes a departure_time
. The available values for this parameter are:
best_guess
(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 departure_time
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.The default value of best_guess
will give the most useful predictions for the vast majority of use cases. It is possible the best_guess
travel time prediction may be shorter than optimistic
, or alternatively, longer than pessimistic
, due to the way the best_guess
prediction model integrates live traffic information.
Specifies one or more preferred modes of transit. This parameter may only be specified for transit directions. The parameter supports the following arguments:
bus
indicates that the calculated route should prefer travel by bus.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.rail
indicates that the calculated route should prefer travel by train, tram, light rail, and subway. This is equivalent to transit_mode=train|tram|subway
.Specifies preferences for transit routes. Using this parameter, you can bias the options returned, rather than accepting the default best route chosen by the API. This parameter may only be specified for transit directions. The parameter supports the following arguments:
less_walking
indicates that the calculated route should prefer limited amounts of walking.fewer_transfers
indicates that the calculated route should prefer a limited number of transfers.Specifies the unit system to use when displaying results.
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.
This example uses latitude/longitude coordinates to specify the destination coordinates:
URLhttps://maps.googleapis.com/maps/api/distancematrix/json ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626 &origins=40.6655101%2C-73.89188969999998 &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'
This example uses plus codes to specify the destination coordinates:
URLhttps://maps.googleapis.com/maps/api/distancematrix/json ?destinations=San%20Francisco &origins=849VCWC8%2BR9 &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'
This example shows the same request using an encoded polyline:
URLhttps://maps.googleapis.com/maps/api/distancematrix/json ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A &origins=40.6655101%2C-73.89188969999998 &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'Traffic information Caution: Requests using traffic information are billed at a higher rate. Learn more about how Distance Matrix API usage is billed.
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):
mode
parameter is driving
, or is not specified (driving
is the default travel mode).departure_time
parameter. The departure_time
can be set to the current time or some time in the future. It cannot be in the past.Optionally, you can include the traffic_model
parameter in your request to specify the assumptions to use when calculating time in traffic.
The following URL initiates a Distance Matrix request for driving distances between Boston, MA or Charlestown, MA, and Lexington, MA and Concord, MA. The request includes a departure time, meeting all the requirements to return the duration_in_traffic
field in the Distance Matrix response.
https://maps.googleapis.com/maps/api/distancematrix/json ?departure_time=now &destinations=Lexington%2CMA%7CConcord%2CMA &origins=Boston%2CMA%7CCharlestown%2CMA &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'JSON
{ "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"], "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"], "rows": [ { "elements": [ { "distance": { "text": "33.3 km", "value": 33253 }, "duration": { "text": "27 mins", "value": 1620 }, "duration_in_traffic": { "text": "34 mins", "value": 2019 }, "status": "OK", }, { "distance": { "text": "41.5 km", "value": 41491 }, "duration": { "text": "33 mins", "value": 1981 }, "duration_in_traffic": { "text": "39 mins", "value": 2342 }, "status": "OK", }, ], }, { "elements": [ { "distance": { "text": "31.1 km", "value": 31100 }, "duration": { "text": "26 mins", "value": 1543 }, "duration_in_traffic": { "text": "29 mins", "value": 1754 }, "status": "OK", }, { "distance": { "text": "39.3 km", "value": 39338 }, "duration": { "text": "32 mins", "value": 1904 }, "duration_in_traffic": { "text": "35 mins", "value": 2077 }, "status": "OK", }, ], }, ], "status": "OK", }XML
<DistanceMatrixResponse> <status>OK</status> <origin_address>Boston, MA, USA</origin_address> <origin_address>Charlestown, Boston, MA, USA</origin_address> <destination_address>Lexington, MA, USA</destination_address> <destination_address>Concord, MA, USA</destination_address> <row> <element> <status>OK</status> <duration> <value>1620</value> <text>27 mins</text> </duration> <distance> <value>33253</value> <text>33.3 km</text> </distance> <duration_in_traffic> <value>2018</value> <text>34 mins</text> </duration_in_traffic> </element> <element> <status>OK</status> <duration> <value>1981</value> <text>33 mins</text> </duration> <distance> <value>41491</value> <text>41.5 km</text> </distance> <duration_in_traffic> <value>2342</value> <text>39 mins</text> </duration_in_traffic> </element> </row> <row> <element> <status>OK</status> <duration> <value>1543</value> <text>26 mins</text> </duration> <distance> <value>31100</value> <text>31.1 km</text> </distance> <duration_in_traffic> <value>1759</value> <text>29 mins</text> </duration_in_traffic> </element> <element> <status>OK</status> <duration> <value>1904</value> <text>32 mins</text> </duration> <distance> <value>39338</value> <text>39.3 km</text> </distance> <duration_in_traffic> <value>2077</value> <text>35 mins</text> </duration_in_traffic> </element> </row> </DistanceMatrixResponse>Location Modifiers Caution: Requests using location modifiers are billed at a higher rate. Learn more about how Distance Matrix API usage is billed
You can use location modifiers to indicate how drivers should approach a particular location, by using the side_of_road
modifier to specify which side of the road to use, or by specifying a heading to indicate the correct direction of travel.
When specifying a location, you can request that the calculated route go through whichever side of the road the waypoint is biased towards by using the side_of_road:
prefix. For example, this request will return the distance for a long route so that the vehicle ends on the side of the road to which the waypoint was biased:
https://maps.googleapis.com/maps/api/distancematrix/json ?destinations=side_of_road%3A37.7663444%2C-122.4412006 &origins=37.7680296%2C-122.4375126 &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'
When using side_of_road:
with encoded polylines, the modifier is applied to every location along the polyline. For example, the two destinations in this request both use the parameter:
https://maps.googleapis.com/maps/api/distancematrix/json ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A &origins=San%20Francisco%20City%20hall &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'
The side_of_road:
modifier may only be used with this restriction:
mode
parameter is driving
, or is not specified (driving
is the default travel mode).When specifying a location, you can request that the calculated route go through the location in a particular heading. This heading is specified with the prefix heading=X:
, where X is an integer degree value between 0 (inclusive) and 360 (exclusive). A heading of 0 indicates North, 90 indicates East, continuing clockwise. For example, in this request the calculated route goes east from the origin, then takes a U-turn:
https://maps.googleapis.com/maps/api/distancematrix/json ?destinations=37.773245%2C-122.469502 &origins=heading%3D90%3A37.773279%2C-122.468780 &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'
The heading=X:
modifier may only be used with these restrictions:
mode
parameter is driving
, bicycling
, or is not specified (driving
is the default travel mode).side_of_road
modifier is not specified for the same location.heading
with addresses, Place IDs, or encoded polylines.A sample HTTP request is shown below, requesting distance and duration from Vancouver, BC, Canada and from Seattle, WA, USA, to San Francisco, CA, USA and to Victoria, BC, Canada.
URLhttps://maps.googleapis.com/maps/api/distancematrix/json ?destinations=San%20Francisco%7CVictoria%20BC &language=fr-FR &mode=bicycling &origins=Vancouver%20BC%7CSeattle &key=YOUR_API_KEYcURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'
This request will return four elements - two origins times two destinations:
Vancouver to San Francisco Vancouver to Victoria Seattle to San Francisco Seattle to VictoriaResults are returned in rows, each row containing one origin paired with each destination.
JSON{ "destination_addresses": ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"], "origin_addresses": ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"], "rows": [ { "elements": [ { "distance": { "text": "1 712 km", "value": 1711765 }, "duration": { "text": "3 jours 16 heures", "value": 318119 }, "status": "OK", }, { "distance": { "text": "140 km", "value": 139695 }, "duration": { "text": "6 heures 49 minutes", "value": 24567 }, "status": "OK", }, ], }, { "elements": [ { "distance": { "text": "1 452 km", "value": 1451704 }, "duration": { "text": "3 jours 2 heures", "value": 266680 }, "status": "OK", }, { "distance": { "text": "146 km", "value": 146500 }, "duration": { "text": "2 heures 53 minutes", "value": 10374 }, "status": "OK", }, ], }, ], "status": "OK", }XML
<DistanceMatrixResponse> <status>OK</status> <origin_address>Vancouver, BC, Canada</origin_address> <origin_address>Seattle, Washington, États-Unis</origin_address> <destination_address>San Francisco, Californie, États-Unis</destination_address> <destination_address>Victoria, BC, Canada</destination_address> <row> <element> <status>OK</status> <duration> <value>318119</value> <text>3 jours 16 heures</text> </duration> <distance> <value>1711765</value> <text>1 712 km</text> </distance> </element> <element> <status>OK</status> <duration> <value>24567</value> <text>6 heures 49 minutes</text> </duration> <distance> <value>139695</value> <text>140 km</text> </distance> </element> </row> <row> <element> <status>OK</status> <duration> <value>266680</value> <text>3 jours 2 heures</text> </duration> <distance> <value>1451704</value> <text>1 452 km</text> </distance> </element> <element> <status>OK</status> <duration> <value>10374</value> <text>2 heures 53 minutes</text> </duration> <distance> <value>146500</value> <text>146 km</text> </distance> </element> </row> </DistanceMatrixResponse>Note: The remainder of this documentation will use JSON syntax. DistanceMatrixResponse Field Required Type Description
destination_addresses
required Array<string>
An array of addresses as returned by the API from your original request. As with origin_addresses
, these are localized if appropriate. This content is meant to be read as-is. Do not programatically parse the formatted addresses.
origin_addresses
required Array<string>
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. This content is meant to be read as-is. Do not programatically parse the formatted addresses.
rows
required Array<DistanceMatrixRow>
An array of elements, which in turn each contain a status
, duration
, and distance
element.
See DistanceMatrixRow for more information.
status
required DistanceMatrixStatus
Contains the status of the request, and may contain debugging information to help you track down why the request failed.
See DistanceMatrixStatus for more information.
error_message
optional string
A string containing the human-readable text of any errors encountered while the request was being processed.
DistanceMatrixStatusStatus codes returned by service.
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.MAX_DIMENSIONS_EXCEEDED
indicates that the number of origins or destinations exceeds the per-query limit.OVER_DAILY_LIMIT
indicates any of the following:
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 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.elements
required Array<DistanceMatrixElement>
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.
See DistanceMatrixElement for more information.
DistanceMatrixElement Field Required Type Descriptionstatus
required DistanceMatrixElementStatus
A status for the element.
See DistanceMatrixElementStatus for more information.
distance
optional TextValueObject
The total distance of this route, expressed in meters (value) and as text. The textual value uses the unit system specified with the unit parameter of the original request, or the origin's region.
See TextValueObject for more information.
duration
optional TextValueObject
The length of time it takes to travel this route, expressed in seconds (the value field) and as text. The textual representation is localized according to the query's language parameter.
See TextValueObject for more information.
duration_in_traffic
optional TextValueObject
The length of time it takes to travel this route, based on current and historical traffic conditions. See the traffic_model
request parameter for the options you can use to request that the returned value is optimistic, pessimistic, or a best-guess estimate. The duration is expressed in seconds (the value field) and as text. The textual representation is localized according to the query's language parameter. The duration in traffic is returned only if all of the following are true:
departure_time
parameter.See TextValueObject for more information.
fare
optional Fare
If present, 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.
See Fare for more information.
FareThe total fare for the route.
{
"currency" : "USD",
"value" : 6,
"text" : "$6.00"
}
Field Required Type Description currency
required string
An ISO 4217 currency code indicating the currency that the amount is expressed in.
text
required string
The total fare amount, formatted in the requested language.
value
required number
The total fare amount, in the currency specified.
DistanceMatrixElementStatusOK
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.An object containing a numeric value and its formatted text representation.
Field Required Type Descriptiontext
required string
String value.
value
required number
Numeric value.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-14 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-14 UTC."],[[["The Google Maps Distance Matrix API calculates travel distance and time between multiple origins and destinations."],["Requests require `origins` and `destinations`, with optional parameters for customizing the results (e.g., `mode`, `avoid`, `language`)."],["The API returns results in JSON or XML format, including distances, durations, and status codes for each origin-destination pair."],["Consider URL length limits, proper encoding, and the use of place IDs for optimal results."],["Departure time and traffic models can be incorporated to provide real-time travel estimates, but incur higher billing costs."]]],["The Distance Matrix API calculates travel time and distance between multiple origins and destinations. Requests use a base URL with parameters specifying locations via addresses, coordinates, place IDs, or encoded polylines. Required parameters include `origins` and `destinations`. Optional parameters like `mode` (driving, walking, etc.), `departure_time`, `arrival_time`, `avoid`, `traffic_model`, and `language` adjust route calculations. Responses, in JSON or XML, are organized in `rows` and `elements`, containing `distance`, `duration`, and `status` data. Location modifiers (`side_of_road`, `heading`) are available. Transit requests provide fare information.\n"]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4