Compute routes

The compute_routes tool returns a route between an origin and a destination for a given travel mode. The response includes the route's distance and duration. By default, routes are computed without live traffic. Pro adds routing that accounts for live traffic and routes with more intermediate stops.

This page describes the request options, including the Pro options; what the response contains; and how requests are billed. For the full tool schema, see the compute_routes reference.

Request options

Option Description
origin, destination Required. Each is a waypoint: an address (a human-readable address or a plus code), a place_id, or a lat_lng. You can mix formats, for example an address for the origin and a Place ID for the destination.
travel_mode The mode of transportation: DRIVE (default), WALK, BICYCLE, or TRANSIT. WALK routes are in beta and might sometimes be missing clear sidewalks or pedestrian paths. You must display this warning to the user for all walking routes that you display in your app.
routing_preference How traffic data is used to compute the route: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (default) or ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, which is a Pro option. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL isn't supported for WALK or BICYCLE. See Traffic-aware routing.
intermediate_waypoints Ordered stops between the origin and destination. The route passes through them in the order given. A request can include up to 10 intermediate waypoints, or 11 to 25 as a Pro option. A request with more than 25 returns an INVALID_ARGUMENT error. Transit routes don't support intermediate waypoints.
departure_time or arrival_time When to depart from the origin or arrive at the destination, as an RFC 3339 timestamp. Set at most one. Defaults to departing at the current time. For TRANSIT, the time can be up to 7 days in the past or 100 days in the future. For other travel modes, the time can't be in the past and can be up to 365 days ahead.
compute_alternative_routes When true, the response includes alternative routes in addition to the recommended route, when alternatives are available. Defaults to false.
include_polyline When true, each route in the response includes encodedPolyline. Defaults to false.
location_bias A latitude and longitude that biases how text waypoints are resolved, for example to disambiguate an address.

Pro options

Two options select the Pro SKU. A request that uses either or both is billed under the Pro SKU:

Pro option When to use it
routing_preference set to ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL The user asks about traffic, congestion, or a travel time that accounts for current traffic. See Traffic-aware routing.
11 to 25 intermediate_waypoints The route needs more than 10 stops between the origin and destination.

All other options are billed under the Essentials SKU, including the travel mode, timing, alternative routes, polylines, and location bias.

Traffic-aware routing

By default, routes are computed without live traffic conditions (ROUTING_PREFERENCE_TRAFFIC_UNAWARE). This setting has the lowest latency. It suits requests where traffic doesn't matter or doesn't apply, such as walking routes or rough planning.

Set routing_preference to ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL to compute the route and its duration with current traffic conditions, when traffic data is available. Use it when the user asks how long a drive takes right now. For TRANSIT routes, this setting uses real-time transit data, such as delays and cancellations, when available. It isn't supported for WALK or BICYCLE routes; those requests return an INVALID_ARGUMENT error. This is a Pro option, so the request is billed under the Pro SKU. The option also adds latency.

During Restricted GA, if your project isn't on the Pro allowlist, this option is treated as ROUTING_PREFERENCE_TRAFFIC_UNAWARE. For details, see Pro options during Restricted GA.

Example

The following request asks for a traffic-aware driving route with one intermediate stop and an encoded polyline. It's billed under the Pro SKU:

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Response

The response contains routes[], ordered from most to least recommended. Only one route is returned unless compute_alternative_routes is true. Each route includes:

  • distanceMeters: The travel distance of the route, in meters.
  • duration: The time needed to travel the route. With ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, the duration accounts for traffic conditions.
  • encodedPolyline: The route's path as an encoded polyline, when include_polyline is true. You can use it to draw the route on a map with other Google Maps Platform APIs.
  • attribution: The attribution that you must show with the route. See Attribution requirements.

Pro options during Restricted GA

During Restricted GA, Pro options are available only to projects on the Pro allowlist. If your project isn't on the allowlist yet:

  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL is treated as ROUTING_PREFERENCE_TRAFFIC_UNAWARE, and the request is billed under the Essentials SKU.
  • A request with more than 10 intermediate waypoints returns an INVALID_ARGUMENT error ("At most 10 intermediate waypoints are supported.").

To request access, see Pro options during Restricted GA.

Billing and quotas

Each compute_routes request is one billable event:

Requesting alternative routes, a polyline, a departure or arrival time, or a different travel mode doesn't change the SKU.

The compute_routes quota is 300 queries per minute, per project, shared by both SKUs. For pricing, see the Main pricing table and the India pricing table.

Limits

  • A request can include at most 25 intermediate waypoints; 11 to 25 is a Pro option. A request with more returns an INVALID_ARGUMENT error.
  • Transit routes don't support intermediate waypoints. A transit request with intermediate waypoints returns an INVALID_ARGUMENT error.
  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL isn't supported for walking or bicycling routes.
  • For transit routes, departure and arrival times can be up to 7 days in the past or 100 days ahead. For other travel modes, they can't be in the past and can be up to 365 days ahead.
  • Waypoint coordinates must be within valid geographic bounds (latitude from -90 to 90, longitude from -180 to 180).
  • The tool doesn't return turn-by-turn steps, legs, or transit line details.