Why migrate to Routes API?

The Routes API provides improved performance for calculating directions, distance, and travel time, making it worthwhile to replace apps that currently use Directions API and Distance Matrix API. Most of the functionality of Routes API is backward compatible with both Directions API and Distance Matrix API.

Use this guide to understand key differences in Routes API compared to the products it replaces, along with how to handle necessary changes. For more details on other Routes API features, see theproduct overview.

Key improvements

This section covers some of the enhancements you can expect when using Routes API in your apps.

Increased request limits

Routes API	Maximum of 625 elements, unless you specify`TRAFFIC_AWARE_OPTIMAL`. Maximum of 100 elements with`TRAFFIC_AWARE_OPTIMAL`.See Enhanced routing preferences. Maximum of 50 waypoints (origins + destinations) using a Place ID.
Distance Matrix API	Maximum of 25 origins or 25 destinations per request. Maximum 100 elements (number of origins × number of destinations) per server-side request.

Faster request responses

The compute route matrix feature offers the following latency improvements:

Receive streaming elements of the responsebefore the entire matrix has been calculated.
Use field masks to customize the response details,requesting only the data you need, a best-practice that also helps reduce your cost.
Enhanced route calculations for traffic,so you can make the tradeoff between data quality and response time.

Routing enhancements

The compute route feature offers these routing enhancements:

Toll informationin addition to distance and ETA.
2-wheel vehicle routes.
Qualify your stopover waypointsfor safety.
Increased ETA accuracyby setting direction of travel and side of road for waypoints.

Request only the data that you need

You now specify which fields to return, reducing processing time and billing charges.

Routes API	Your requests must use a field mask to specify which fields you want returned in the response. Field masking ensures that you do not request unnecessary data, which avoids unnecessary processing time and billing charges. For more information, see Choose fields to return.
Directions API Distance Matrix API	Returns a default list of fields, even if your app does not strictly need them. This can result in unnecessary processing time and billing charges.

Enhanced route computations for traffic

The Routes API supports three routing preferences that you can use to balance between response latency and data quality when requesting traffic information.

For more information, see Configure quality vs 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` (new)	Performance-optimized live traffic quality for reduced latency. In contrast to`TRAFFIC_AWARE_OPTIMAL`,this setting applies optimizations to significantly reduce latency. This setting is also new for the Routes API with no equivalent in the Directions API or the Distance Matrix API.
`TRAFFIC_AWARE_OPTIMAL`	High quality, comprehensive traffic data. This setting produces the highest latency and is equivalent to the`departure_time` setting in the Directions API and Distance Matrix API. This preference is equivalent to the mode used by maps.google and by the Google Maps mobile app.

Route computation comparison

The following table compares routing options between theRoutes API and theDirections APIandDistance Matrix API services.

Traffic option Routes API Directions API
Distance Matrix API Latency

No real-time traffic TRAFFIC_UNAWARE departure_timeproperty not set Fastest latency of the three modes.

Live traffic conditions applied

Traffic option	Routes API	Directions API Distance Matrix API	Latency
No real-time traffic	`TRAFFIC_UNAWARE`	`departure_time`property not set	Fastest latency of the three modes.
Live traffic conditions applied	`TRAFFIC_AWARE`	No equivalent	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	`TRAFFIC_AWARE_OPTIMAL`	`departure_time`property set	Equivalent to the mode used by maps.google 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.

TRAFFIC_AWARE

No equivalent

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

It has a much lower latency thanTRAFFIC_AWARE_OPTIMAL.

High quality, comprehensive live traffic data applied

TRAFFIC_AWARE_OPTIMAL

departure_timeproperty set

Equivalent to the mode used by maps.google 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.

Key differences

This section covers key differences between Routes API and the services it replaces, along with ways you can address these differences when migrating from these services in your existing apps.

Call one service instead of two

Routes API	Enable only one service in the API Console for your app to use Compute Routes and Compute Route Matrix. For more information, seeSet Up in the Google API Console.
Directions API Distance Matrix API	Enable two services: Directions API and Distance Matrix API as separate services in the API Console.

Uses`HTTPS POST`requests

Routes API	Pass parameters in the request body or in headers as part of an`HTTP POST`request. For examples, see: -Compute a route -Compute a route matrix
Directions API Distance Matrix API	Pass URL parameters using an`HTTP GET`request.

ETA response differences

The Routes API returns ETA and uses thedurationresponse property differently than the Directions API and Distance Matrix API services as shown in the table below.

Type of ETA Routes API Directions API
Distance Matrix API

Traffic unaware, time-independent ETA.

Type of ETA	Routes API	Directions API Distance Matrix API
Traffic unaware, time-independent ETA.	Set using`TRAFFIC_UNAWARE`. ETA contained in the`duration`response property. The`duration`and`staticDuration` response properties contain the same value.	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.
ETA that takes real-time traffic into consideration.	Set using`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.	Set using`departure_time`in the request. ETA taking real-time traffic into consideration is contained in the`duration_in_traffic`response property.

Set usingTRAFFIC_UNAWARE.

ETA contained in thedurationresponse property.
ThedurationandstaticDuration response properties contain the same value.

Corresponds todeparture_timenot being set in the request.

ETA contained in thedurationresponse property.
Theduration_in_trafficresponse property is not returned.

ETA that takes real-time traffic into consideration.

Set usingTRAFFIC_AWAREor TRAFFIC_AWARE_OPTIMAL.

ETA taking real-time traffic into consideration is contained in thedurationresponse property.
ThestaticDurationresponse property contains the duration of traveling through the route without taking traffic conditions into consideration.
Theduration_in_trafficproperty is no longer returned.

Set usingdeparture_timein the request.

ETA taking real-time traffic into consideration is contained in theduration_in_trafficresponse property.

Polyline waypoints

You no longer need to convert your latitude/longitude coordinates to polyline waypoints with this service, which supports a POST request body and is therefore no longer impacted by URL string limits. Some users of Distance Matrix API addressed the request limits issue by converting latitude/longitude points to polyline waypoints.

Formatted addresses (reverse geocode)

The Routes API does not provided formatted addresses in the response. To obtain formatted addresses, use the Geocoding API which is built for this use case and provides higher quality results.

Available travel modes

As is the case with Directions API, the Routes API uses DRIVE as the default mode when a route request does not specify a travel mode. However, when a request does specify a travel mode for a route, the Routes API does not return an array of available travel modes as alternative choices for the request. If your use case relies on this feature,file an issue describing how you use the feature, so we can follow up.

XML as a response format

The Routes API does not provide XML as a response format. You can find a number of JSON to XML converters online that should suit your purposes.