為何要遷移至 Routes API？

Routes API 提升計算路線、距離和交通時間的效能，因此取代目前使用 Directions API 和 Distance Matrix API 的應用程式也十分值得。Routes API 的大多數功能都與 Directions API 和 Distance Matrix API 回溯相容。

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

重要改善項目

本節說明在應用程式中使用 Routes API 時的一些改善項目。

提高要求上限

Routes API
  • 除非指定 TRAFFIC_AWARE_OPTIMAL，否則上限為 625 個元素。
  • 含有 TRAFFIC_AWARE_OPTIMAL 的元素上限為 100 個。請參閱加強型轉送偏好設定。
  • 使用地點 ID 時，最多可使用 50 個路線控點 (起點 + 目的地)。
Distance Matrix API
  • 每項要求最多 25 個起點或 25 個目的地。
  • 每個伺服器端要求最多 100 個元素 (起點數 × 目的地數量)。

加快要求回應的速度

運算路線矩陣功能提供以下延遲改善項目：

  • 在計算整個矩陣之前，接收回應的串流元素。
  • 使用欄位遮罩自訂回應詳細資料，只要求需要的資料，這是也能降低費用的最佳做法。
  • 加強流量計算功能，方便您在資料品質和回應時間之間做出取捨。

路徑強化功能

運算路徑功能提供以下轉送強化功能：

  • 通行費資訊，以及距離和預計到達時間。
  • 2 輪車輛路線。
  • 設定行經停靠點的路線控點，以確保安全。
  • 設定路線控點的行進方向和道路方向，提高預計到達時間準確度。

僅要求所需資料

您現在可以指定要傳回哪些欄位，藉此減少處理時間和帳單費用。

Routes API 要求必須使用欄位遮罩來指定要在回應中傳回的欄位。欄位遮蓋功能可確保您不會要求不必要的資料，以免產生不必要的處理時間和帳單費用。
詳情請參閱「選擇要傳回的欄位」。
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 會傳回預計到達時間，並使用 duration 回應屬性與 Directions API 和 Distance Matrix API 服務不同，如下表所示。

預計到達時間類型 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，並提供品質更好的結果。

可用的交通方式

如同使用 Directions API，Routes API 會在路線要求未指定交通模式時，使用 Drive 做為預設模式。不過，如果要求確實指定路線的交通方式，Routes API 不會傳回可用的交通方式陣列做為要求的替代選項。如果您的用途需要這項功能，請回報問題，並說明這項功能的使用方式，以便我們後續追蹤。

XML 做為回應格式

Routes API 並未提供 XML 做為回應格式。您可以在線上找到許多符合自身需求的 JSON 到 XML 轉換工具。