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 the product 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 |
|
Distance Matrix API |
|
Faster request responses
The compute route matrix feature offers the following latency improvements:
- Receive streaming elements of the response before 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 information in addition to distance and ETA.
- 2-wheel vehicle routes.
- Qualify your stopover waypoints for safety.
- Increased ETA accuracy by 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.com and by the Google Maps mobile app. |
Route computation comparison
The following table compares routing options between the Routes API and the Directions API and Distance Matrix API services.
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 It has a much lower latency than |
High quality, comprehensive live traffic data applied | TRAFFIC_AWARE_OPTIMAL |
departure_time property set |
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. |
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, see Set 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 the duration
response 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. | Set using
|
Corresponds to
|
ETA that takes real-time traffic into consideration. | Set using
|
Set using
|
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.