Distance Matrix
DistanceMatrixServiceclass
google.maps.DistanceMatrixServiceclass
A service for computing distances between multiple origins and destinations.
Access by callingconst {DistanceMatrixService} = await google.maps.importLibrary("routes").
SeeLibraries in the Maps JavaScript API.
Constructor | |
|---|---|
DistanceMatrixService | DistanceMatrixService()Parameters: None Creates a new instance of a DistanceMatrixService that sends distance matrix queries to Google servers. |
Methods | |
|---|---|
getDistanceMatrix | getDistanceMatrix(request[, callback])Parameters:
Return Value: Promise<DistanceMatrixResponse>Issues a distance matrix request. |
DistanceMatrixRequestinterface
google.maps.DistanceMatrixRequestinterface
A distance matrix query sent by theDistanceMatrixService containing arrays of origin and destination locations, and various options for computing metrics.
Properties | |
|---|---|
destinations | Type: Array<string|LatLng|LatLngLiteral|Place>An array containing destination address strings, or LatLng, orPlace objects, to which to calculate distance and time. Required. |
origins | Type: Array<string|LatLng|LatLngLiteral|Place>An array containing origin address strings, or LatLng, orPlace objects, from which to calculate distance and time. Required. |
travelMode | Type: TravelModeType of routing requested. Required. |
avoidFerriesoptional | Type: booleanoptionalIf true, instructs the Distance Matrix service to avoid ferries where possible. Optional. |
avoidHighwaysoptional | Type: booleanoptionalIf true, instructs the Distance Matrix service to avoid highways where possible. Optional. |
avoidTollsoptional | Type: booleanoptionalIf true, instructs the Distance Matrix service to avoid toll roads where possible. Optional. |
drivingOptionsoptional | Type: DrivingOptionsoptionalSettings that apply only to requests where travelMode isDRIVING. This object will have no effect for other travel modes. |
languageoptional | Type: stringoptionalA language identifier for the language in which results should be returned, when possible. See thelist of supported languages. |
regionoptional | Type: stringoptionalRegion code used as a bias for geocoding requests. The region code accepts accTLD ("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"). |
transitOptionsoptional | Type: TransitOptionsoptionalSettings that apply only to requests where travelMode is TRANSIT. This object will have no effect for other travel modes. |
unitSystemoptional | Type: UnitSystemoptionalPreferred unit system to use when displaying distance. Optional; defaults to metric. |
DistanceMatrixResponseinterface
google.maps.DistanceMatrixResponseinterface
The response to aDistanceMatrixService request, consisting of the formatted origin and destination addresses, and a sequence ofDistanceMatrixResponseRows, one for each corresponding origin address.
Properties | |
|---|---|
destinationAddresses | Type: Array<string>The formatted destination addresses. |
originAddresses | Type: Array<string>The formatted origin addresses. |
rows | Type: Array<DistanceMatrixResponseRow>The rows of the matrix, corresponding to the origin addresses. |
DistanceMatrixResponseRowinterface
google.maps.DistanceMatrixResponseRowinterface
A row of the response to aDistanceMatrixService request, consisting of a sequence ofDistanceMatrixResponseElements, one for each corresponding destination address.
Properties | |
|---|---|
elements | The row's elements, corresponding to the destination addresses. |
DistanceMatrixResponseElementinterface
google.maps.DistanceMatrixResponseElementinterface
A single element of a response to aDistanceMatrixService request, which contains the duration and distance from one origin to one destination.
Properties | |
|---|---|
distance | Type: DistanceThe distance for this origin-destination pairing. This property may be undefined as the distance may be unknown. |
duration | Type: DurationThe duration for this origin-destination pairing. This property may be undefined as the duration may be unknown. |
duration_in_traffic | Type: DurationThe duration for this origin-destination pairing, taking into account the traffic conditions indicated by the trafficModel property. This property may beundefined as the duration may be unknown. Only available to Premium Plan customers whendrivingOptions is defined when making the request. |
fare | Type: TransitFareThe total fare for this origin-destination pairing. Only applicable to transit requests. |
status | The status of this particular origin-destination pairing. |
DistanceMatrixStatusconstants
google.maps.DistanceMatrixStatusconstants
The top-level status about the request in general returned by theDistanceMatrixService upon completion of a distance matrix request. Specify these by value, or by using the constant's name. For example,'OK' orgoogle.maps.DistanceMatrixStatus.OK.
Access by callingconst {DistanceMatrixStatus} = await google.maps.importLibrary("routes").
SeeLibraries in the Maps JavaScript API.
Constants | |
|---|---|
INVALID_REQUEST | The provided request was invalid. |
MAX_DIMENSIONS_EXCEEDED | The request contains more than 25 origins, or more than 25 destinations. |
MAX_ELEMENTS_EXCEEDED | The product of origins and destinations exceeds the per-query limit. |
OK | The response contains a valid result. |
OVER_QUERY_LIMIT | Too many elements have been requested within the allowed time period. The request should succeed if you try again after some 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. |
DistanceMatrixElementStatusconstants
google.maps.DistanceMatrixElementStatusconstants
The element-level status about a particular origin-destination pairing returned by theDistanceMatrixService upon completion of a distance matrix request. These values are specified as strings, for example,'OK'.
Access by callingconst {DistanceMatrixElementStatus} = await google.maps.importLibrary("routes").
SeeLibraries in the Maps JavaScript API.
Constants | |
|---|---|
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. |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-07-18 UTC.