Distance Matrix API quick reference

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
  • Overview: Distance Matrix API overview

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 instead.
  • You need new features or a route matrix of up to 625 elements with streamed responses (computeRouteMatrix). Use Routes API instead.
  • You need a full route with steps and polylines between points, not only distance and duration values. Use Routes API instead.

Distance Matrix API: setup

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