為何要遷移至 Routes API？

歐洲經濟區 (EEA) 開發人員

Routes API 提升了計算路線、距離和行程時間的效能，因此建議您取代使用 Directions API 和 Distance Matrix API 的應用程式。Routes API 的大部分功能都與 Directions API 和 Distance Matrix API 回溯相容。

請參閱本指南，瞭解 Routes API 與取代產品的主要差異，以及如何處理必要變更。如要進一步瞭解其他 Routes API 功能，請參閱產品總覽。

主要改善項目

本節說明在應用程式中使用 Routes API 時，可望獲得的幾項強化功能。

提高要求上限

Routes API Compute Route Matrix
  • 最多 625 個元素，除非您指定 TRAFFIC_AWARE_OPTIMAL。
  • 最多可使用 100 個元素 (含 TRAFFIC_AWARE_OPTIMAL)。請參閱「強化路徑偏好設定」。
  • 使用地點 ID 時，最多可有 50 個路線控點 (起點 + 目的地)。
Distance Matrix API
  • 每項要求最多可包含 25 個起點或 25 個目的地。
  • 每個伺服器端要求最多 100 個元素 (起點數 × 目的地數)。

更快取得要求的回覆

Compute Route Matrix 功能提供下列延遲時間改善項目：

  • 在計算完整矩陣之前，接收回應的串流元素。
  • 使用欄位遮罩自訂回應詳細資料，只要求所需資料，這項最佳做法也有助於降低成本。
  • 強化車流量路線計算，讓您在資料品質和回應時間之間取得平衡。

轉送功能強化

計算路徑功能提供下列路徑強化功能：

  • 除了距離和預計到達時間外，還會顯示過路費資訊。
  • 雙輪車路線。
  • 評估中途停靠點，確保安全。
  • 設定路線控點的行進方向和道路側，提高預計抵達時間的準確度。

只要求提供您需要的資料

現在您可以指定要傳回的欄位，縮短處理時間並減少帳單費用。

Routes API
Compute Routes
Compute Route Matrix 		要求必須使用欄位遮罩，指定要在回應中傳回的欄位。欄位遮蓋可確保您不會要求不必要的資料，避免不必要的處理時間和帳單費用。
詳情請參閱「選擇要傳回的欄位」。
Directions API
Distance Matrix API 		即使應用程式不需要，也會傳回預設欄位清單。這可能會導致不必要的處理時間和帳單費用。

車流量的強化路線計算

Routes API 支援三種路線偏好設定，您可以在要求路況資訊時，用來平衡回應延遲時間和資料品質。

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

TRAFFIC_UNAWARE
(預設)		 使用與時間無關的平均流量資料 (而非即時流量資料) 計算路線，因此回覆延遲時間最短。這項設定等同於在 Directions API 和 Distance Matrix API 中不使用車流量。
TRAFFIC_AWARE
(新)		 即時流量品質經過最佳化，可縮短延遲時間。與 TRAFFIC_AWARE_OPTIMAL 不同，這項設定會套用最佳化功能，大幅降低延遲。這項設定也是 Routes API 的新功能，Directions API 或 Distance Matrix API 沒有對應的設定。
TRAFFIC_AWARE_OPTIMAL 高品質、全面的交通資訊。這項設定會產生最高延遲，相當於 Directions API 和 Distance Matrix API 中的 departure_time 設定。
這項偏好設定等同於 maps.google.com 和 Google 地圖行動應用程式使用的模式。

路線計算比較

下表比較 Routes API、Directions API 和 Distance Matrix API 服務的路線選項。

流量選項 Routes API Directions API
Distance Matrix API		 延遲時間
沒有即時車流量 TRAFFIC_UNAWARE 未設定 departure_time 項屬性 三種模式中延遲時間最短。
已套用即時路況 TRAFFIC_AWARE 無對應報告

Routes API 新增了模式。與 TRAFFIC_UNAWARE 相比，這項功能會稍微增加延遲時間，但預計抵達時間的準確度只會略微降低。

延遲時間比 TRAFFIC_AWARE_OPTIMAL 低得多。
套用高品質的全面即時車流量資料 TRAFFIC_AWARE_OPTIMAL departure_time 屬性集

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

以 Compute Route Matrix 來說，要求中的元素數 (起點數 × 目的地數) 不得超過 100。

主要差異

本節將說明 Routes API 與其取代的服務之間的主要差異，以及從現有應用程式中的這些服務遷移時，如何解決這些差異。

呼叫一項服務，而非兩項

Routes API 在 API 控制台中，為應用程式啟用一項服務，以便使用 Compute Routes 和 Compute Route Matrix。
詳情請參閱「在 Google API 控制台中設定」。
Directions API
Distance Matrix API 		在 API 控制台中，分別啟用 Directions API 和 Distance Matrix API 這兩項服務。

使用 HTTPS POST 項要求

Routes API 在要求內文或標頭中傳遞參數，做為 HTTP POST 要求的一部分。
如需範例，請參閱：
- 計算路線
- 計算路線矩陣
Directions API
Distance Matrix API 		使用 HTTP GET 要求傳遞網址參數。

預計到達時間回覆差異

Routes API 會傳回預計抵達時間，並以不同於 Directions API 和 Distance Matrix API 服務的方式使用 duration 回應屬性，如下表所示。

預計到達時間類型 Routes API Directions API
Distance Matrix API
不考慮路況，預計到達時間與時間無關。

使用 TRAFFIC_UNAWARE 設定。

  • duration 回應屬性中包含的預計抵達時間。
  • duration 和 staticDuration 回應屬性包含相同的值。

對應於要求中未設定 departure_time。

  • duration 回應屬性中包含的預計到達時間。
  • 不會傳回 duration_in_traffic 回應屬性。
考量即時路況的預計到達時間。

使用 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL 進行設定。

  • duration 回應屬性中包含考量即時路況的預計抵達時間。
  • staticDuration 回應屬性包含不考慮路況的路線行車時間。
  • 系統不再傳回 duration_in_traffic 屬性。

在要求中使用 departure_time 進行設定。

  • duration_in_traffic 回應屬性中包含考量即時路況的預計抵達時間。

折線路線控點

這項服務支援 POST 要求主體，因此不再受網址字串限制影響，您也不必再將經緯度座標轉換為折線航點。部分 Distance Matrix API 使用者將經緯度點轉換為折線路線控點，解決了要求限制問題。

格式化地址 (反向地理編碼)

Routes API 不會在回應中提供格式化地址。如要取得格式化地址，請使用 Geocoding API，這項 API 專為這個用途而建構，可提供更高品質的結果。

可用的交通方式

與 Directions API 相同，如果路線要求未指定交通方式，Routes API 會使用 DRIVE 做為預設模式。不過，如果要求確實指定了路線的交通方式，Routes API 就不會傳回可用交通方式的陣列，做為要求的替代選項。如果您的應用情境需要這項功能，請提出問題，說明您如何使用這項功能，我們會與您聯絡。

XML 做為回應格式

Routes API 不會以 XML 格式提供回應。網路上有許多 JSON 轉 XML 轉換器，應該能滿足您的需求。