計算路徑

compute_routes 工具會傳回指定交通方式的起點和目的地之間的路線。回應會包含路線的距離和時間長度。根據預設，系統計算路線時不會考量即時路況。Pro 則會考量即時路況，並提供更多中途停靠站的路線。

您可以透過 MCP 伺服器或 computeRoutes REST 方法呼叫 compute_routes。本頁面說明要求選項 (包括 Pro 選項)、回應內容，以及要求的計費方式。如需完整結構定義，請參閱 compute_routes MCP 參考資料和 computeRoutes REST 參考資料。

要求選項

下表說明 compute_routes 的要求選項：

選項	說明
`origin`、`destination`	必填。每個都是路線控點：`address` (人類可讀地址或 Plus Code)、`place_id` 或 `lat_lng`。您可以混合使用格式，例如起點使用地址，目的地使用地點 ID。
`travel_mode`	交通方式：`DRIVE` (預設)、`WALK`、`BICYCLE` 或 `TRANSIT`。`WALK`路線目前為 Beta 版，有時可能不會顯示清楚的人行道或行人路徑。在應用程式中顯示步行路線時，必須向使用者顯示這則警告。
`routing_preference`	如何使用車流量資料計算路線：`ROUTING_PREFERENCE_TRAFFIC_UNAWARE` (預設) 或 `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL` (Pro 選項)。`WALK`或`BICYCLE`不支援`ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`。請參閱「車流量監測路線」。
`intermediate_waypoints`	起點和目的地之間的停靠點順序。路線會依指定順序通過這些控點。一項要求最多可包含 10 個中繼路線控點，或 11 到 25 個 (Pro 選項)。如果要求超過 25 個，則會傳回 `INVALID_ARGUMENT` 錯誤。大眾運輸路線不支援中途路線控點。
`departure_time` 或 `arrival_time`	從起點出發或抵達目的地的時間，採用 RFC 3339 時間戳記。最多只能設定一個。預設為目前時間出發。`TRANSIT` 的時間最多可設為過去 7 天或未來 100 天。如果是其他交通方式，則時間不得早於當下，且最多可設為 365 天後。
`compute_alternative_routes`	設為 `true` 時，除了建議路線外，回應也會包含替代路線 (如有)。預設為 `false`。
`include_polyline`	如果 `true`，回應中的每條路線都會包含 `encodedPolyline`。預設值為 `false`。
`location_bias`	經緯度座標，可偏重文字路線控點的解析方式，例如消除地址歧義。

Pro 選項

其中兩個選項會選取 Maps Grounding Pro SKU。使用其中一項或兩項功能的要求，會以 Pro SKU 計費：

Pro 選項	適用時機
`routing_preference`已設在`ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`	使用者詢問車流量、塞車情況，或考量目前路況後的行程時間。請參閱「車流量監測路線」。
11 到 25 `intermediate_waypoints`	路線在起點和目的地之間需要超過 10 個停靠站。

所有其他選項 (包括交通模式、時間、替代路線、折線和位置偏誤) 則會依 Essentials SKU 計費。

流量感知轉送

根據預設，系統計算路線時不會考量即時路況 (ROUTING_PREFERENCE_TRAFFIC_UNAWARE)。這項設定的延遲時間最短。這項設定適用於不考慮或不適用路況的要求，例如步行路線或粗略規劃。

將 routing_preference 設為 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL，即可根據目前的交通狀況 (如有交通資料) 計算路線和所需時間。當使用者詢問目前開車需要多久時間時，請使用這項工具。如果是 TRANSIT 路線，這項設定會使用即時大眾運輸資料 (例如誤點和取消)，不支援 WALK 或 BICYCLE 路線，這類要求會傳回 INVALID_ARGUMENT 錯誤。這是 Pro 選項，因此要求會依 Pro SKU 計費。這個選項也會增加延遲時間。

範例

下列 MCP 要求會要求提供考量路況的行車路線，其中包含一個中途停靠點和一條編碼折線。系統會依 Pro SKU 計費：

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

下列範例會將相同要求傳送至 computeRoutes REST 方法：

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "origin": {"address": "Ferry Building, San Francisco, CA"},
  "destination": {"address": "Golden Gate Park, San Francisco, CA"},
  "intermediateWaypoints": [
    {"address": "Palace of Fine Arts, San Francisco, CA"}
  ],
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includePolyline": true
}' \
"https://mapstools.googleapis.com/v1:computeRoutes"

將 API_KEY 替換為您的 API 金鑰。

回應

回應包含 routes[]，並依推薦程度由高到低排序。除非 compute_alternative_routes 為 true，否則只會傳回一條路線。每條路徑都包含：

distanceMeters：：路線的移動距離，以公尺為單位。
duration：行經路線所需的時間。使用 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL 時，時間長度會考量路況。
encodedPolyline：當 include_polyline 為 true 時，路線的路徑會以編碼折線表示。您可以搭配其他 Google Maps Platform API，在地圖上繪製路線。
retrievalToken：為 DRIVE 路線傳回的不透明權杖 (10 分鐘內有效)，可傳遞至 search_along_route，用於尋找該路線沿途的地點，而不必重新傳送路線控點。
attribution：必須與路線一併顯示的作者資訊。請參閱作者資訊相關規定。

計費和配額

每個 compute_routes 要求都是一個計費事件：

如果要求未使用任何 Pro 選項，則會依 Maps Grounding Essentials SKU 計費。
使用 Pro 選項的要求會依 Maps Grounding Pro SKU 計費。在單一要求中同時使用兩個 Pro 選項，費用不會改變。如要瞭解 Pro 定價，請參閱「比較 Essentials、Pro 和利用 Google 地圖建立基準」。

要求替代路線、折線、出發或抵達時間，或不同的交通方式，都不會變更 SKU。

compute_routes 配額為每項專案每分鐘 300 次查詢，由兩個 SKU 共用。如需定價資訊，請參閱主要價目表和印度價目表。

限制

一項要求最多可包含 25 個中繼路線控點，其中 11 到 25 個為 Pro 選項。如果要求超過這個數量，系統會傳回 INVALID_ARGUMENT 錯誤。
大眾運輸路線不支援中繼路線控點。如果大眾運輸要求包含中途路線控點，則會傳回 INVALID_ARGUMENT 錯誤。
步行或單車路線不支援ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL。
如果是大眾運輸路線，出發和抵達時間最多可設為過去 7 天或未來 100 天。如果是其他交通方式，則不得為過去的時間，且最多可提前 365 天。
路線控點座標必須在有效的地理範圍內 (緯度介於 -90 到 90，經度介於 -180 到 180)。
這項工具不會傳回即時路線步驟、路段或大眾運輸路線詳細資料。