沿路線搜尋

search_along_route 工具可讓 LLM 根據自然語言查詢，找出旅遊路線沿途的地點，例如前往太浩湖途中的電動車充電站，或舊金山和聖荷西之間的咖啡店。工具會傳回 AI 生成的摘要，列出符合條件的地點，以及繞道前往這些地點的利弊。對於摘要中引用的每個地點，回應也會包含地點 ID、經緯度座標、Google 地圖連結、必要屬性和繞道指標。

每個 search_along_route 要求都是專業版選項，並依 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 可以在 search_along_route 中將 retrievalToken 值傳遞為 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 次查詢。如需定價資訊，請參閱主要價目表和印度價目表。