Search along route

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 and is billed under the Maps 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 and the searchAlongRoute REST reference.

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.

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

Examples

The following MCP request searches for EV charging stations between San Francisco and Lake Tahoe using route_endpoints and traffic-aware routing:

{
  "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:

{
  "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:

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.
    • 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 (Preview) that lets you display the places in the response with Places UI Kit at no additional cost. Returned when the response includes at least one place.

For full field details, see the search_along_route reference.

Billing and quotas

Each search_along_route request is one billable event under the Maps 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 (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 and the India pricing table.