Routes API 目前為預先發布版 (正式發布前)。正式發布前的產品和功能支援有限，對正式發布前的產品和功能所做的變更可能與其他正式發布前的版本不相容。「正式發布前產品」受《Google 地圖平台服務專屬條款》規範。詳情請參閱發布階段說明。

Routes API 遷移指南

Google 地圖平台目前支援 Directions API 和 Distance Matrix API。這個新版 Routes API 包含現有 Directions API 和 Distance Matrix API 的新一代效能最佳化版本：

  • 運算路徑：運用全方位的全域轉送資料和即時流量計算不同位置之間的路線。
  • 「Compute Route Matrix」(運算路徑矩陣)：計算起點/目的地清單的距離和所需時間。

Routes API 提供許多新功能，包括：

  • TWO_WHEELER 轉送
  • 過路費計算
  • 交通意識折線
  • 折線品質控管機制
  • 品質延遲控管機制
  • 結果串流 (僅限使用 gRPC 的 Compute Route Matrix)
  • gRPC 支援

如要進一步瞭解 Routes API，請參閱 Routes API。

本指南說明如何遷移使用 Directions API 和 Distance Matrix API 的現有應用程式，以使用新的 Routes API。

新 Routes API 的功能異動

一般而言，Routes API 會對 Directions API 和 Distance Matrix API 進行下列變更：

  • 將 Compute Route 和 Compute Route Matrix 合併在名為 Routes API 的單一服務中

    您必須在 API 主控台中啟用 Routes API，才能使用 Compute Routes 和 Compute Route Matrix。您目前在 API 控制台中啟用了 Directions API 和 Distance Matrix API 做為個別服務。

    如需詳細資訊，請參閱在 Google API 控制台中設定一文。

  • New Routes API 使用 HTTP POST 要求

    在新的 Routes API 中，您會在要求主體或標頭中傳送參數做為 HTTP POST 要求的一部分。相較之下，使用 Directions API 和 Distance Matrix API 時，您會使用 HTTP GET 要求來傳遞網址參數。

    如需範例，請參閱：

  • 需要欄位遮蓋

    當您呼叫新的 Routes API 以計算路徑或計算路徑矩陣時，您必須指定要在回應中傳回哪些欄位。系統並未傳回傳回欄位的預設清單。如果省略這個清單，這個方法會傳回錯誤。

    建立回應欄位遮罩以指定欄位清單。然後，您可以使用網址參數 $fields 或 fields，或使用 HTTP/gRPC 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至每個方法。

    欄位遮罩是一個不錯的設計做法，可確保您不會要求不必要的資料，以避免不必要的處理時間和帳單費用。

    詳情請參閱選擇要傳回的欄位一文。

  • Compute 路徑矩陣的新要求限制

    Distance Matrix API 會強制執行以下要求限制：

    • 每個要求最多 25 個起點或 25 個目的地。
    • 每個伺服器端要求最多 100 個元素 (起點數 × 目的地數)。

    Compute 路徑矩陣會強制執行以下要求限制：

    • 元素數目不得超過 625。

    • 如果指定 TRAFFIC_AWARE_OPTIMAL，則元素數量不得超過 100。如要進一步瞭解 TRAFFIC_AWARE_OPTIMAL，請參閱設定品質和延遲時間一文。

    • 可使用地點 ID 可指定的路線控點 (出發地 + 目的地) 數量上限為 50。

  • 設定品質與延遲時間的新選項

    新的 Routes API 支援三種轉送偏好設定，可用來明確設定路徑品質與回應延遲時間：

    • TRAFFIC_UNAWARE (預設) - 使用平均獨立時間流量資料 (而非即時路況資料) 來計算路徑，藉此縮短回應延遲時間。這項設定相當於在 Directions API 和 Distance Matrix API 中使用流量時。

    • TRAFFIC_AWARE - 效能最佳化的即時流量品質以縮短延遲時間。這個路徑是 Routes API 的新設定，在 Directions API 和 Distance Matrix API 中無對等設定。

      與 TRAFFIC_AWARE_OPTIMAL 相比，某些最佳化作業會大幅縮短延遲時間。

    • TRAFFIC_AWARE_OPTIMAL - 高品質且完整的車流量資料，且不用套用大部分的效能最佳化。這項設定會產生最高延遲時間，等同於 Directions API 和 Distance Matrix API 中的 departure_time 設定。

      TRAFFIC_AWARE_OPTIMAL 轉送偏好設定相當於 maps.google.com 和 Google 地圖行動應用程式使用的模式。

    在 Directions API 和 Distance Matrix API 中，我們只會提供對等的 TRAFFIC_AWARE_OPTIMAL 和 TRAFFIC_UNAWARE 選項。系統會根據您是否設定 departure_time，以隱含方式設定這些選項。

    下表比較了 current Directions API 和 Distance Matrix API 選項以及新的 Routes API 選項：

    模式 目前的專案 Routes API Notes
    無即時路況 未設定「departure_time」屬性 TRAFFIC_UNAWARE 三種模式中最快的延遲時間。
    已套用即時路況 無對應報告 TRAFFIC_AWARE

    由 Routes API 新增模式。這個延遲時間的延遲時間略高於 TRAFFIC_UNAWARE，且 ETA 費用也略低。

    延遲時間比 TRAFFIC_AWARE_OPTIMAL 短很多。
    已套用高品質且完整的即時車流量資料 已設定 departure_time 項屬性 TRAFFIC_AWARE_OPTIMAL

    等同於 maps.google.com 和 Google 地圖行動應用程式使用的模式。

    如果是運算路徑矩陣，要求中的元素數量 (起點數 × 目的地數) 不得超過 100 個。

    Routes API 也會修改 duration 回應屬性的設定方式，並修改「目前」回應中傳回的屬性，如下表所示：

    旅遊預計到達時間 目前的專案 Routes API
    路況不受干擾且與時俱進的預計到達時間。

    對應於要求中未設定的 departure_time。

    • duration 回應屬性中包含的延展型文字廣告。
    • 系統不會傳回 duration_in_traffic 回應屬性。

    對應 TRAFFIC_UNAWARE。

    • duration 回應屬性中包含的延展型文字廣告。
    • duration 和 staticDuration 回應屬性中都含有相同的值。
    將即時流量納入考量的延展型文字廣告。

    對應要求中的 departure_time 設定。

    • 將即時流量納入考量的延展型文字廣告會包含在 duration_in_traffic 回應屬性中。

    對應於 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL。

    • 將即時流量納入考量的延展型文字廣告會包含在 duration 回應屬性中。
    • staticDuration 回應屬性包含通過路線時長，且不將路況納入考量。
    • 系統已不再支援 duration_in_traffic 屬性。

    詳情請參閱設定品質與延遲時間。

Routes API 不支援現有功能

Routes API 將不支援以下功能：

  • XML 做為回應格式。僅支援 JSON 和 gRPC。

  • 反向地址定位

    您現在可以使用 Reverse Geocoding API 建立適用於此用途的函式，並提供更優質的品質結果。

遷移至 Routes API

我們在 Routes API 中進行了多項變更。大多數變更都與舊版 API 回溯相容，但下方列出幾項破壞性變更，需要您將應用程式遷移至 Routes API 時才能採用。

更新 REST API 端點

如果您使用 Directions API，請更新程式碼來使用新的 Routes API 端點：

Directions API https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
Routes API https://routes.googleapis.com/directions/v2:computeRoutes

如果您使用 Distance Matrix API，請更新程式碼來使用新的 Routes API 端點：

Distance Matrix API https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
Routes API https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

轉換網址參數以使用 HTTP 要求主體

您可以利用 Directions API 和 Distance Matrix API 將設定屬性做為網址參數傳遞至 HTTP GET 要求。例如，針對 Directions API：

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

透過 Routes API，您可以在要求主體或標頭中傳送參數做為 HTTP POST 要求的一部分。如需範例，請參閱：

將目前的參數轉換為 Routes API 參數

下表列出目前 Directions API 和 Distance Matrix API 中已重新命名或修改的 參數，或 預覽 版本 不支援的 參數。使用這些參數時，請更新程式碼。

目前的參數 Routes API 參數 Notes
destination destination 預先發布版不支援地址和 Plus Code。
origin origin 預先發布版不支援地址和 Plus Code。
alternatives computeAlternativeRoutes
arrival_time 預覽功能不支援「TRANSIT」模式，因此無法使用此功能。
avoid routeModifiers
copyrights 不適用於預先發布版。
departure_time departureTime
distance distanceMeters 距離僅適用於公尺。
duration_in_traffic 已在 Routes API 中移除，請使用 duration。詳情請參閱上方的新版 Routes API 的功能異動。
language languageCode
mode travelMode

新增對 TWO_WHEELER 的支援。

「TRANSIT」無法預覽。
region 因為不支援地址，所以無法使用預覽功能。
status 不適用於預先發布版。針對 HTTP 回應錯誤，請使用 HTTP 回應代碼。詳情請參閱處理要求錯誤。
traffic_model 不適用於預先發布版。
transit_mode 預覽功能不支援「TRANSIT」模式，因此無法使用此功能。
transit_routing_preference 預覽功能不支援「TRANSIT」模式，因此無法使用此功能。
units 預先發布版不支援距離矩陣。
waypoints intermediates 預先發布版不支援地址和折線。
路線控點為 optimize=true 不適用於預先發布版。