沿路线搜索

借助 search_along_route 工具，LLM 可以根据自然语言查询查找旅行路线沿途的地点，例如前往太浩湖途中的电动车辆充电站，或旧金山和圣何塞之间的咖啡店。该工具会返回 AI 生成的摘要，其中包含匹配的地点及其绕行权衡。对于摘要中引用的每个地点，响应还包含地点 ID、纬度/经度坐标、Google 地图链接、必需的属性和绕行指标。

每个 search_along_route 请求都是 Pro 选项，并根据 Maps Grounding Pro SKU 计费。

您可以通过 MCP 服务器或作为 searchAlongRoute REST 方法调用 search_along_route。本页面介绍了请求选项、如何指定路线、响应包含的内容以及请求的结算方式。如需查看完整架构，请参阅 search_along_route MCP 参考文档和 searchAlongRoute REST 参考文档。

请求选项

LLM 在调用工具时，会根据用户请求和工具说明设置这些选项。您可以使用自己的指令来影响模型使用的选项；请参阅控制 Pro 使用情况。

下表介绍了 search_along_route 的请求选项：

选项	说明
`text_query`	必需。用于搜索沿途地点的自然语言搜索查询，例如 `ev chargers`、`coffee` 或 `vegetarian restaurants`。
`retrieval_token`、`route_endpoints` 或 `encoded_polyline`	必需。要沿其搜索的路线。在每个请求中指定这三个字段之一。请参阅指定路线。
`travel_mode`	可选。用于计算路线和绕行路线的交通方式：`DRIVE`（默认）、`WALK` 或 `BICYCLE`。`WALK` 和 `BICYCLE` 仅支持 `route_endpoints`。`TRANSIT` 不受支持。`WALK`路线功能目前处于 Beta 版阶段，有时可能无法提供清晰的人行道或步行道。对于应用中显示的所有步行路线，您都必须向用户显示此警告。
`routing_preference`	可选。如何使用路况数据来计算路线和绕行时间：`ROUTING_PREFERENCE_TRAFFIC_UNAWARE`（默认）或 `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`。`ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL` 会使用实时路况信息（如有），但 `WALK` 或 `BICYCLE` 不支持此功能。
`include_extended_details`	可选。如果为 `true`，则摘要会包含扩展地点详情，例如评价中的分析洞见、菜单项、氛围、游客提示、电动汽车充电桩可用性或油价。默认值为 `false`。
`language_code`	可选。摘要和本地化绕行距离的 BCP-47 语言代码，例如 `en-US` 或 `ja`。默认值为 `en-US`。
`region_code`	可选。用户的两位字母 CLDR 地区代码，例如 `US` 或 `CA`。会影响特定区域的地名，并可能根据适用法律影响结果。

指定路线

每个 search_along_route 请求都必须使用三个互斥字段之一指定路由。设置多个路由字段或省略所有三个路由字段都会返回 INVALID_ARGUMENT 错误。

下表比较了指定路由的三种方式：

路线选项	输入格式	支持的出行方式	返回 `detourDuration`	适用情形
`retrieval_token`	先前 `compute_routes` 响应中的 `retrievalToken` 字符串（有效期为 10 分钟）	`DRIVE`	是	代理已调用 `compute_routes` 来获取驾车路线（包括包含中间停靠点的路线），并且用户询问该路线沿途的地点。
`route_endpoints`	包含 `origin` 和 `destination` 航点（`address`、`place_id` 或 `lat_lng`）的对象	`DRIVE`、`WALK`、`BICYCLE`	是	用户要求一步找到两个地点之间的场所，而无需先调用 `compute_routes`，或者路线使用步行或骑车。
`encoded_polyline`	表示驾车路线的编码多段线字符串	`DRIVE`	否（仅返回 `localizedDetourDistance`）	您的应用已具有来自其他来源（例如 Routes API）的路线多段线。

连锁店 `compute_routes` 和 `search_along_route`

当 compute_routes 请求使用 DRIVE 出行方式时，响应中的每条路线都包含一个 retrievalToken 字段。此令牌的有效期为 10 分钟，用于对计算出的路线（包括任何中间停靠点）进行编码。当用户接着询问该路线沿途的地点时，LLM 可以将 retrievalToken 值作为 search_along_route 中的 retrieval_token 传递。

扩展地点详情

当用户的请求需要沿途的定性数据分析、实时路况或特殊属性时，请将 include_extended_details 设置为 true，例如：

评价者的反馈：基于评价的分析洞见、客户情绪和反馈。
具体推介项目：菜单项、菜肴、特色食品、饮料或商家亮点。
氛围：室内装饰、美学风格、环境或氛围。
实用的游客提示和实时数据：是否需要提前预订、等待时间、地点的繁忙程度、电动汽车充电桩可用性、油价、停车和设施。

对于沿路线进行的标准搜索（例如按位置、营业时间和绕行时间查找加油站、休息站或咖啡店），请将 include_extended_details 设置为 false（默认值）。包含扩展详情的请求需要更长时间才能完成，但不会产生额外费用，因为每个 search_along_route 请求都已按 Pro SKU 计费。

示例

以下 MCP 请求使用 route_endpoints 和路况感知路线规划功能搜索旧金山和太浩湖之间的电动车辆充电站：

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

以下示例使用先前 compute_routes 响应中的 retrieval_token：

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

将 RETRIEVAL_TOKEN 替换为 compute_routes 返回的 retrievalToken 字符串。

以下示例向 searchAlongRoute REST 方法发送第一个请求：

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"

将 API_KEY 替换为您的 API 密钥。

响应

响应包含以下字段：

summary：搜索结果和绕行权衡的自然语言摘要。它可能包含从零开始的引用（例如 [0]），这些引用会映射到 results 中的条目。
results[]：摘要中提及的地点的排名列表。每个条目都包含：
- place：地点的详细信息：
  - place：地点的资源名称，格式为 places/{id}。
  - id：地点 ID。您可以将其与其他 Google Maps Platform API 搭配使用，例如在地图上显示地点。
  - location：地点的纬度/经度坐标。
  - googleMapsLinks：指向地点 (placeUrl)、路线 (directionsUrl)、评价 (reviewsUrl)、照片 (photosUrl) 和撰写评价 (writeAReviewUrl) 的 Google 地图链接。
  - attribution：您必须随地点一起显示的提供方说明。请参阅提供出处的要求。
- detourSummary：沿路线在此地点停留所需的额外行程时间和距离：
  - localizedDetourDistance：以请求语言设置格式的额外距离，例如 "1.2 mi" 或 "1.9 km"。
  - detourDuration：额外行程时间，以时长字符串表示，例如 "180s"。如果使用 encoded_polyline 指定路由，则不会设置此字段。
contentToken：智能体数据可视化令牌（预览版），可让您使用 Places UI Kit 在回答中显示地点，而无需支付额外费用。当响应中包含至少一个地点时返回。

如需了解完整的字段详情，请参阅 search_along_route 参考文档。

结算和配额

每个 search_along_route 请求都是 Maps Grounding Pro SKU 下的一个可结算事件。将 include_extended_details 设置为 true 或将 routing_preference 设置为 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL 不会产生额外费用。如果您的智能体先调用 compute_routes，然后将 retrieval_token 传递给 search_along_route，则每次工具调用都会作为单独的请求计费。

如果您使用 Places UI Kit 显示 search_along_route 响应中的地点，则可以使用智能体数据可视化令牌（预览版），这样这些 Places UI Kit 请求就不会产生费用。

search_along_route 配额为每个项目每分钟 300 个查询。如需了解价格，请参阅主价格表和印度价格表。