Directions API (舊版) 是一項網路服務,可計算開車、步行、單車和大眾運輸的地點間路線 (包括含路線控點的多段路線),並以 JSON 或 XML 格式傳回路線、路段和步驟。目前處於舊版狀態:自 2026 年 10 月起,新的 Google Cloud 雲端專案將無法啟用這項 API,請改用 Routes API。
Directions API:重要資訊
- 產品:Directions API
- 舊稱:Directions API (舊版)
- 類別:路徑
- 平台:網路服務 (REST)
- 執行位置:伺服器 (後端程式碼)
- 推出階段:GA
- 生命週期:舊版
- 取代為:Routes API
- 總覽:Directions API 總覽
- 適用地區:全球。涵蓋範圍因區域和交通方式而異 (大眾運輸取決於大眾運輸供應商提供的資料)。(涵蓋範圍詳細資料)
Directions API:使用時機
Directions API 適用情況:
- 您維護的現有 Google Cloud 雲端專案已啟用 Directions API (舊版) 並呼叫
maps/api/directions。 - 您需要現有專案中,以 JSON 或 XML 格式提供的伺服器端開車、步行、單車或大眾運輸路線 (路線控點僅適用於非大眾運輸模式)。
不適合使用 Directions API 的情況:
- 您正在啟動新的 Google Cloud 雲端專案;自 2026 年 10 月起,新專案無法啟用 Directions API (舊版)。請改用 Routes API。
- 您需要新的轉送功能和更優異的效能。請改用 Routes API。
- 您需要在單一要求中,取得多個出發地和目的地的行程時間和距離。請改用 Routes API。
Directions API:設定
- 要啟用的服務:
directions-backend.googleapis.com - 驗證:API 金鑰
- 開始使用:設定 Directions API
- 參考資料:Directions API 參考資料
- 定價:Directions API 用量與計費
- 政策:Directions API 政策
- 版本資訊:Directions API 版本資訊
Directions API:常見錯誤
- 問題:如果專案未啟用舊版 API,向 Directions API (舊版) 提出的要求會失敗,並傳回
LegacyApiNotActivatedMapError。修正方式:如果您是應用程式擁有者,請遷移至 Routes API。在遷移或等待應用程式更新期間,您可以填寫舊版 API 啟用表單,啟用舊版 API 做為短期解決方案。請參閱 /maps/legacy。 - 問題:在路線控點上使用
via:前置字元,會使路線控點成為嚴格的經過點,可能導致嚴重繞路或ZERO_RESULTS狀態。修正方式:除非需要嚴格的通過點,否則請使用中途停靠點 (不含via:前置字元)。請參閱 /maps/documentation/directions/get-directions。 - 問題:如果要求包含 11 到 25 個路線控點、
optimize:true、考量路況的車程時間 (duration_in_traffic),或side_of_road/heading位置修飾符,則會以較高的 Directions Advanced (Pro) SKU 計費。修正方式:只在必要時使用這些功能;將路線控點數量控制在 10 個以下,並省略optimize:true、departure_time(開車)、side_of_road和heading,即可繼續使用 Essentials SKU。請參閱 /maps/billing-and-pricing/sku-details/legacy#directions-advanced-pro-sku。 - 問題:如果是開車,
departure_time不得為過去時間 (要求會失敗並傳回INVALID_REQUEST)。如果沒有departure_time,路線和時間長度會使用不限時間的平均路況,且不會傳回duration_in_traffic。修正方式:將departure_time設為now或未來時間,並使用mode=driving取得duration_in_traffic。傳回duration_in_traffic的要求會以 Directions Advanced (Pro) SKU 計費。請參閱 /maps/documentation/directions/get-directions。