Routes API quick reference

The Routes API is a web service with two methods: Compute Routes returns a route between two locations with optional intermediate waypoints, and Compute Route Matrix returns travel distance and time for combinations of origins and destinations (up to 625 route elements).

Routes API: key facts

  • Product: Routes API
  • Also known as: Routes API v2, Compute Routes, Compute Route Matrix
  • Category: Routes
  • Platform: Web service (REST)
  • Runs on: Server (backend code)
  • Launch stage: GA
  • Lifecycle: Active
  • Overview: Routes API overview
  • Regional availability: Global. Two-wheeler routing, eco-friendly routes, and toll calculation are limited to supported countries and cities, and dependent territories with their own CLDR code aren't supported unless listed. For European Economic Area (EEA) billing addresses, the EEA terms at https://developers.google.com/maps/comms/eea/routes prohibit using route descriptions or steps with any map. (coverage details)

Routes API: when to use it

Use Routes API when:

  • You need a route between an origin and destination, with optional intermediate waypoints, for driving, walking, cycling, two-wheeler, or transit.
  • You need travel distances and times for many origin-destination pairs in one request (up to 625 elements).
  • You need toll fee estimates (select cities), eco-friendly routes (select regions), traffic-aware polylines, or large vehicle routing (limited availability).
  • You're migrating a server app off the legacy Directions API or Distance Matrix API.

Don't use Routes API when:

  • You need to optimize load assignments and stop ordering for a whole fleet of vehicles. Use Route Optimization API instead.
  • You need in-app turn-by-turn navigation on Android that follows a computed route. Use Navigation SDK for Android instead.
  • You need in-app turn-by-turn navigation on iOS that follows a computed route. Use Navigation SDK for iOS instead.

Routes API: setup

Official Routes API packages:

  • npm: @googlemaps/routing
  • pypi: google-maps-routing
  • go: cloud.google.com/go/maps
  • maven: com.google.maps:google-maps-routing

Routes API: common mistakes

  • Problem: There's no default list of returned fields; requests without a field mask (X-Goog-FieldMask header or $fields parameter) return an error. Fix: Always send a field mask listing the response fields you need. See /maps/documentation/routes/choose_fields.
  • Problem: Using the wildcard field mask (*) in production raises cost and latency, and cost can rise unexpectedly as new advanced features are added to the response. Fix: Use * only during development; in production request only the fields you need. See /maps/documentation/routes/choose_fields.
  • Problem: Toll info and fuel consumption aren't returned just by adding them to the field mask; since GA they must be enabled explicitly. Fix: Add the extraComputations array (for example TOLLS, FUEL_CONSUMPTION) to the request in addition to the field mask. See /maps/documentation/routes/migrate-routes-preview.
  • Problem: Compute Route Matrix allows 625 elements, but only 100 elements when routingPreference is TRAFFIC_AWARE_OPTIMAL. Fix: Keep origins x destinations at or below 100 when using TRAFFIC_AWARE_OPTIMAL, or split the request. See /maps/documentation/routes/compute_route_matrix.

What you can do with Routes API

See the guides linked below for each task, or compare across products in the Capabilities Explorer.