The `search_along_route` tool lets an LLM find places along a travel route from a natural language query, such as EV charging stations on the way to Lake Tahoe or coffee shops between San Francisco and San Jose. The tool returns an AI-generated summary of matching places and their detour trade-offs. For each place cited in the summary, the response also includes the place ID, latitude/longitude coordinates, Google Maps links, required attribution, and detour metrics. Every `search_along_route` request is a [Pro option](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#essentials-and-pro) and is billed under the [Maps Grounding Pro SKU](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-pro-sku). You can call `search_along_route` through the MCP server or as the `searchAlongRoute` REST method. This page describes the request options, how to specify a route, what the response contains, and how requests are billed. For the full schemas, see the [`search_along_route` MCP reference](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/search_along_route.md.txt) and the [`searchAlongRoute` REST reference](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/rest/v1/TopLevel/searchAlongRoute.md.txt). ## Request options The LLM sets these options when it calls the tool, based on the user's request and the tool description. You can influence which options the model uses with your own instructions; see [Control Pro usage](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#control_pro_usage). The following table describes the request options for `search_along_route`: | Option | Description | |---|---| | `text_query` | Required. The natural language search query for places along the route---for example, `ev chargers`, `coffee`, or `vegetarian restaurants`. | | `retrieval_token`, `route_endpoints`, or `encoded_polyline` | Required. The route to search along. Specify one of these three fields in each request. See [Specify a route](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-along-route.md.txt#specify-a-route). | | `travel_mode` | Optional. The mode of transportation used to compute the route and detours: `DRIVE` (default), `WALK`, or `BICYCLE`. `WALK` and `BICYCLE` are supported only with `route_endpoints`. `TRANSIT` isn't supported. `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` | Optional. How traffic data is used to compute the route and detour times: `ROUTING_PREFERENCE_TRAFFIC_UNAWARE` (default) or `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`. `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL` uses live traffic conditions when available and isn't supported for `WALK` or `BICYCLE`. | | `include_extended_details` | Optional. When `true`, the summary includes [extended place details](https://developers.google.com/maps/ai/maps-experience-agent-tools/search-along-route.md.txt#extended-place-details), such as insights from reviews, menu items, atmosphere, visitor tips, EV charger availability, or gas prices. Defaults to `false`. | | `language_code` | Optional. The BCP-47 language code for the summary and localized detour distance---for example, `en-US` or `ja`. Defaults to `en-US`. | | `region_code` | Optional. The two-letter CLDR region code of the user---for example, `US` or `CA`. Affects region-specific place names and can affect results based on applicable law. | ## Specify a route Each `search_along_route` request must specify the route using one of three mutually exclusive fields. Setting more than one route field, or omitting all three, returns an `INVALID_ARGUMENT` error. The following table compares the three ways to specify a route: | Route option | Input format | Supported travel modes | Returns `detourDuration` | When to use it | |---|---|---|---|---| | `retrieval_token` | The `retrievalToken` string from a prior [`compute_routes`](https://developers.google.com/maps/ai/maps-experience-agent-tools/compute-routes.md.txt) response (valid for 10 minutes) | `DRIVE` | Yes | The agent already called `compute_routes` for a driving route, including routes with intermediate stops, and the user asks for places along that route. | | `route_endpoints` | An object with `origin` and `destination` waypoints (`address`, `place_id`, or `lat_lng`) | `DRIVE`, `WALK`, `BICYCLE` | Yes | The user asks to find places between two locations in a single step without calling `compute_routes` first, or the route uses walking or bicycling. | | `encoded_polyline` | An [encoded polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm.md.txt) string representing a driving route | `DRIVE` | No (returns `localizedDetourDistance` only) | Your application already has a route polyline from another source, such as the Routes API. | ### Chain `compute_routes` and `search_along_route` When a `compute_routes` request uses the `DRIVE` travel mode, each route in the response includes a `retrievalToken` field. This token is valid for 10 minutes and encodes the computed route, including any intermediate stops. When the user follows up by asking for places along that route, the LLM can pass the `retrievalToken` value as `retrieval_token` in `search_along_route`. ## Extended place details Set `include_extended_details` to `true` when the user's request needs qualitative insights, real-time conditions, or specialized attributes along the route, such as: - What reviewers say: review-based insights, customer sentiment, and feedback. - Specific offerings: menu items, dishes, food specialties, beverages, or business highlights. - Atmosphere: interior decor, aesthetic, ambience, or mood. - Practical visitor tips and real-time data: whether to book ahead, wait times, how busy the place is, EV charger availability, gas prices, parking, and facilities. Leave `include_extended_details` set to `false` (the default) for standard searches along a route, such as finding gas stations, rest stops, or coffee shops by location, operating hours, and detour time. Requests with extended details take longer to complete, but they don't add extra charges because every `search_along_route` request is already billed under the Pro SKU. > [!NOTE] > **Note:** Summaries that include insights from reviews are subject to the [attribution requirements](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#attribution_requirements_for_google_maps_sources) for Google Maps sources. Each place in the response includes `googleMapsLinks.reviewsUrl`, which links to the place's reviews on Google Maps. ## Examples The following MCP request searches for EV charging stations between San Francisco and Lake Tahoe using `route_endpoints` and traffic-aware routing: ```json { "method": "tools/call", "params": { "name": "search_along_route", "arguments": { "text_query": "fast EV chargers with a coffee shop nearby", "route_endpoints": { "origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"} }, "travel_mode": "DRIVE", "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL", "include_extended_details": true } }, "jsonrpc": "2.0", "id": 1 } ``` The following example uses a `retrieval_token` from a prior `compute_routes` response: ```json { "method": "tools/call", "params": { "name": "search_along_route", "arguments": { "text_query": "coffee shops", "retrieval_token": "RETRIEVAL_TOKEN" } }, "jsonrpc": "2.0", "id": 2 } ``` Replace RETRIEVAL_TOKEN with the `retrievalToken` string returned by `compute_routes`. The following example sends the first request to the `searchAlongRoute` REST method: ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -d '{ "textQuery": "fast EV chargers with a coffee shop nearby", "routeEndpoints": { "origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"} }, "travelMode": "DRIVE", "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL", "includeExtendedDetails": true }' \ "https://mapstools.googleapis.com/v1:searchAlongRoute" ``` Replace `API_KEY` with your API key. ## Response The response contains the following fields: - `summary`: A natural language summary of the search results and detour trade-offs. It might contain zero-based citations, such as `[0]`, that map to entries in `results`. - `results[]`: The ranked list of places mentioned in the summary. Each entry includes: - `place`: Details about the place: - `place`: The resource name of the place, in the format `places/{id}`. - `id`: The place ID. You can use it with other Google Maps Platform APIs, such as to show the place on a map. - `location`: The latitude/longitude coordinates of the place. - `googleMapsLinks`: Google Maps links for the place (`placeUrl`), directions (`directionsUrl`), reviews (`reviewsUrl`), photos (`photosUrl`), and writing a review (`writeAReviewUrl`). - `attribution`: The attribution that you must show with the place. See [Attribution requirements](https://developers.google.com/maps/ai/maps-experience-agent-tools.md.txt#attribution_requirements_for_google_maps_sources). - `detourSummary`: The additional travel time and distance required to stop at this place along the route: - `localizedDetourDistance`: The extra distance formatted in the request language, such as `"1.2 mi"` or `"1.9 km"`. - `detourDuration`: The extra travel time as a duration string, such as `"180s"`. This field isn't set when the route is specified with `encoded_polyline`. - `contentToken`: An [agentic data visualization token](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt) (Preview) that lets you display the places in the response with [Places UI Kit](https://developers.google.com/maps/documentation/javascript/places-ui-kit/overview.md.txt) at no additional cost. Returned when the response includes at least one place. For full field details, see the [`search_along_route` reference](https://developers.google.com/maps/ai/maps-experience-agent-tools/reference/mcp/search_along_route.md.txt). ## Billing and quotas Each `search_along_route` request is one billable event under the [Maps Grounding Pro SKU](https://developers.google.com/maps/billing-and-pricing/sku-details/places.md.txt#grounding-pro-sku). Setting `include_extended_details` to `true` or `routing_preference` to `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL` doesn't add extra charges. If your agent calls `compute_routes` first and then passes `retrieval_token` to `search_along_route`, each tool call is billed as a separate request. If you display the places from a `search_along_route` response with Places UI Kit, you can use the [agentic data visualization token](https://developers.google.com/maps/ai/agentic-data-visualization-token.md.txt) (Preview) so that those Places UI Kit requests aren't billed. The `search_along_route` quota is 300 queries per minute for each project. For pricing, see the [Main pricing table](https://developers.google.com/maps/billing-and-pricing/pricing.md.txt#places-pricing) and the [India pricing table](https://developers.google.com/maps/billing-and-pricing/pricing-india.md.txt#places-pricing).