Directions API 快速參考

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 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。