The Routes API is currently in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions.

Routes API migration guide

Stay organized with collections Save and categorize content based on your preferences.

Currently, the Google Maps Platform supports the Directions API and Distance Matrix API. This release of the new 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_WHEELER routing
  • Toll calculation
  • Traffic aware polyline
  • Polyline quality controls
  • Quality latency controls
  • Results streaming (Compute Route Matrix using gRPC only)
  • gRPC support

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

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

Functionality changes in the new 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 new 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 new 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 new 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 new 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 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 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 Preview release. Update your code if you are using any of these parameters.

Current parameter Routes API parameter Notes
destination destination Addresses and Plus codes are not available in the Preview release.
origin origin Addresses and Plus codes are not available in the Preview release.
alternatives computeAlternativeRoutes
arrival_time Not available because TRANSIT mode not available in Preview.
avoid routeModifiers
copyrights Not available in the Preview release.
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
mode travelMode

Added support for TWO_WHEELER.

TRANSIT mode not available in Preview.
region Not available in the Preview release because addresses are not supported.
status Not available in the Preview release. Use the HTTP response codes for errors reported by the API. See Handle request errors for more information.
traffic_model Not available in the Preview release.
transit_mode Not available because TRANSIT mode not available in Preview.
transit_routing_preference Not available because TRANSIT mode not available in Preview.
units Not available for Distance Matrix in the Preview release.
waypoints intermediates Addresses and polylines are not available in the Preview release.
optimize=true for waypoints Not available in the Preview release.