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-backend.googleapis.com - 驗證:API 金鑰
- 開始使用:設定 Distance Matrix API
- 參考資料:Distance Matrix API 參考資料
- 定價:Distance Matrix API 用量與計費
- 政策:Distance Matrix 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 APIcomputeRouteMatrix(搭配X-Goog-FieldMask標頭)。透過表單啟用舊版 API 只是短期措施。請參閱 /maps/legacy#LegacyApiNotActivatedMapError。