> [!CAUTION]
> **Legacy product:** Distance Matrix API is Legacy as of 2025-03-01. Use [Routes API](https://developers.google.com/maps/documentation/routes/quick-reference.md.txt) instead. See the [migration guide](https://developers.google.com/maps/documentation/routes/migrate-routes.md.txt).

Distance Matrix API (Legacy) is a web service that returns travel distance and time for a matrix of origins and destinations, based on the recommended route between each pair. You can set the travel mode (driving, walking, bicycling, transit), transit modes, units, and departure time for traffic-based durations. It returns JSON or XML.

## Distance Matrix API: key facts

- **Product:** Distance Matrix API
- **Also known as:** Distance Matrix API (Legacy), Distance Matrix (Legacy)
- **Category:** Routes
- **Platform:** Web service (REST)
- **Runs on:** Server (backend code)
- **Launch stage:** GA
- **Lifecycle:** Legacy
- **Replaced by:** [Routes API](https://developers.google.com/maps/documentation/routes/quick-reference.md.txt)
- **Overview:** [Distance Matrix API overview](https://developers.google.com/maps/documentation/distance-matrix/overview.md.txt)

## Distance Matrix API: when to use it

**Use Distance Matrix API when:**

- You maintain an existing project that already has Distance Matrix API (Legacy) enabled and calls `/maps/api/distancematrix`.
- You need travel distance and time between each of several origins and each of several destinations from a server.
- You need durations in traffic for driving, using `departure_time` and an optional `traffic_model`.
**Don't use Distance Matrix API when:**

- You're starting a new Google Cloud project. As of October 2026, Distance Matrix API (Legacy) can't be enabled for new projects. Use [Routes API](https://developers.google.com/maps/documentation/routes/quick-reference.md.txt) instead.
- You need new features or a route matrix of up to 625 elements with streamed responses (`computeRouteMatrix`). Use [Routes API](https://developers.google.com/maps/documentation/routes/quick-reference.md.txt) instead.
- You need a full route with steps and polylines between points, not only distance and duration values. Use [Routes API](https://developers.google.com/maps/documentation/routes/quick-reference.md.txt) instead.

## Distance Matrix API: setup

- **Service to enable:** `distance-matrix-backend.googleapis.com`
- **Authentication:** API key
- **Get started:** [Set up Distance Matrix API](https://developers.google.com/maps/documentation/distance-matrix/start.md.txt)
- **Reference:** [Distance Matrix API reference](https://developers.google.com/maps/documentation/distance-matrix/distance-matrix.md.txt)
- **Pricing:** [Distance Matrix API usage and billing](https://developers.google.com/maps/documentation/distance-matrix/usage-and-billing.md.txt)
- **Policies:** [Distance Matrix API policies](https://developers.google.com/maps/documentation/distance-matrix/policies.md.txt)
- **Release notes:** [Distance Matrix API release notes](https://developers.google.com/maps/documentation/distance-matrix/releases.md.txt)

## Distance Matrix API: common mistakes

- **Problem:** Each server-side request is limited to 100 elements (origins × destinations) and to 25 origins or 25 destinations. Larger requests return `MAX_ELEMENTS_EXCEEDED` or `MAX_DIMENSIONS_EXCEEDED`. **Fix:** Split the matrix into requests of no more than 100 elements and 25 origins or destinations. See [/maps/documentation/distance-matrix/usage-and-billing#usage-limits](https://developers.google.com/maps/documentation/distance-matrix/usage-and-billing.md.txt#usage-limits).
- **Problem:** If you don't specify `departure_time`, the route and duration are based on average time-independent traffic, and no `duration_in_traffic` is returned. Results can vary over time. **Fix:** Set `departure_time` to `now` or a future time with `mode=driving` to get traffic-aware durations. Note that traffic requests are billed at a higher rate. See [/maps/documentation/distance-matrix/distance-matrix](https://developers.google.com/maps/documentation/distance-matrix/distance-matrix.md.txt).
- **Problem:** The `units` parameter changes only the text in distance fields. The distance value is always in meters. **Fix:** Read `distance.value` as meters, or use `distance.text` for display. See [/maps/documentation/distance-matrix/distance-matrix](https://developers.google.com/maps/documentation/distance-matrix/distance-matrix.md.txt).
- **Problem:** Calling Distance Matrix API (Legacy) from a project where it isn't enabled returns `REQUEST_DENIED` in `status` and an `error_message` linking to `LegacyApiNotActivatedMapError`. AI assistants often generate legacy-API code by default. **Fix:** Migrate to the Routes API `computeRouteMatrix` (with the `X-Goog-FieldMask` header). Activate the legacy API by form only as a short-term measure. See [/maps/legacy#LegacyApiNotActivatedMapError](https://developers.google.com/maps/legacy.md.txt#LegacyApiNotActivatedMapError).