Routes API migration guide

Currently, the Google Maps Platform supports the Directions API and Distance Matrix API. This release of the Routes API contains the next generation, performance optimized version of the existing Directions API and Distance Matrix API:

  • Compute Routes: Calculate directions between locations with comprehensive, global routing data and real-time traffic.
  • Compute Route Matrix: Calculate distance and travel time for a list of origin/destination pairs.

Routes API include many new capabilities, including:

  • Two-wheel vehicle routing
  • Toll calculation
  • Traffic aware polyline
  • Polyline quality controls
  • Quality latency controls
  • Eco-friendly routes
  • Results streaming (Compute Route Matrix using gRPC only)
  • gRPC support

For more information on the Routes API, see product overview.

This guide describes how to migrate your existing apps that use the Directions API and Distance Matrix API to use the Routes API.

Functionality changes in the Routes API

At a high level, the Routes API makes the following changes to the Directions API and Distance Matrix API:

  • Consolidating Compute Routes and Compute Route Matrix under single service called the Routes API

    You must enable the Routes API in the API Console before you can use Compute Routes and Compute Route Matrix. Currently, you enable Directions API and Distance Matrix API as separate services in the API Console.

    For more information, see Set Up in the Google API Console.

  • New Routes API uses HTTP POST requests

    In the Routes API, you pass parameters in the request body or in headers as part of an HTTP POST request. In contrast, with the Directions API and Distance Matrix API, you pass URL parameters using an HTTP GET request.

    For examples, see:

  • Field masking is required

    When you call the Routes API to compute a route or compute a route matrix, you must specify which fields you want returned in the response. There is no default list of returned fields. If you omit this list, the methods return an error.

    Specify the field list by creating a response field mask. You then pass the response field mask to each method by using the URL parameter $fields or fields, or by using the HTTP/gRPC header X-Goog-FieldMask.

    Field masking is a good design practice to ensure that you do not request unnecessary data, which helps to avoid unnecessary processing time and billing charges.

    For more information, see Choose fields to return.

  • New request limits for the Compute Route Matrix

    The Distance Matrix API enforced the following request limits:

    • Maximum of 25 origins or 25 destinations per request.
    • Maximum 100 elements (number of origins × number of destinations) per server-side request.

    The Compute Route Matrix enforces the following request limits:

    • The number of elements cannot exceed 625.

    • If you specify TRAFFIC_AWARE_OPTIMAL, then the number of elements cannot exceed 100. For more on TRAFFIC_AWARE_OPTIMAL, see Configure quality vs latency.

    • The maximum number of waypoints (origins + destinations) that you can specify by using a Place ID is 50.

  • New options for configuring quality versus latency

    The Routes API supports three routing preferences that you can use to explicitly configure route quality versus response latency:

    • TRAFFIC_UNAWARE (default) - Uses average time-independent traffic data, not live traffic data, to calculate the route, resulting in lowest response latency. This setting is equivalent to when traffic is not used in the Directions API and Distance Matrix API.

    • TRAFFIC_AWARE - Performance-optimized live traffic quality for reduced latency. This setting is new for the Routes API and has no equivalent in the Directions API and the Distance Matrix API.

      In contrast to TRAFFIC_AWARE_OPTIMAL, some optimizations are applied to significantly reduce latency.

    • TRAFFIC_AWARE_OPTIMAL - High quality, comprehensive traffic data without applying most performance optimizations. This setting produces the highest latency and is equivalent to the setting of departure_time in the Directions API and Distance Matrix API.

      The TRAFFIC_AWARE_OPTIMAL routing preference is equivalent to the mode used by maps.google.com and by the Google Maps mobile app.

    In the Directions API and Distance Matrix API, we only provide the equivalent of the TRAFFIC_AWARE_OPTIMAL and TRAFFIC_UNAWARE options. These options were implicitly set based on whether you set departure_time.

    The following table compares the current Directions API and Distance Matrix API options and with the Routes API options:

    Mode Current Routes API Notes
    No real-time traffic departure_time property not set TRAFFIC_UNAWARE Fastest latency of the three modes.
    Live traffic conditions applied No equivalent TRAFFIC_AWARE

    New mode added by the Routes API. It provides a slightly greater latency than TRAFFIC_UNAWARE with a small cost of ETA quality.

    It has a much lower latency than TRAFFIC_AWARE_OPTIMAL.
    High quality, comprehensive live traffic data applied departure_time property set TRAFFIC_AWARE_OPTIMAL

    Equivalent to the mode used by maps.google.com and by the Google Maps mobile app.

    For Compute Route Matrix, the number of elements in a request (number of origins × number of destinations) cannot exceed 100.

    Routes API also modify the way the duration response property is set, and modifies the properties returned in the current Directions API and Distance Matrix API response, as shown in the following table:

    Type of travel ETA Current Routes API
    Traffic unaware, time-independent ETA.

    Corresponds to departure_time not being set in the request.

    • ETA contained in the duration response property.
    • The duration_in_traffic response property is not returned.

    Corresponds to TRAFFIC_UNAWARE.

    • ETA contained in the duration response property.
    • The duration and staticDuration response properties contain the same value.
    ETA that takes real-time traffic into consideration.

    Corresponds to setting departure_time in the request.

    • ETA taking real-time traffic into consideration is contained in the duration_in_traffic response property.

    Corresponds to TRAFFIC_AWARE or TRAFFIC_AWARE_OPTIMAL.

    • ETA taking real-time traffic into consideration is contained in the duration response property.
    • The staticDuration response property contains the duration of traveling through the route without taking traffic conditions into consideration.
    • The duration_in_traffic property is no longer returned.

    For more information, see Configure quality vs latency.

Existing features not supported in Routes API

The following features will not be supported in Routes API:

  • XML as a response format. Only JSON and gRPC are supported.

  • Reverse geocoding

    You now use the Reverse Geocoding API for this functionality, which is built for this use case and provides higher quality results.

Migrate to Routes API

We have made several changes in the Routes API. Most of the changes are backward compatible with current APIs but there are a few breaking changes listed below that require your attention when migrating apps to the Routes API.

Update the REST API endpoints

If you are using the Directions API, update your code to use the new Routes API endpoint:

Directions API https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
Routes API https://routes.googleapis.com/directions/v2:computeRoutes

If you are using the Distance Matrix API, update your code to use the new Routes API endpoint:

Distance Matrix API https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
Routes API https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

Convert URL parameters to use an HTTP request body

With Directions API and Distance Matrix API, you pass configuration properties as URL parameters to an HTTP GET request. For example, for the Directions API:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

With the Routes API, you pass parameters in a request body or in headers as part of an HTTP POST request. For examples, see:

Convert waypoints represented as encoded polylines to intermediate waypoints

Specifying waypoints as encoded polylines is available in the Directions API to fit a large number of waypoints in the URL limit of 8192 characters. This feature is not necessary in the Routes API because waypoints can be transmitted in the REST or gRPC requests body as intermediate waypoints.

Convert current parameters to Routes API parameters

The following table lists parameters in the current Directions API and Distance Matrix API that have been renamed or modified, or parameters that are not supported in the GA release. Update your code if you are using any of these parameters.

Current parameter Routes API parameter Notes
alternatives computeAlternativeRoutes
arrival_time Not available because TRANSIT mode not available.
avoid routeModifiers
copyrights

Not included in the response. You must include the following statement when displaying the results to your users:

Powered by Google, ©YEAR Google

For example:

Powered by Google, ©2022 Google
departure_time departureTime
distance distanceMeters Distance is only available in meters.
duration_in_traffic Removed in the Routes API, use duration. For more information, see Functionality changes for the new Routes API above.
language languageCode Supported for Compute Routes only.
mode travelMode

Added support for TWO_WHEELER.

TRANSIT mode not available.
region regionCode

status Not available. Use the HTTP response codes for errors reported by the API. See Handle request errors for more information.
traffic_model Not available.
transit_mode Not available because TRANSIT mode not available.
transit_routing_preference Not available because TRANSIT mode not available.
units Not available for route matrix.
waypoints intermediates Removed support for encoded polylines.
optimize=true for waypoints Not available.

Migrating from the Preview release

The Routes API was released as a public Preview (pre-GA) in September of 2022. Pre-GA Offerings are covered by the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions.

This section describes how to migrate an app from the Preview release to the GA release.

New features added to the GA release

The GA release adds the following new features that were not included in the Preview:

  • Along with place IDs and latitude/longitude coordinates, you can now specify a location in the GA release by using:

    • Address strings ("Chicago, IL" or "Darwin, NT, Australia")

      Address strings are often how a user inputs an address. However, {product_name} must first geocode the address string internally to convert it to latitude/longitude coordinates before it can calculate a route.

      In addition, support for the regionCode request parameter has been added, which lets you specify to return geocoded results for a specific geographic region.

    • Plus Codes

      Plus Codes are like street addresses for people or places that don't have an actual address. Instead of addresses with street names and numbers, Plus Codes are based on latitude and longitude, and are displayed as numbers and letters.

  • The compute routes response now contains the geocodingResults array. For every location in the request (origin, destination, or intermediate waypoint) that was specified as an address string or as a Plus code, the API performs a place ID lookup. Each element of this array contains the place ID corresponding to a location along with additional metadata about the location. Locations in the request specified as a place ID or as latitude/longiiture coordinates are ignored.

Changes to existing Preview features

You must now explicitly enable the following features in the GA by adding the new array extraComputations field to the request:

In the Preview release, you used a field mask to specify to return information for these features in the response. Now, you must both:

  • Set the new extraComputations array request parameter to enable these features.
  • Set a field mask to specify to return the information in the response.

What do I need to know?

The following fields will no longer be included in computeRouteMatrix responses unless explicitly enabled by setting extraComputations:

  • travelAdvisory.tollInfo (Toll info)

The following fields will no longer be included in computeRoutes responses unless explicitly enabled by setting extraComputations:

  • routes.legs.travelAdvisory.tollInfo(Toll info)
  • routes.travelAdvisory.tollInfo(Toll info)
  • routes.travelAdvisory.fuelConsumptionMicroliters(Fuel consumption)
  • routes.travelAdvisory.speedReadingIntervals(Traffic on a polyline)
  • routes.legs.travelAdvisory.speedReadingIntervals(Traffic on a polyline)

What do I need to do?

To receive the response fields for toll info, fuel consumption, or traffic on a polyline, you must set the new request array field, extraComputations, to include one or more of the following values: