Specify intermediate waypoints

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 entire RouteLeg 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
}