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.durationroutes.distanceMetersroutes.legscorresponding to the entireRouteLegobject.
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
geocodingResultsin the response field mask to specify to return thegeocodingResultsarray 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"
}
]
}
}