Get alternative routes

  • The Routes API can return up to three alternative routes in addition to the default route, allowing users to choose the best option for their needs.

  • Alternative routes can only be requested for routes without intermediate waypoints and may increase API response time.

  • The response identifies routes using routeLabels: DEFAULT_ROUTE for the default route and DEFAULT_ROUTE_ALTERNATE for alternative routes.

  • You can include polylines in the response to display routes on a map by adding routes.polyline to the field mask.
European Economic Area (EEA) developers

By default, the Routes API returns the default route, which is typically the fastest route from the origin to the destination. When you request alternative routes, the API returns up to three routes along with the default route. Your customers can then choose a route that best fits their requirements.

Considerations when requesting alternative routes

To request alternative routes, be aware of the following considerations:

  • You can only request alternative routes for routes without intermediate waypoints. Requesting alternative routes when the route specifies intermediate waypoints does not cause an error. However, no alternative routes are returned.

  • The response contains a maximum of three alternative routes. However, sometimes no alternative routes are available so the response only contains the default route.

  • Because of the additional processing required to calculate alternative routes, requesting alternative routes might increase the response time of the API.

Example alternative routes request

Set computeAlternativeRoutes to true to request alternative routes. The following example shows how to request alternative routes in a computeRoutes method (REST) request.

curl -X POST -d '{
  "origin":{
    "location":{
      "latLng":{
        "latitude":42.340173523716736,
        "longitude":-71.05997968330408
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude":42.075698891472804,
        "longitude": -72.59806562080408
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference":"TRAFFIC_AWARE",
  "computeAlternativeRoutes": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeLabels' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

In this example, you specify a field mask so that the response contains only the duration, distanceMeters, and routeLabels properties for each route. Your customer can then use that information to choose which route to take. For more information, see Choose what information to return.

Example alternative routes response

In the response, use the routeLabels array property to identify reach route:

  • For the default route, the routeLabels property contains DEFAULT_ROUTE.

  • For any alternate routes, the routeLabels property contains DEFAULT_ROUTE_ALTERNATE.

In this example, the response contains the default route and two alternative routes. Notice that the values of the duration and distanceMeters properties are different for each route:

{
  "routes": [
    {
      "distanceMeters": 150322,
      "duration": "5309s",
      "routeLabels": [
        "DEFAULT_ROUTE"
      ]
    },
    {
      "distanceMeters": 157614,
      "duration": "6879s",
      "routeLabels": [
        "DEFAULT_ROUTE_ALTERNATE"
      ]
    },
    {
      "distanceMeters": 189311,
      "duration": "7376s",
      "routeLabels": [
        "DEFAULT_ROUTE_ALTERNATE"
      ]
    }
   ]
}

Include polylines in the response

To make it easier for the user to select the route, add the polyline for each route to the response. You can then display each polyline on a map.

To add the polyline, include routes.polyline in the field mask:

-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeLabels,routes.polyline'

The response then contains the polyline for each route:

{
  "routes": [
    {
      "distanceMeters": 150322,
      "duration": "5309s",
      "polyline": {
        "encodedPolyline": "mrlaGtavpLPLBTm…PgA^qC"
      },
      "routeLabels": [
        "DEFAULT_ROUTE"
      ]
    },
    {
      "distanceMeters": 157614,
      "duration": "6879s",
      "polyline": {
        "encodedPolyline": "DmEd`@e@pCo@pCs@z…PgA^qC"
      },
      "routeLabels": [
        "DEFAULT_ROUTE_ALTERNATE"
      ]
    },
    {
      "distanceMeters": 189311,
      "duration": "7376s",
      "polyline": {
        "encodedPolyline": "FVLL|Af@HPAV…PgA^qC"
      },
      "routeLabels": [
        "DEFAULT_ROUTE_ALTERNATE"
      ]
    }
   ]
}