Routes API 遷移指南

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

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

Routes API 提供許多新功能,包括:

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

如要進一步瞭解 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 計算路徑或計算路徑矩陣時,您必須指定要在回應中傳回哪些欄位。系統並未傳回傳回欄位的預設清單。如果省略這個清單,這個方法會傳回錯誤。

    建立回應欄位遮罩以指定欄位清單。然後,您可以使用網址參數 $fieldsfields,或使用 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_OPTIMALTRAFFIC_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 回應屬性的設定方式,並修改目前 Directions API 和 Distance Matrix API 回應中傳回的屬性,如下表所示:

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

    對應於要求中未設定的 departure_time

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

    對應 TRAFFIC_UNAWARE

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

    對應要求中的 departure_time 設定。

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

    對應於 TRAFFIC_AWARETRAFFIC_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
alternatives computeAlternativeRoutes
arrival_time 無法使用「TRANSIT」模式,因此無法使用。
avoid routeModifiers
copyrights

未包含在回應中。向使用者顯示結果時,您必須加入下列陳述式:

Powered by Google, ©YEAR Google

例如:

Powered by Google, ©2022 Google

departure_time departureTime
distance distanceMeters 距離僅適用於公尺。
duration_in_traffic 已在 Routes API 中移除,請使用 duration。詳情請參閱上方的新版 Routes API 的功能異動
language languageCode 僅適用於運算路徑。
mode travelMode

新增對 TWO_WHEELER 的支援。

TRANSIT」模式無法使用。

region regionCode

status 無法使用。針對 HTTP 回應錯誤,請使用 HTTP 回應代碼。詳情請參閱處理要求錯誤
traffic_model 不適用。
transit_mode 無法使用「TRANSIT」模式,因此無法使用。
transit_routing_preference 無法使用「TRANSIT」模式,因此無法使用。
units 不支援路徑矩陣。
waypoints intermediates
路線控點為 optimize=true 不適用。

從預覽版本遷移

Routes API 已於 2022 年 9 月發布為公開預先發布版 (正式發布前)。正式發布前產品受到《Google 地圖平台服務專屬條款》的規範。 詳情請參閱發布階段說明

本節說明如何將應用程式從預覽版本遷移至 Google Analytics (分析) 版本。

Analytics (分析) 版本新增功能

GA 版本新增以下新功能,不包含在預先發布版中:

  • 除了地點 ID 和緯度/經度座標,您現在可以使用以下方式在 Google Analytics (分析) 版本中指定位置

    • 地址字串 (「Chicago, IL」或「Darwin, NT, Australia」)

      地址字串通常是使用者輸入地址的方式。不過,{product_name} 必須先在內部為地址字串進行地理編碼,才能將其轉換為經緯度座標,才能計算路徑。

      此外,我們也新增了 regionCode 要求參數,可讓您指定傳回特定地理區域的地理編碼結果。

    • Plus Codes

      Plus Codes 就像是沒有實際地址的使用者或地點的街道地址。Plus Codes 並非使用包含街道名稱和數字的地址,而是以經緯度呈現,並以數字和字母顯示。

  • 運算路徑回應現在包含 geocodingResults 陣列。針對要求中所指定地址字串加號代碼的每個位置 (出發地、目的地或中繼路線控點),API 都會執行地點 ID 查詢。這個陣列的每一個元素都含有地點對應的地點 ID,以及有關該位置的其他中繼資料。要求中以地點 ID 或緯度/長期座標表示的位置將遭到忽略。

現有預覽功能異動

現在,您必須在要求中加入新陣列 extraComputations 欄位,在 Google Analytics (分析) 中明確啟用以下功能:

在預先發布版中,您使用欄位遮罩指定要在回應中傳回這些功能的相關資訊。現在您必須同時完成以下兩個動作:

  • 設定新的 extraComputations 陣列要求參數即可啟用這些功能。
  • 設定欄位遮罩,以指定在回應中傳回資訊。

重要須知

除非設定 extraComputations 明確啟用,否則 computeRouteMatrix 回應中將不再包含以下欄位:

  • travelAdvisory.tollInfo (收費路段)

除非設定 extraComputations 以明確啟用,否則computeRoutes 回應中將不再包含以下欄位:

  • routes.legs.travelAdvisory.tollInfo(收費資訊)
  • routes.travelAdvisory.tollInfo(收費資訊)
  • routes.travelAdvisory.fuelConsumptionMicroliters(油耗)
  • routes.travelAdvisory.speedReadingIntervals(折線上的流量)
  • routes.legs.travelAdvisory.speedReadingIntervals(折線上的流量)

我需要做些什麼?

要接收折線的收費資訊、油耗或路況的回應欄位,您必須設定新的要求陣列欄位 extraComputations,以包含下列一或多個值:

  • 如要接收收費資訊,請將新的 extraComputations 陣列欄位設為 "TOLLS"

  • 如要接收油耗,請將新的 extraComputations 陣列欄位設為 "FUEL_CONSUMPTION"

  • 如要接收折線的流量資訊,請將新的 extraComputations 陣列欄位設為 "TRAFFIC_ON_POLYLINE"