MCP Tools Reference: mapstools.googleapis.com

工具：search_along_route

当用户想要查找旅行路线沿途的地点、商家或地图注点（例如“去太浩湖路上的加油站”“旧金山和圣何塞之间的咖啡店”）时，请调用此工具。调用此工具的费用高于 search_places，因此在搜索单个地点附近（而非沿路线）时，请改用 search_places。

输入要求（至关重要）：

  1. text_query（字符串 - 必填）：沿路线搜索的内容的自然语言说明。

    • 示例：'ev chargers'、'coffee'、'vegetarian restaurants'、'rest stops'。

  2. 路线规范（必填 - 仅提供以下其中一项）：

    • retrieval_token（字符串）：先前针对 DRIVE 路线调用 compute_routes 返回的 retrieval_token。只要路线已计算完毕，就首选此方法。令牌的有效期为 10 分钟。
    • route_endpoints（对象）：路线的 origin 和 destination。每个都必须使用 address、lat_lng 或 place_id 之一提供。
      • 示例： {"route_endpoints": {"origin": {"address": "San Francisco, CA"}, "destination": {"address": "Lake Tahoe, CA"}}}
    • encoded_polyline（字符串）：表示 DRIVE 路线的编码多段线。

  3. travel_mode（枚举 - 可选）：DRIVE（默认）、WALK 或 BICYCLE。WALK 和 BICYCLE 仅支持 route_endpoints。不支持 TRANSIT。

  4. routing_preference（枚举 - 可选）：

    • ROUTING_PREFERENCE_TRAFFIC_UNAWARE（默认）：在不考虑实时路况的情况下计算路线和绕行路线。延迟时间最短。
    • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL：使用实时路况信息（如有）。WALK 或 BICYCLE 不支持此方法。仅当用户询问路况、拥堵情况或根据路况调整的绕行时间时，才设置此参数。它会产生更高的延迟。

  5. include_extended_details（布尔值 - 可选）：仅当请求需要定性评价数据分析、特定菜单项或产品/服务、氛围、访客提示或繁忙程度、电动汽车充电桩可用性、油价或其他丰富的定性详细信息时，才设置为 true。此字段的默认值为 false。启用此功能可能会增加延迟时间。

  6. language_code（字符串 - 可选）：结果摘要和地点详情的语言，例如 en、ja、en-US。默认值为 en-US。

  7. region_code（字符串 - 可选）：用户的 Unicode CLDR 区域代码，例如 US、CA。

工具调用说明：

  • 每个结果都包含一个 detour_summary（如果可用），用于说明在该地点停留所产生的额外距离 (localized_detour_distance) 和额外时间 (detour_duration)（除非路线指定为 encoded_polyline）。您可以使用它来比较各种选项。
  • 回答 summary 可能包含从零开始的引用（例如“[0]”），这些引用指向 results 中的条目。
  • 必须使用每个 results[].place 的 attribution 字段（如果可用）将接地输出归因于来源。

以下代码示例展示了如何使用 curl 调用 search_along_route MCP 工具。

Curl 请求 
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
}'

输入架构

SearchAlongRoute 的请求消息。

SearchAlongRouteRequest

JSON 表示法 
{
  "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.
}
字段
textQuery

string

必需。自然语言搜索查询（例如“电动汽车充电桩”“咖啡”）。
languageCode

string

可选。摘要和地点详情的语言。默认值为“en-US”。
regionCode

string

可选。位置的国家/地区代码 (CLDR)（例如“US”）。
routingPreference

enum (RoutingPreference)

可选。可选路由偏好设置，用于指定如何使用路况数据。默认值为 TRAFFIC_UNAWARE。
includeExtendedDetails

boolean

可选。在响应中包含扩展的地点详情。

当用户请求需要丰富的定性数据洞见、实时动态或专门的实体属性时，请将此字段设置为 true：- 定性评价、客户情绪和反馈。- 具体产品/服务，例如菜单项、菜品、特色美食、饮品或商家亮点。- 氛围、室内装饰、美学、环境或情调等定性描述。- 实时数据和专门设施规格、访客政策/提示、等待时间。

对于标准发现搜索（例如菜系、商店类型）、位置/地址查询、联系信息、营业时间和标准元数据/设施，请保留 false（默认）。

启用此字段可能会导致延迟时间增加。
travelMode

enum (RouteTravelMode)

可选。指定用于计算路线和绕行路线的出行方式。默认为 DRIVE。WALK 和 BICYCLE 仅支持 route_endpoints。不支持 TRANSIT。
联合字段 route_spec。路线规范：现有路线、路线令牌或起点/终点。route_spec 只能是下列其中一项：
encodedPolyline

string

表示路线的编码多段线字符串。请参阅 https://developers.google.com/maps/documentation/utilities/polylinealgorithm
retrievalToken

string

从之前的 ComputeRoutes 调用返回的检索令牌，表示路线。
routeEndpoints

object (RouteEndpoints)

明确的路线端点（出发地和目的地）。

RouteEndpoints

JSON 表示法 
{
  "origin": {
    object (Waypoint)
  },
  "destination": {
    object (Waypoint)
  }
}
字段
origin

object (Waypoint)

必需。起点（地址、地点 ID 或地理坐标）。
destination

object (Waypoint)

必需。目的地（地址、地点 ID 或地理坐标）。

航点

JSON 表示法 
{

  // 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.
}
字段
联合字段 location_type。表示位置的不同方式。location_type 只能是下列其中一项：
latLng

object (LatLng)

使用地理坐标指定的点。
placeId

string

与航点关联的地点 ID。
address

string

人类可读地址或 Plus Code。如需了解详情，请参阅 https://plus.codes。

LatLng

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
字段
latitude

number

纬度（以度为单位）。它必须在 [-90.0, +90.0] 范围内。
longitude

number

经度（以度为单位）。它必须在 [-180.0, +180.0] 范围内。

RoutingPreference

一组值，用于指定计算路线时要考虑的因素。

枚举
ROUTING_PREFERENCE_UNSPECIFIED 未指定路由偏好设置。默认为 ROUTING_PREFERENCE_TRAFFIC_UNAWARE。
ROUTING_PREFERENCE_TRAFFIC_UNAWARE 计算路线时不考虑实时路况信息。适用于路况信息不重要或不适用的情况。使用此值可实现最低延迟。
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL

在有路况数据的情况下，计算路线时会考虑实时路况。对于TRANSIT，系统会使用实时公交数据（例如延误和取消），前提是这些数据可用。

此值会触发 Pro 层级，并产生更高的已出账单费用和延迟时间。

RouteTravelMode

一组用于指定出行方式的值。

枚举
ROUTE_TRAVEL_MODE_UNSPECIFIED 未指定出行方式。默认为 DRIVE。
DRIVE 乘轿车出行。
WALK 步行出行。注意：WALK路线功能目前处于 Beta 版阶段，有时可能无法提供畅通无阻的人行道或步道。对于应用中显示的所有步行路线，您都必须向用户显示此警告。
BICYCLE 骑自行车出行。
TRANSIT 乘坐公共交通工具出行。

输出架构

SearchAlongRoute 的响应消息。

SearchAlongRouteResponse

JSON 表示法 
{
  "results": [
    {
      object (Result)
    }
  ],
  "summary": string,
  "contentToken": string
}
字段
results[]

object (Result)

仅限输出。沿路线找到的搜索结果的排名列表。
summary

string

仅限输出。搜索结果和绕行权衡的自然语言摘要。可能包含从零开始的引用（例如“[0]”“[1]”），这些引用指向 results 列表中的相应条目。
contentToken

string

仅限输出。一个加密令牌，用于封装搜索上下文，并可传递给 Google 地图可视化渲染服务、SDK 或地图智能体 UI 工具包 (A2UI)，以便为返回的搜索结果显示交互式界面组件。

结果

JSON 表示法 
{
  "place": {
    object (PlaceView)
  },
  "detourSummary": {
    object (DetourSummary)
  }
}
字段
place

object (PlaceView)

仅限输出。沿途找到的地点的详细信息。
detourSummary

object (DetourSummary)

仅限输出。将此地点添加为路线中的中间经停点所产生的绕行指标。如果无法计算绕行指标，则省略或留空。

PlaceView

JSON 表示法 
{
  "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.
}
字段
place

string

底层地点的资源名称，格式为“places/{id}”。
id

string

底层地点的地点 ID。
googleMapsLinks

object (GoogleMapsLinks)

用于触发不同 Google 地图操作的链接。
attribution

object (Attribution)

与地点一起显示的必需提供方信息。

联合字段 _location。

_location 只能是下列其中一项：
location

object (LatLng)

此地点的位置。

LatLng

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
字段
latitude

number

纬度（以度为单位）。它必须在 [-90.0, +90.0] 范围内。
longitude

number

经度（以度为单位）。它必须在 [-180.0, +180.0] 范围内。
JSON 表示法 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
字段
directionsUrl

string

用于显示前往该地点的路线的链接。该链接仅填充目的地位置，并使用默认出行方式 DRIVE。
placeUrl

string

用于显示此地点的链接。
writeAReviewUrl

string

一个链接，用于在 Google 地图上为此地点撰写评价。
reviewsUrl

string

一个链接，用于在 Google 地图上显示此地点的评价。
photosUrl

string

一个链接，用于在 Google 地图上显示此地点的照片。

归因

JSON 表示法 
{
  "title": string,
  "url": string
}
字段
title

string

要为提供方显示的标题。
url

string

要链接到的归因网址。

DetourSummary

JSON 表示法 
{
  "detourDuration": string,
  "localizedDetourDistance": string
}
字段
detourDuration

string (Duration format)

从主路线绕行到此地点所需的额外行程时间。如果路由由 encoded_polyline 指定，则不会设置此值。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
localizedDetourDistance

string

从主路线绕行到此地点所需的额外距离，其格式设置为以请求语言显示（例如“1.2 英里”或“1.9 公里”）。

时长

JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

时间跨度的带符号秒数。必须介于 -315,576,000,000 到 +315,576,000,000 之间（含边界值）。注意：这些边界的计算公式为：60 秒/分钟 * 60 分钟/小时 * 24 小时/天 * 365.25 天/年 * 10000 年
nanos

integer

时间跨度的秒数的有符号小数部分（以纳秒为单位）。小于 1 秒的时长用 0 seconds 字段和正或负 nanos 字段表示。对于一秒或更长的时长，nanos 字段的非零值必须与 seconds 字段具有相同的符号。必须介于 -999,999,999 到 +999,999,999 之间（含边界值）。

工具注释

工具注解会发送到 MCP 客户端，用于描述给定工具的基本风险。大多数客户端会将这些提示视为不可信，但它们可用于决定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则该工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则该工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同参数重复调用该工具不会对其环境产生额外影响。默认值：false。
  • openWorldHint：如果为 true，则该工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体交互。例如，网页搜索工具是开放世界，而记忆工具不是开放世界。

破坏性提示：❌ | 幂等性提示：❌ | 只读提示：✅ | 开放世界提示：❌