Distance Matrix API 快速參考

Distance Matrix API (舊版) 是一項網路服務,可根據每組起點和目的地之間的建議路線,傳回移動距離和時間。您可以設定交通方式 (開車、步行、單車、大眾運輸)、大眾運輸模式、單位,以及依路況計算時間的出發時間。傳回 JSON 或 XML。

Distance Matrix API:重要資訊

  • 產品:Distance Matrix API
  • 別名:Distance Matrix API (舊版)、Distance Matrix (舊版)
  • 類別:路徑
  • 平台:網路服務 (REST)
  • 執行位置:伺服器 (後端程式碼)
  • 推出階段:GA
  • 生命週期:舊版
  • 取代為:Routes API
  • 總覽:Distance Matrix API 總覽

Distance Matrix API:使用時機

Distance Matrix API 適用情況:

  • 您維護的現有專案已啟用 Distance Matrix API (舊版),並呼叫 /maps/api/distancematrix。
  • 您需要從伺服器取得多個起點和多個目的地之間的交通距離和時間。
  • 您需要使用 departure_time 和選用的 traffic_model,取得開車時的車流量持續時間。

請勿在下列情況使用 Distance Matrix API:

  • 您要建立新的 Google Cloud 專案。2026 年 10 月起,新專案將無法啟用 Distance Matrix API (舊版)。請改用 Routes API。
  • 您需要新功能,或最多 625 個元素的路徑矩陣,且須支援串流回應 (computeRouteMatrix)。請改用 Routes API。
  • 您需要包含步驟和折線的完整路線,而不只是距離和時間長度值。請改用 Routes API。

Distance Matrix API:設定

Distance Matrix API:常見錯誤

  • 問題:每項伺服器端要求最多只能包含 100 個元素 (起點 × 目的地),且起點或目的地數量不得超過 25 個。如果要求過大,則會傳回 MAX_ELEMENTS_EXCEEDED 或 MAX_DIMENSIONS_EXCEEDED。修正方式:將矩陣分割成多個要求,每個要求最多包含 100 個元素和 25 個起點或目的地。請參閱 /maps/documentation/distance-matrix/usage-and-billing#usage-limits。
  • 問題:如未指定 departure_time,系統會根據不考慮時間的平均路況來選擇路線和時間,且不會傳回 duration_in_traffic。結果可能隨時間而異。修正方式:將 departure_time 設為 now,或使用 mode=driving 設為未來時間,即可取得考量路況的車程時間。請注意,車流量要求會以較高的費率計費。請參閱 /maps/documentation/distance-matrix/distance-matrix。
  • 問題:units 參數只會變更距離欄位中的文字,距離值的單位一律為公尺。修正方式:將 distance.value 視為公尺,或使用 distance.text 顯示。請參閱 /maps/documentation/distance-matrix/distance-matrix。
  • 問題:從未啟用 Distance Matrix API (舊版) 的專案呼叫該 API 時,status 會傳回 REQUEST_DENIED,並顯示連結至 LegacyApiNotActivatedMapError 的 error_message。AI 助理預設通常會生成舊版 API 程式碼。修正方式:改用 Routes API computeRouteMatrix (搭配 X-Goog-FieldMask 標頭)。透過表單啟用舊版 API 只是短期措施。請參閱 /maps/legacy#LegacyApiNotActivatedMapError。