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
orfields
, or by using the HTTP/gRPC headerX-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 onTRAFFIC_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 ofdeparture_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
andTRAFFIC_UNAWARE
options. These options were implicitly set based on whether you setdeparture_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 setTRAFFIC_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 setTRAFFIC_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
andstaticDuration
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
orTRAFFIC_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
|
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. |