Set intermediate waypoints

Intermediate waypoints are locations in between the origin and destination that you want the route to go through. An intermediate waypoint can be a stop or you can specify it as a location to pass through. For an example of a waypoint for a stop, see Set a stop along a route. For an example of a waypoint to pass-through, Set point for a route to pass-through.

Note: Intermediate waypoints are not supported in the Compute Route Matrix.

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.

Caution: If you make requests using 11 or more intermediate waypoints (between 11 and 25), your requests are billed at a higher rate. Learn more about billing for Routes API.

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.

Example - Set 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.

This example uses 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": [
                {
                  ...