## Tool: `compute_routes`

Computes travel routes between an origin and a destination, optionally through intermediate stops. Returns the distance and duration for each route.

**Input Requirements (CRITICAL):**

1. **`origin` and `destination` (objects - MANDATORY):** Each must be provided using exactly one of:

   - **`address`** (string, e.g., `'Eiffel Tower, Paris'`). Named places, landmarks, and businesses are resolved directly, so do NOT call `search_places` first just to geocode a waypoint. Include any city, region, or country the user mentioned.
   - **`lat_lng`** (object, `{"latitude": number, "longitude": number}`).
   - **`place_id`** (string, e.g., `'ChIJOwE_Id1w5EAR4Q27FkL6T_0'`), for example from `search_places`.
2. **`intermediate_waypoints` (array of objects - OPTIONAL):** Up to 25 stops to pass through, in order, between the origin and destination. Same format as `origin`. Not supported with `TRANSIT`. Only include stops the user asked for; specifying more than 10 intermediate waypoints will incur a higher cost and higher latency.

3. **`travel_mode` (enum - OPTIONAL):** `DRIVE` (default), `WALK`, `BICYCLE`, or `TRANSIT`.

4. **Timing (OPTIONAL - set at most ONE):** RFC 3339 timestamps with a UTC offset, e.g., `'2026-09-19T08:00:00-07:00'`. Defaults to departing now. For `TRANSIT`, the time can be up to 7 days in the past or up to 100 days in the future. For other modes, the time can be up to 365 days in the future and must not be in the past.

   - **`departure_time`:** Use when the user says when they will leave (e.g., "tomorrow at 8am").
   - **`arrival_time`:** Use when the user says when they must arrive (e.g., "be there by 9am").
5. **`routing_preference` (enum - OPTIONAL):**

   - `ROUTING_PREFERENCE_TRAFFIC_UNAWARE` (default): ignores live traffic, incidents, and closures. Lowest latency.
   - `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`: uses live traffic conditions when available. Not supported for `WALK` or `BICYCLE`. Set this ONLY when the user asks about traffic, congestion, or a traffic-adjusted ETA. It incurs higher cost and latency.
6. **`location_bias` (object - OPTIONAL):** `{"latitude": number, "longitude": number}` used to disambiguate place names in waypoint addresses. If a name is ambiguous (e.g., "Springfield") and the user gave no region, keep the name as given in `address` and set `location_bias` toward the intended area instead of guessing a region.

7. **`compute_alternative_routes` (boolean - OPTIONAL):** Set to `true` only when the user asks for route options or alternatives. Defaults to `false`, which returns only the recommended route.

8. **`include_polyline` (boolean - OPTIONAL):** Set to `true` only when the route geometry (`encoded_polyline`) is needed. Defaults to `false`.

**Instructions for Tool Call:**

- If the origin or the destination is missing, **you MUST ask the user for clarification** before calling the tool.
- For "How far is A from B?" questions, use B as the `origin` and A as the `destination`.

**Example Tool Call:** {"origin":{"address":"Eiffel Tower"},"destination":{"place_id":"ChIJt_5xIthw5EARoJ71mGq7t74"},"intermediate_waypoints":\[{"address":"Louvre Museum"}\],"travel_mode":"DRIVE","departure_time":"2026-09-19T08:00:00+02:00"}

**Instructions for Response:**

- When alternative routes are requested, routes are ordered from most to least recommended.
- If `routes` is empty, tell the user no route was found. Do not guess a route.
- To find places along a `DRIVE` route, pass the route's `retrieval_token` to `search_along_route`. The token is valid for 10 minutes.
- Only state facts returned by the tool. Do NOT invent turn-by-turn directions, transit lines, stations, platforms, or transfers.
- The grounded output must be attributed to the source using each route's `attribution` field when available.

The following code sample shows how to use `curl` to call the `compute_routes` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://mapstools.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "compute_routes", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

ComputeRoutesRequest.

### ComputeRoutesRequest

| JSON representation |
|---|
| ``` { "origin": { object (`Waypoint`) }, "destination": { object (`Waypoint`) }, "travelMode": enum (`RouteTravelMode`), "intermediateWaypoints": [ { object (`Waypoint`) } ], "routingPreference": enum (`RoutingPreference`), "locationBias": { object (`LatLng`) }, "includePolyline": boolean, "computeAlternativeRoutes": boolean, // Union field `timing` can be only one of the following: "departureTime": string, "arrivalTime": string // End of list of possible types for union field `timing`. } ``` |

| Fields ||
|---|---|
| `origin` | ``object (`Waypoint`)`` Required. Origin waypoint. |
| `destination` | ``object (`Waypoint`)`` Required. Destination waypoint. |
| `travelMode` | ``enum (`RouteTravelMode`)`` Optional. Specifies the mode of transportation. |
| `intermediateWaypoints[]` | ``object (`Waypoint`)`` Optional. Intermediate stops between the origin and destination to pass through in order. Up to 25 intermediate waypoints are supported. Specifying more than 10 intermediate waypoints will incur higher cost and higher latency. Intermediate waypoints are not supported when `travel_mode` is `TRANSIT`. |
| `routingPreference` | ``enum (`RoutingPreference`)`` Optional. Determines how traffic data is used to compute the route. `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL` is not supported when `travel_mode` is `WALK` or `BICYCLE`. For `TRANSIT`, it enables realtime transit data, such as delays and cancellations. |
| `locationBias` | ``object (`LatLng`)`` Optional. A location to bias the search results toward, for example to disambiguate waypoint text queries. |
| `includePolyline` | `boolean` Optional. Whether to include the encoded polyline in the response routes. Defaults to `false`. When set to `true`, `Route.encoded_polyline` is returned. |
| `computeAlternativeRoutes` | `boolean` Optional. Whether to compute alternative routes in addition to the recommended route. Defaults to false, in which case only the recommended route is returned. When set to true, up to all available routes are returned, though alternatives may not be available for every request. |
| Union field `timing`. Specifies when to depart from the origin or arrive at the final waypoint. Defaults to departing at the current time if not specified. For `TRANSIT`, the time must be at most 7 days in the past and at most 100 days in the future. For other travel modes, the time must not be in the past and must be at most 365 days in the future. `timing` can be only one of the following: ||
| `departureTime` | ``string (`Timestamp` format)`` Optional. Indicates that the route should be computed based on departure time. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `arrivalTime` | ``string (`Timestamp` format)`` Optional. Indicates that the route should be computed based on arrival time. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
|   ||

### Waypoint

| JSON representation |
|---|
| ``` { // Union field `location_type` can be only one of the following: "latLng": { object (`LatLng`) }, "placeId": string, "address": string // End of list of possible types for union field `location_type`. } ``` |

| Fields ||
|---|---|
| Union field `location_type`. Different ways to represent a location. `location_type` can be only one of the following: ||
| `latLng` | ``object (`LatLng`)`` A point specified using geographic coordinates. |
| `placeId` | `string` The Place ID associated with the waypoint. |
| `address` | `string` Human readable address or a plus code. See <https://plus.codes> for details. |
|   ||

### LatLng

| JSON representation |
|---|
| ``` { "latitude": number, "longitude": number } ``` |

| Fields ||
|---|---|
| `latitude` | `number` The latitude in degrees. It must be in the range \[-90.0, +90.0\]. |
| `longitude` | `number` The longitude in degrees. It must be in the range \[-180.0, +180.0\]. |

### Timestamp

| JSON representation |
|---|
| ``` { "seconds": string, "nanos": integer } ``` |

| Fields ||
|---|---|
| `seconds` | `string (int64 format)` Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z). |
| `nanos` | `integer` Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive. |

### RouteTravelMode

A set of values used to specify the mode of travel.

| Enums ||
|---|---|
| `ROUTE_TRAVEL_MODE_UNSPECIFIED` | No travel mode specified. Defaults to `DRIVE`. |
| `DRIVE` | Travel by passenger car. |
| `WALK` | Travel by walking. NOTE: `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 that you display in your app. |
| `BICYCLE` | Travel by bicycle. |
| `TRANSIT` | Travel by public transit. |

### RoutingPreference

A set of values that specify factors to take into consideration when calculating the route.

| Enums ||
|---|---|
| `ROUTING_PREFERENCE_UNSPECIFIED` | No routing preference specified. Defaults to `ROUTING_PREFERENCE_TRAFFIC_UNAWARE`. |
| `ROUTING_PREFERENCE_TRAFFIC_UNAWARE` | Computes routes without taking live traffic conditions into consideration. Suitable when traffic conditions don't matter or are not applicable. Using this value produces the lowest latency. |
| `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL` | Calculates routes taking live traffic conditions into consideration, when traffic data is available. For `TRANSIT`, uses realtime transit data, such as delays and cancellations, when available. This value will trigger the Pro tier and incur higher billing cost and latency. |

## Output Schema

ComputeRoutesResponse.

### ComputeRoutesResponse

| JSON representation |
|---|
| ``` { "routes": [ { object (`Route`) } ] } ``` |

| Fields ||
|---|---|
| `routes[]` | ``object (`Route`)`` Contains routes between the requested origin and destination, ordered from most recommended to least recommended. Only one route is returned unless `ComputeRoutesRequest.compute_alternative_routes` is set to true. |

### Route

| JSON representation |
|---|
| ``` { "distanceMeters": integer, "duration": string, "attribution": { object (`Attribution`) }, "encodedPolyline": string, "retrievalToken": string } ``` |

| Fields ||
|---|---|
| `distanceMeters` | `integer` The travel distance of the route, in meters. |
| `duration` | ``string (`Duration` format)`` The length of time needed to navigate the route. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `attribution` | ``object (`Attribution`)`` Required attribution to show with the route. |
| `encodedPolyline` | `string` An encoded polyline of the route. See <https://developers.google.com/maps/documentation/utilities/polylinealgorithm> |
| `retrievalToken` | `string` A token that can be used to retrieve this specific route in downstream tools, such as SearchAlongRoute. Valid for 10 minutes. |

### Duration

| JSON representation |
|---|
| ``` { "seconds": string, "nanos": integer } ``` |

| Fields ||
|---|---|
| `seconds` | `string (int64 format)` Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min \* 60 min/hr \* 24 hr/day \* 365.25 days/year \* 10000 years |
| `nanos` | `integer` Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 `seconds` field and a positive or negative `nanos` field. For durations of one second or more, a non-zero value for the `nanos` field must be of the same sign as the `seconds` field. Must be from -999,999,999 to +999,999,999 inclusive. |

### Attribution

| JSON representation |
|---|
| ``` { "title": string, "url": string } ``` |

| Fields ||
|---|---|
| `title` | `string` The title to display for the attribution. |
| `url` | `string` The URL to link to for the attribution. |

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.


Along with the title string, the following boolean hints are defined as follows:

- `readOnlyHint`: If true, the tool doesn't modify its environment. Default: false.
- `destructiveHint`: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
- `idempotentHint`: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
- `openWorldHint`: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ \| Idempotent Hint: ❌ \| Read Only Hint: ✅ \| Open World Hint: ❌