Intermediate waypoints are the non-terminal waypoints that make up a route.
Use the intermediates
array property of the
computeRoutes method (REST) or the
ComputeRoutes
method (gRPC), to define up to a maximum of 25 intermediate waypoints.
For each intermediate waypoint in the request, the
Route object (REST) or
Route object (gRPC) in the
response adds an entry to the legs
array to provide the details for
that leg of the journey.
Each leg of a route is represented by a
RouteLeg (REST) or
RouteLeg (gRPC) object.
Control which RouteLeg
fields to return by using the
response field mask.
Define an intermediate waypoint
The following example uses the intermediates
array property to add a single
intermediate waypoint to the POST request body of a route.
In this example, you use a response field mask in the X-Goog-FieldMask
header that
specifies to return the following fields in the response:
routes.duration
routes.distanceMeters
routes.legs
corresponding to the entireRouteLeg
object.
curl -X POST -d '{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } }, "sideOfRoad": true }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, "intermediates": [ { "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0807784 } } } ], "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE", "departureTime": "2022-10-15T15:01:23.045123456Z", "computeAlternativeRoutes": false, "routeModifiers": { "avoidTolls": false, "avoidHighways": false, "avoidFerries": false }, "languageCode": "en-US", "units": "IMPERIAL" }' -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs' 'https://routes.googleapis.com/directions/v2:computeRoutes'
The response from this call contains the legs
array. Each step of the leg is
represented by a
RouteLegStep (REST) or
RouteLegStep (gRPC) object.
{ "routes": [ { "legs": [ # First leg { "distanceMeters": 207, "duration": "89s", "staticDuration": "89s", "polyline": { "encodedPolyline": "ipkcFjgchVd@@@cF]@@oCK?" }, "startLocation": { "latLng": { "latitude": 37.4197318, "longitude": -122.0826233 } }, "endLocation": { "latLng": { "latitude": 37.419734, "longitude": -122.08077919999998 } }, "steps": [ { "distanceMeters": 21, "staticDuration": "6s", "polyline": { "encodedPolyline": "ipkcFjgchVd@@" }, "startLocation": { "latLng": { "latitude": 37.4197318, "longitude": -122.0826233 } }, "endLocation": { "latLng": { "latitude": 37.41954, "longitude": -122.08262750000002 } } }, ... }, # Second leg { "distanceMeters": 598, "duration": "159s", "staticDuration": "159s", "polyline": { "encodedPolyline": "ipkcFz{bhVh@??{@xPBP?J}E{E?" }, "startLocation": { "latLng": { "latitude": 37.419734, "longitude": -122.08077919999998 } }, "endLocation": { "latLng": { "latitude": 37.417616599999995, "longitude": -122.07938820000001 } }, "steps": [ { ...
Define a pass-through waypoint
By default, intermediate waypoints are used for stopping to pickup and drop-off, but you can also specify that an intermediate waypoint is meant just for passing through.
A route that contains an origin waypoint, a pass-through intermediate waypoint, and a destination waypoint contains just one route leg that connects the origin and the destination, while passing through the intermediate via waypoint.
Configure an intermediate waypoint to be a pass-through waypoint by
setting the via
property of the waypoint to true
using either
Waypoint (REST) or
Waypoint (gRPC).
The via
property is most effective when creating routes in response to
the user dragging the waypoints on the map. Doing so allows the user to see how
the final route may look in real-time and helps ensure that waypoints are placed
in locations that are accessible to the Compute Routes.
The following example demonstrates how to mark an intermediate waypoint as a pass-through waypoint.
{ "location": { "latLng": { "latitude":37.419734, "longitude":-122.0827784 } }, "via": true }
Access place IDs for intermediate waypoints
If you specify the location of an origin, destination, or intermediate waypoint
as an address string or as a Plus code, the API attempts to find the
most relevant location which has a corresponding place ID. The
geocodingResults.intermediates
array in the results contains the place ID corresponding to the location of the
waypoints, along with additional data about the location.
For each element of the intermediates
array, use the
intermediateWaypointRequestIndex
property to determine which intermediate
waypoint in the request corresponds to the place ID in the response.
For example:
You specify three intermediate waypoints in a request. Two of these waypoints are specified by address strings and one by latitude/longitude coordinates.
You include
geocodingResults
in the response field mask to specify to return thegeocodingResults
array in the results.
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "intermediates": [ { "address": "450 Serra Mall, Stanford, CA 94305, USA" }, { "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0807784 } } }, { "address": "1836 El Camino Real, Redwood City, CA 94063" } ], "travelMode": "DRIVE", }' -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,geocodingResults' 'https://routes.googleapis.com/directions/v2:computeRoutes'
The response includes the geocodingResults
array containing the place ID for
the origin, destination, and for two of the three waypoints. These are the
waypoints at index 0 and 2 of the request. Because the waypoint at index 1 of
the request was specified by using latitude/longitude coordinates, it is
omitted from the geocodingResults
array in the response.
{ "routes": [{...}], "geocodingResults": { "origin": { "geocoderStatus": {}, "type": [ "premise" ], "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g" }, "destination": { "geocoderStatus": {}, "type": [ "premise" ], "placeId": "ChIJI7ES6tl_j4ARVpDZoXbWAiY" }, "intermediates": [ { "geocoderStatus": {}, "intermediateWaypointRequestIndex": 0, "type": [ "street_address" ], "placeId": "ChIJvdLMGyq7j4ARScE5tWX_C0Y" }, { "geocoderStatus": {}, "intermediateWaypointRequestIndex": 2, "type": [ "premise" ], "placeId": "ChIJkTc0GKajj4AR9UMsOSHwGD0" } ] } }