MCP Tools Reference: mapstools.googleapis.com

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 
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].
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 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: ❌