為何要遷移至 Routes API？

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

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

重要改善項目

本節說明在應用程式中使用 Routes API 時，可能出現的一些強化功能。

提高要求數量上限

Routes API
  • 最多 625 個元素，除非您指定 TRAFFIC_AWARE_OPTIMAL。
  • 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 稍長，但 ETA 品質微乎其微。

延遲時間比 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 的預設模式會使用 DR。不過，如果要求確實指定路線的交通方式，Routes API 不會傳回可用的交通方式陣列做為要求的替代選項。如果您的用途需要使用這項功能，請提交問題，說明功能的使用方式，以便我們後續追蹤。

以 XML 做為回應格式

Routes API 並未提供 XML 做為回應格式。您可以在線上找到一些符合您用途的 JSON 到 XML 轉換器。