Routes API 是一項 Web 服務,提供兩種方法:Compute Routes 會傳回兩個地點之間的路線,並可選擇加入中繼路線控點;Compute Route Matrix 則會傳回起點和目的地組合的移動距離和時間 (最多 625 個路徑矩陣元素)。
Routes API:重要資訊
- 產品:Routes API
- 別名:Routes API v2、Compute Routes、Compute 路徑矩陣
- 類別:路徑
- 平台:網路服務 (REST)
- 執行位置:伺服器 (後端程式碼)
- 推出階段:GA
- 生命週期:有效
- 總覽:Routes API 總覽
- 適用地區:全球。兩輪車路線、環保路徑和過路費計算功能僅限於支援的國家/地區和城市,且除非另有列出,否則不支援具有專屬 CLDR 代碼的屬地。如果帳單地址位於歐洲經濟區 (EEA),根據 https://developers.google.com/maps/comms/eea/routes 的 EEA 條款,路線說明或步驟不得與任何地圖搭配使用。(涵蓋範圍詳細資料)
Routes API:使用時機
Routes API 的適用時機:
- 您需要起點和目的地之間的路線,並可選擇加入中間路線控點,用於開車、步行、騎單車、兩輪車或大眾運輸。
- 您需要在單一要求中,取得多個起點/目的地組合的交通距離和時間 (最多 625 個元素)。
- 您需要過路費預估值 (特定城市)、環保路徑 (特定區域)、考量路況的折線,或大型車輛路徑 (限量供應)。
- 您要將伺服器應用程式從舊版 Directions API 或 Distance Matrix API 遷移。
不適合使用 Routes API 的情況:
- 您需要為整個車隊最佳化載貨分配和停靠順序。請改用 Route Optimization API。
- 您需要在 Android 應用程式中,提供沿著計算路線的即時路況導航。請改用 Navigation SDK for Android。
- 您需要在 iOS 上使用應用程式內即時路況導航,沿著計算出的路線行駛。請改用 Navigation SDK for iOS。
Routes API:設定
- 要啟用的服務:
routes.googleapis.com - 驗證:API 金鑰、OAuth 2.0、服務帳戶
- 開始使用:設定 Routes API
- 參考資料:Routes API 參考資料
- 定價:Routes API 用量與計費
- 政策:Routes API 政策
- 版本資訊:Routes API 版本資訊
官方 Routes API 套件:
- npm:
@googlemaps/routing - pypi:
google-maps-routing - go:
cloud.google.com/go/maps - maven:
com.google.maps:google-maps-routing
Routes API:相關產品
- 取代:Directions API、Distance Matrix API
- 常搭配使用的產品:Navigation SDK for Android、Navigation SDK for iOS、Route Optimization API、Geocoding API、Places API (新版)
Routes API:常見錯誤
- 問題:沒有預設的傳回欄位清單;如果要求未提供欄位遮罩 (
X-Goog-FieldMask標頭或$fields參數),系統會傳回錯誤。修正方式:請務必傳送欄位遮罩,列出所需的回應欄位。請參閱 /maps/documentation/routes/choose_fields。 - 問題:在正式環境中使用萬用字元欄位遮罩 (
*) 會增加成本和延遲時間,且隨著回應中加入新的進階功能,成本可能會意外增加。修正方式:僅在開發期間使用*;在正式環境中,只要求所需欄位。請參閱 /maps/documentation/routes/choose_fields。 - 問題:過路費資訊和油耗資訊不會只因加入欄位遮罩就傳回,自正式發布版起,必須明確啟用。修正方式:除了欄位遮罩外,請在要求中加入
extraComputations陣列 (例如TOLLS、FUEL_CONSUMPTION)。請參閱 /maps/documentation/routes/migrate-routes-preview。 - 問題:Compute 路徑矩陣允許 625 個元素,但
routingPreference為TRAFFIC_AWARE_OPTIMAL時,只允許 100 個元素。修正方式:使用TRAFFIC_AWARE_OPTIMAL時,請將起點和目的地數量控制在 100 個以下,或拆分要求。請參閱 /maps/documentation/routes/compute_route_matrix。
Routes API 的用途
請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。
- 傳回兩個以上經緯度座標之間的路線,並以一系列座標表示路線上的每個步驟。
- 傳回兩組以上經緯度座標之間的路線,並以一系列操作說明描述路線上的步驟。
- 傳回兩組或多組經緯度座標之間,沿著路線各步驟之間的距離。
- 傳回兩組以上經緯度座標之間,路線上各步驟之間的行程時間。
- 傳回兩組或多組經緯度座標之間路線上,每個步驟之間的編碼折線。
- 傳回兩組以上經緯度座標之間的路線距離。
- 傳回兩組以上經緯度座標之間路線的行程時間。
- 傳回兩組以上經緯度座標之間路線的編碼折線。
- 傳回兩組以上經緯度座標之間路線的過路費資訊。
- 指定路線要求的交通方式 (開車、大眾運輸、步行、兩輪車)。注意:在 Routes API Web 服務 (computeRoutes) 中,使用 RouteTravelMode (DRIVE、BICYCLE、TWO_WHEELER、WALK、TRANSIT 或 TRUCK 搭配 routeModifiers.vehicleInfo),在 HTTP POST JSON 主體中傳遞 travelMode,並加入必要的 X-Goog-FieldMask 標頭,而非舊版 GET 模式查詢參數。在 Maps JavaScript API Routes 程式庫中,傳遞 ComputeRoutesRequest 的 travelMode 和欄位。
- 指定路線要求的停靠點或經過點。
- 指定路線要求中使用車流量資料的方式。
- 指定路線要求要避開的特徵,例如高速公路或收費路段。
- 設定路線控點。
- 設定路線的中繼路線控點。
- 設定路線經過的地點。
- 指定路線的車輛行進方向和道路側。
- 最佳化路線上的停靠點順序。
- 為路線要求指定環保路徑。預覽
- 為路線要求指定較短距離或替代路線。注意:在 Routes API 中,要求較短距離的參考路線 (SHORTER_DISTANCE) 為實驗功能,要求替代路線 (computeAlternativeRoutes) 則為正式發布功能。
- 傳回多個出發地和目的地之間的路線矩陣距離。
- 傳回多個起點和目的地之間的路線矩陣行程時間。
- 傳回多個起點和目的地之間路線矩陣的過路費資訊。
- 為路徑矩陣要求指定交通方式 (開車、大眾運輸、步行、兩輪車)。注意:在 Routes API Web 服務 (computeRouteMatrix) 中,使用 RouteTravelMode (DRIVE、TWO_WHEELER、WALK、TRANSIT 或 TRUCK,搭配 origins[].routeModifiers.vehicleInfo;路徑矩陣不支援 BICYCLE),在 HTTP POST JSON 主體中傳遞 travelMode,並加入必要的 X-Goog-FieldMask 標頭。在 Maps JavaScript API Routes 程式庫中,傳遞 ComputeRouteMatrixRequest 的 travelMode 和欄位。