Set intermediate waypoints

  • Intermediate waypoints allow you to specify locations between the origin and destination for a route to pass through or stop at.

  • You can define up to 25 intermediate waypoints using the intermediates property when computing routes, but requests with 11 or more are billed at a higher rate.

  • The response provides route details including legs, with each leg representing a segment of the journey between waypoints.

  • Each leg within the route is further broken down into steps, providing detailed information about each segment of the journey.
European Economic Area (EEA) developers

Intermediate waypoints are locations specified between the origin and destination that you want the route to go through.

You can define up to 25 intermediate waypoints in a single request using the intermediates array property of the REST computeRoutes method or the gRPC ComputeRoutes method.

Stopovers versus pass-through waypoints

You can configure an intermediate waypoint as either a stop or a pass-through location:

  • Stopover: By default, the vehicle stops at the location. Each stopover waypoint divides the route by adding a RouteLeg entry to the legs array in the response. For more information, see Set a stop along a route.
  • Pass-through waypoint with "via" set to true: The vehicle passes through the location without stopping. Pass-through waypoints don't add entries to the legs array. For more information, see Set a point for a route to pass through.

Route legs and intermediate waypoints

For each intermediate stopover in a request, the response contains a separate RouteLeg object in the routes.legs array.

For example, a route with an origin, one intermediate stopover, and a destination contains two route legs: * Leg 1: From origin to the intermediate stopover. * Leg 2: From the intermediate stopover to the destination.

Example: Request with an intermediate waypoint

The following example uses the intermediates array to add a single intermediate stopover to a route.

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
        }
      }
    }
  ],
  "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'

Response with multiple route legs

Because the intermediate waypoint in the request is a stopover that doesn't set "via": true, the response divides the route into two legs in the legs array:

{
  "routes": [
    {
      "distanceMeters": 805,
      "duration": "248s",
      "legs": [
        {
          "distanceMeters": 207,
          "duration": "89s",
          "startLocation": {
            "latLng": {
              "latitude": 37.4197318,
              "longitude": -122.0826233
            }
          },
          "endLocation": {
            "latLng": {
              "latitude": 37.419734,
              "longitude": -122.0807792
            }
          }
        },
        {
          "distanceMeters": 598,
          "duration": "159s",
          "startLocation": {
            "latLng": {
              "latitude": 37.419734,
              "longitude": -122.0807792
            }
          },
          "endLocation": {
            "latLng": {
              "latitude": 37.4176166,
              "longitude": -122.0793882
            }
          }
        }
      ]
    }
  ]
}