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.
You can call compute_routes through the MCP server or as the computeRoutes
REST method. This page describes the request options, including the Pro options;
what the response contains; and how requests are billed. For the full schemas,
see the
compute_routes MCP reference
and the
computeRoutes REST reference.
Request options
The following table describes the request options for compute_routes:
| 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 |
Latitude/longitude coordinates that bias how text waypoints are resolved, such as to disambiguate an address. |
Pro options
Two options select the Maps Grounding 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.
Example
The following MCP 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
}
The following example sends the same request to the computeRoutes REST
method:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"origin": {"address": "Ferry Building, San Francisco, CA"},
"destination": {"address": "Golden Gate Park, San Francisco, CA"},
"intermediateWaypoints": [
{"address": "Palace of Fine Arts, San Francisco, CA"}
],
"travelMode": "DRIVE",
"routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
"includePolyline": true
}' \
"https://mapstools.googleapis.com/v1:computeRoutes"
Replace API_KEY with your API key.
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. WithROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, the duration accounts for traffic conditions.encodedPolyline: The route's path as an encoded polyline, wheninclude_polylineistrue. You can use it to draw the route on a map with other Google Maps Platform APIs.retrievalToken: An opaque token returned forDRIVEroutes (valid for 10 minutes) that you can pass tosearch_along_routeto find places along that route without resending waypoints.attribution: The attribution that you must show with the route. See Attribution requirements.
Billing and quotas
Each compute_routes request is one billable event:
- A request that doesn't use any Pro options is billed under the Maps Grounding Essentials SKU.
- A request that uses a Pro option is billed under the Maps Grounding Pro SKU. Using both Pro options in one request doesn't change the charge. For Pro pricing, see Compare Essentials, Pro, and Grounding with Google Maps.
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 for each 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_ARGUMENTerror. - Transit routes don't support intermediate waypoints. A transit request
with intermediate waypoints returns an
INVALID_ARGUMENTerror. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALisn'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.