計算路徑

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

本頁面說明要求選項 (包括 Pro 選項)、回覆內容，以及要求的計費方式。如需完整的工具結構定義，請參閱 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 選項

有兩個選項可選取 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 計費。這個選項也會增加延遲時間。

在受限正式發布期間，如果專案不在 Pro 許可清單中，這個選項會視為 ROUTING_PREFERENCE_TRAFFIC_UNAWARE。詳情請參閱「受限正式發布期間的 Pro 選項」。

範例

下列要求會索取考量路況的行車路線，其中包含一個中途停靠點和一條編碼折線。系統會依 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
}

回應

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

  • distanceMeters：路線的移動距離，以公尺為單位。
  • duration：行經路線所需的時間。使用 ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL 時，時間長度會考量路況。
  • encodedPolyline：當 include_polyline 為 true 時，路線的路徑會以編碼折線表示。您可以搭配其他 Google 地圖平台 API，在地圖上繪製路線。
  • attribution：必須與路線一併顯示的作者資訊。請參閱「出處規定」。

受限正式發布期間的 Pro 選項

在受限正式發布階段，只有 Pro 許可清單中的專案才能使用 Pro 選項。如果專案尚未加入許可清單：

  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL 會視為 ROUTING_PREFERENCE_TRAFFIC_UNAWARE，並依 Essentials SKU 計費。
  • 如果要求包含超過 10 個中繼路線控點，系統會傳回 INVALID_ARGUMENT 錯誤 (「最多支援 10 個中繼路線控點」)。

如要申請存取權，請參閱「受限正式發布期間的專業選項」。

計費和配額

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

要求替代路線、折線、出發或抵達時間，或不同的交通方式，都不會變更 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 之間)。
  • 這項工具不會傳回即時路線步驟、路段或大眾運輸路線詳細資料。