This guide describes how to migrate apps that use either Directions API or Distance Matrix API to using the Routes API. For details on the Routes API, see product overview.
Update the REST API endpoints
Update your code to use the new Routes API endpoints
From Directions API
Directions API | https://maps.googleapis.com/maps/api/directions/outputFormat?parameters |
Routes API | https://routes.googleapis.com/directions/v2:computeRoutes |
From Distance Matrix API
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 HTTPS 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 polyline-encoded waypoints to location waypoints
Specifying waypoints as encoded polylines is available in the Directions API to fit a large number of waypoints in the URL limit of 16384 characters. This feature is not necessary in the Routes API because waypoints can be transmitted in the REST or gRPC request body as latitude/longitude coordinates. For examples, see the HTTP Example in the Compute a route matrix document, or Define an intermediate waypoint in the Specify intermediate waypoints document.
Convert parameters
The following tables lists parameters in the 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.
Request parameter conversions
Directions or Distance matrix parameter | Routes API parameter | Notes |
---|---|---|
alternatives |
computeAlternativeRoutes |
|
arrival_time |
arrivalTime |
Available in TRANSIT mode only, and not at the same
time as departureTime . |
avoid |
routeModifiers |
|
departure_time |
departureTime |
Cannot be used at the same time as arrivalTime . |
language |
languageCode |
Supported for Compute Routes only. |
mode |
travelMode |
Added support for |
region |
regionCode |
|
traffic_model |
trafficModel |
Learn more |
transit_mode |
"travelMode": "TRANSIT" |
In the Directions API, in a transit route, each segment of a trip with the same travel mode (for example, Walk or Transit) is considered to be one step, and individual directions for that travel mode are in substeps. In contrast, In the Routes API, steps are consistently one navigation instruction across all types of travel. So each navigation instruction is a step. For multiple steps in one travel mode, the Routes API provides metadata that contains a summary of the steps for that travel mode, in `stepsOverview`. To request this metadata, use the `routes.legs.stepsOverview` field mask. Learn more. |
transit_routing_preference |
transitRoutingPreference |
Learn more |
units |
Not available for route matrix. | |
waypoints |
intermediates |
Removed support for encoded polylines. |
optimize=true for waypoints |
"optimizeWaypointOrder": "true" |
Learn more |
Response parameter conversions
Directions or Distance matrix parameter | Routes API parameter | Notes |
---|---|---|
copyrights |
Not included in the response. You must include the following statement when displaying the results to your users:
For example:
|
|
distance |
distanceMeters |
Distance is only available in meters. |
duration_in_traffic |
duration |
Removed in the Routes API, use duration . |
status |
Not available. Use the HTTP response codes for errors reported by the API. See Handle request errors for more information. | |
geocoded_waypoints |
geocoding_results |
Supported for Compute Routes only. Contains geocoding response info only for waypoints specified as addresses. |
bounds |
viewport |
|
legs.end_address |
Not available. | |
legs.start_address |
Not available. | |
overview_polyline |
polyline | |
summary |
description |
|
waypoint_order |
optimizedIntermediateWaypointIndex |