## Tool: `search_along_route`

Call this tool when the user wants to find places, businesses, or points of interest along a travel route (e.g., "gas stations on my way to Tahoe", "coffee shops between SF and San Jose"). Calling this tool incurs higher cost than `search_places`, so use `search_places` instead when searching near a single location rather than along a route.

**Input Requirements (CRITICAL):**

1. **`text_query` (string - MANDATORY):** A natural language description of what to search for along the route.

   - **Examples:** `'ev chargers'`, `'coffee'`, `'vegetarian restaurants'`, `'rest stops'`.
2. **Route specification (MANDATORY - provide exactly ONE of the following):**

   - **`retrieval_token` (string):** The `retrieval_token` returned by a prior `compute_routes` call for a `DRIVE` route. Prefer this whenever the route was already computed. The token is valid for 10 minutes.
   - **`route_endpoints` (object):** The route's `origin` and `destination`. Each must be provided using one of `address`, `lat_lng`, or `place_id`.
     - **Example:** `{"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}`
   - **`encoded_polyline` (string):** An encoded polyline representing a `DRIVE` route.
3. **`travel_mode` (enum - OPTIONAL):** `DRIVE` (default), `WALK`, or `BICYCLE`. `WALK` and `BICYCLE` are only supported with `route_endpoints`. `TRANSIT` is not supported.

4. **`routing_preference` (enum - OPTIONAL):**

   - `ROUTING_PREFERENCE_TRAFFIC_UNAWARE` (default): computes the route and detours without live traffic. 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 traffic-adjusted detour times. It incurs higher latency.
5. **`include_extended_details` (boolean - OPTIONAL):** Set to `true` only when the request requires qualitative review insights, specific menu items or offerings, atmosphere, visitor tips or busyness, EV charger availability, gas prices, or other rich qualitative details. Defaults to `false`. Enabling it may increase latency.

6. **`language_code` (string - OPTIONAL):** The language for the results summary and place details, e.g., `en`, `ja`, `en-US`. Defaults to `en-US`.

7. **`region_code` (string - OPTIONAL):** The Unicode CLDR region code of the user, e.g., `US`, `CA`.

**Instructions for Tool Call:**

- Each result includes a `detour_summary` (when available) describing the extra distance (`localized_detour_distance`) and, unless the route was given as `encoded_polyline`, the extra time (`detour_duration`) incurred by stopping at that place. Use it to compare options.
- The response `summary` may contain zero-based citations (e.g., "\[0\]") referencing entries in `results`.
- The grounded output must be attributed to the source using the `attribution` field of each `results[].place` when available.

The following code sample shows how to use `curl` to call the `search_along_route` 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": "search_along_route", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request message for SearchAlongRoute.

### SearchAlongRouteRequest

| JSON representation |
|---|
| ``` { "textQuery": string, "languageCode": string, "regionCode": string, "routingPreference": enum (`RoutingPreference`), "includeExtendedDetails": boolean, "travelMode": enum (`RouteTravelMode`), // Union field `route_spec` can be only one of the following: "encodedPolyline": string, "retrievalToken": string, "routeEndpoints": { object (`RouteEndpoints`) } // End of list of possible types for union field `route_spec`. } ``` |

| Fields ||
|---|---|
| `textQuery` | `string` Required. Natural language search query (e.g., "ev chargers", "coffee"). |
| `languageCode` | `string` Optional. The language for summary and place details. Defaults to "en-US". |
| `regionCode` | `string` Optional. Country/region code (CLDR) of location (e.g., "US"). |
| `routingPreference` | ``enum (`RoutingPreference`)`` Optional. Optional routing preference specifying how traffic data is used. Defaults to TRAFFIC_UNAWARE. |
| `includeExtendedDetails` | `boolean` Optional. Includes extended place details in the response. Set this field to `true` when the user request requires rich qualitative insights, real-time dynamics, or specialized entity attributes: - Qualitative reviews, customer sentiment, and feedback. - Specific offerings like menu items, dishes, food specialties, beverages, or business highlights. - Qualitative atmosphere, interior decor, aesthetic, ambience, or mood. - Real-time data and specialized facility specs, visitor policies/tips, wait times. Leave `false` (default) for standard discovery searches (e.g., cuisines, store types), location/address lookups, contact info, operating hours, and standard metadata/amenities. Enabling this field may incur higher latency. |
| `travelMode` | ``enum (`RouteTravelMode`)`` Optional. Specifies the travel mode used to compute the route and the detours. Defaults to `DRIVE`. `WALK` and `BICYCLE` are only supported with `route_endpoints`. `TRANSIT` is not supported. |
| Union field `route_spec`. Route specification: either an existing route, route token, or origin/destination endpoints. `route_spec` can be only one of the following: ||
| `encodedPolyline` | `string` An encoded polyline string representing the route. See <https://developers.google.com/maps/documentation/utilities/polylinealgorithm> |
| `retrievalToken` | `string` A retrieval token returned from a prior ComputeRoutes call representing the route. |
| `routeEndpoints` | ``object (`RouteEndpoints`)`` Explicit route endpoints (origin and destination). |
|   ||

### RouteEndpoints

| JSON representation |
|---|
| ``` { "origin": { object (`Waypoint`) }, "destination": { object (`Waypoint`) } } ``` |

| Fields ||
|---|---|
| `origin` | ``object (`Waypoint`)`` Required. Starting point (address, Place ID, or geographic coordinates). |
| `destination` | ``object (`Waypoint`)`` Required. Destination point (address, Place ID, or geographic coordinates). |

### 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\]. |

### 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. |

### 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. |

## Output Schema

Response message for SearchAlongRoute.

### SearchAlongRouteResponse

| JSON representation |
|---|
| ``` { "results": [ { object (`Result`) } ], "summary": string, "contentToken": string } ``` |

| Fields ||
|---|---|
| `results[]` | ``object (`Result`)`` Output only. The ranked list of search results found along the route. |
| `summary` | `string` Output only. Natural language summary of search results and detour trade-offs. May contain zero-based citations (e.g. "\[0\]", "\[1\]") referencing the corresponding entries in the `results` list. |
| `contentToken` | `string` Output only. An encrypted token that encapsulates the search context and can be passed to Google Maps visual rendering services, SDKs, or the Maps Agentic UI Toolkit (A2UI) to display interactive UI components for the returned search results. |

### Result

| JSON representation |
|---|
| ``` { "place": { object (`PlaceView`) }, "detourSummary": { object (`DetourSummary`) } } ``` |

| Fields ||
|---|---|
| `place` | ``object (`PlaceView`)`` Output only. Details about the place found along the route. |
| `detourSummary` | ``object (`DetourSummary`)`` Output only. Detour metrics incurred by adding this place as an intermediate stop along the route. Omitted or empty if detour metrics could not be calculated. |

### PlaceView

| JSON representation |
|---|
| ``` { "place": string, "id": string, "googleMapsLinks": { object (`GoogleMapsLinks`) }, "attribution": { object (`Attribution`) }, // Union field `_location` can be only one of the following: "location": { object (`LatLng`) } // End of list of possible types for union field `_location`. } ``` |

| Fields ||
|---|---|
| `place` | `string` The resource name of the underlying place, in the format of "places/{id}". |
| `id` | `string` The place ID of the underlying place. |
| `googleMapsLinks` | ``object (`GoogleMapsLinks`)`` Links to trigger different Google Maps actions. |
| `attribution` | ``object (`Attribution`)`` Required attribution to show with the place. |
| Union field `_location`. `_location` can be only one of the following: ||
| `location` | ``object (`LatLng`)`` The position of this place. |
|   ||

### 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\]. |

### GoogleMapsLinks

| JSON representation |
|---|
| ``` { "directionsUrl": string, "placeUrl": string, "writeAReviewUrl": string, "reviewsUrl": string, "photosUrl": string } ``` |

| Fields ||
|---|---|
| `directionsUrl` | `string` A link to show the directions to the place. The link only populates the destination location and uses the default travel mode `DRIVE`. |
| `placeUrl` | `string` A link to show this place. |
| `writeAReviewUrl` | `string` A link to write a review for this place on Google Maps. |
| `reviewsUrl` | `string` A link to show reviews of this place on Google Maps. |
| `photosUrl` | `string` A link to show photos of this place on Google Maps. |

### 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. |

### DetourSummary

| JSON representation |
|---|
| ``` { "detourDuration": string, "localizedDetourDistance": string } ``` |

| Fields ||
|---|---|
| `detourDuration` | ``string (`Duration` format)`` The additional travel time required to detour to this place from the main route. This value is not set if the route is specified by `encoded_polyline`. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `localizedDetourDistance` | `string` The additional distance required to detour to this place from the main route, formatted for display in the request language (e.g. "1.2 mi" or "1,9 km"). |

### 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. |

### 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: ❌