<iframe src="https://developers.devsite.google/frame/maps/documentation/javascript/reference/distance-matrix_874c0a4fe4bf46891e9604ab72a45b2d296d3355bd21d52333fae66496772879.frame" class="framebox inherit-locale redirect-iframe" allow="clipboard-write https://developers.devsite.google" allowfullscreen is-upgraded></iframe>

## [DistanceMatrixService](https://developers.google.com/maps/documentation/javascript/reference/distance-matrix.md.txt#DistanceMatrixService)
class


class
`google.maps.DistanceMatrixService`

library `"routes"`

> [!WARNING]
> **[Deprecated:](https://developers.google.com/maps/deprecations.md.txt)** google.maps.DistanceMatrixService is deprecated as of February 25th, 2026. At this time, google.maps.DistanceMatrixService is not scheduled to be discontinued and will continue to receive bug fixes for any major regressions. At least 12 months notice will be given before support is discontinued. Please see <https://developers.google.com/maps/legacy> for additional details.

```javascript
const {DistanceMatrixService} = await google.maps.importLibrary("routes");
```

| ### 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:** - `request: DistanceMatrixRequest` - `callback: function(DistanceMatrixResponse optional, DistanceMatrixStatus): void optional` **Return Value:** `Promise<DistanceMatrixResponse>` Issues a distance matrix request. |

## [DistanceMatrixRequest](https://developers.google.com/maps/documentation/javascript/reference/distance-matrix.md.txt#DistanceMatrixRequest)
interface


interface
`google.maps.DistanceMatrixRequest`

A distance matrix query sent by the `DistanceMatrixService` 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`, or `Place` objects, to which to calculate distance and time. Required. |
| `origins` | **Type:** `Array<string|LatLng|LatLngLiteral|Place>` An array containing origin address strings, or `LatLng`, or `Place` objects, from which to calculate distance and time. Required. |
| `travelMode` | **Type:** `TravelMode` Type of routing requested. Required. |
| `avoidFerries` optional | **Type:** `boolean optional` If `true`, instructs the Distance Matrix service to avoid ferries where possible. Optional. |
| `avoidHighways` optional | **Type:** `boolean optional` If `true`, instructs the Distance Matrix service to avoid highways where possible. Optional. |
| `avoidTolls` optional | **Type:** `boolean optional` If `true`, instructs the Distance Matrix service to avoid toll roads where possible. Optional. |
| `drivingOptions` optional | **Type:** `DrivingOptions optional` Settings that apply only to requests where `travelMode` is `DRIVING`. This object will have no effect for other travel modes. |
| `language` optional | **Type:** `string optional` A language identifier for the language in which results should be returned, when possible. See the [list of supported languages](https://developers.google.com/maps/faq.md.txt#languagesupport). |
| `region` optional | **Type:** `string optional` Region code used as a bias for geocoding requests. The region code accepts a [ccTLD ("top-level domain")](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains#Country_code_top-level_domains) 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"). |
| `transitOptions` optional | **Type:** `TransitOptions optional` Settings that apply only to requests where `travelMode` is TRANSIT. This object will have no effect for other travel modes. |
| `unitSystem` optional | **Type:** `UnitSystem optional` Preferred unit system to use when displaying distance. Optional; defaults to metric. |

## [DistanceMatrixResponse](https://developers.google.com/maps/documentation/javascript/reference/distance-matrix.md.txt#DistanceMatrixResponse)
interface


interface
`google.maps.DistanceMatrixResponse`

The response to a `DistanceMatrixService` request, consisting of the formatted origin and destination addresses, and a sequence of `DistanceMatrixResponseRow`s, 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. |

## [DistanceMatrixResponseRow](https://developers.google.com/maps/documentation/javascript/reference/distance-matrix.md.txt#DistanceMatrixResponseRow)
interface


interface
`google.maps.DistanceMatrixResponseRow`

A row of the response to a `DistanceMatrixService` request, consisting of a sequence of `DistanceMatrixResponseElement`s, one for each corresponding destination address.

| ### Properties ||
|---|---|
| `elements` | **Type:** `Array<DistanceMatrixResponseElement>` The row's elements, corresponding to the destination addresses. |

## [DistanceMatrixResponseElement](https://developers.google.com/maps/documentation/javascript/reference/distance-matrix.md.txt#DistanceMatrixResponseElement)
interface


interface
`google.maps.DistanceMatrixResponseElement`

A single element of a response to a `DistanceMatrixService` request, which contains the duration and distance from one origin to one destination.

| ### Properties ||
|---|---|
| `distance` | **Type:** `Distance` The distance for this origin-destination pairing. This property may be undefined as the distance may be unknown. |
| `duration` | **Type:** `Duration` The duration for this origin-destination pairing. This property may be undefined as the duration may be unknown. |
| `duration_in_traffic` | **Type:** `Duration` The duration for this origin-destination pairing, taking into account the traffic conditions indicated by the `trafficModel` property. This property may be `undefined` as the duration may be unknown. Only available to Premium Plan customers when `drivingOptions` is defined when making the request. |
| `fare` | **Type:** `TransitFare` The total fare for this origin-destination pairing. Only applicable to transit requests. |
| `status` | **Type:** `DistanceMatrixElementStatus` The status of this particular origin-destination pairing. |

## [DistanceMatrixStatus](https://developers.google.com/maps/documentation/javascript/reference/distance-matrix.md.txt#DistanceMatrixStatus)
constants


constants
`google.maps.DistanceMatrixStatus`

library `"routes"`

The top-level status about the request in general returned by the `DistanceMatrixService` upon completion of a distance matrix request. Specify these by value, or by using the constant's name. For example, `'OK'` or `google.maps.DistanceMatrixStatus.OK`.

These constants are also usable as strings. In TypeScript, the string literals are defined by the `DistanceMatrixStatusString` type.

```javascript
const {DistanceMatrixStatus} = await google.maps.importLibrary("routes");
```

| ### 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. |

## [DistanceMatrixElementStatus](https://developers.google.com/maps/documentation/javascript/reference/distance-matrix.md.txt#DistanceMatrixElementStatus)
constants


constants
`google.maps.DistanceMatrixElementStatus`

library `"routes"`

The element-level status about a particular origin-destination pairing returned by the `DistanceMatrixService` upon completion of a distance matrix request. These values are specified as strings, for example, `'OK'`.

These constants are also usable as strings. In TypeScript, the string literals are defined by the `DistanceMatrixElementStatusString` type.

```javascript
const {DistanceMatrixElementStatus} = await google.maps.importLibrary("routes");
```

| ### 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. |