Set a point for a route to pass through

  • Intermediate waypoints can be designated as pass-through points using the via property to avoid unnecessary stops.

  • Setting via to true allows for a more direct route, but may result in detours or route calculation failures if the waypoint is inaccessible.

  • When using address strings or Plus codes for waypoints, the API returns place IDs for these locations in the geocodingResults array.

  • The geocodingResults array helps identify the place IDs of waypoints, which can be useful for subsequent requests or analysis.

  • Waypoints specified using latitude/longitude coordinates or place IDs are excluded from the geocodingResults array.
European Economic Area (EEA) developers

By default, the API treats intermediate waypoints as stops along a route. However, you can configure an intermediate waypoint as a pass-through via waypoint that the vehicle passes through without stopping.

Use pass-through waypoints to shape or adjust a specific route. Rather than splitting the route into separate pickup or drop-off stops, a pass-through waypoint forces the routing engine to pass through a specific location on the way to the destination—for example, to follow a preferred road segment or avoid a known hazard.

A route containing an origin, one or more pass-through intermediate waypoints, and a destination contains only one route leg that connects the origin directly to the destination.

To configure an intermediate waypoint as a pass-through waypoint, set the via property of the waypoint to true in either the REST Waypoint resource or the gRPC Waypoint message.

While the Routes API accepts addresses, Place IDs, and latitude and longitude coordinates, latitude and longitude, or latLng, coordinates provide the most precise route adjustments for pass-through waypoints.

The via property is most effective when you create routes in response to dragging waypoints on a map. This approach lets you see how the final route looks in real time and helps you place waypoints in accessible locations.

Example: Set a pass-through waypoint

The following example demonstrates how to set "via": true on an intermediate waypoint in a complete computeRoutes POST request:

curl -X POST -d '{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "intermediates": [
    {
      "location":{
        "latLng":{
          "latitude": 37.419734,
          "longitude": -122.0807784
        }
      },
      "via": true
    }
  ],
  "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' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Using addresses or Place IDs for pass-through waypoints

While we recommend latitude and longitude coordinates for precise pass-through routing, you can also specify intermediate waypoints using an address string or a Place ID.

When you use an address or Place ID for a pass-through waypoint, the API interpolates and snaps the location to the nearest navigable road. This road-snapping process can sometimes result in route variations or inaccuracies compared to exact coordinates.

If you specify a waypoint using an address string or Plus Code, the API geocodes the location and returns the matching Place ID in the geocodingResults.intermediates array in the response.

For each element in the intermediates array, use the intermediateWaypointRequestIndex property to determine which intermediate waypoint in the request corresponds to the Place ID in the response.

Example: Request Place IDs for pass-through waypoints

The following example shows a request with three pass-through intermediate waypoints, each of which specifies "via": true:

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",
      "via": true
    },
    {
      "location":{
        "latLng":{
          "latitude": 37.419734,
          "longitude": -122.0807784
        }
      },
      "via": true
    },
    {
      "address": "1836 El Camino Real, Redwood City, CA 94063",
      "via": true
    }
  ],
  "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 IDs for the origin, destination, and the two intermediate waypoints that you specified by address at request index 0 and index 2. The API omits the intermediate waypoint at index 1 from geocodingResults because you specified it using latitude and longitude coordinates:

{
  "routes": [
    {
      "distanceMeters": 54200,
      "duration": "2400s",
      "legs": [
        {
          "distanceMeters": 54200,
          "duration": "2400s",
          "startLocation": {
            "latLng": {
              "latitude": 37.4220,
              "longitude": -122.0841
            }
          },
          "endLocation": {
            "latLng": {
              "latitude": 37.7786,
              "longitude": -122.3893
            }
          }
        }
      ]
    }
  ],
  "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"
      }
    ]
  }
}