為何要遷移至 Routes API？

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

Routes API 在計算路線、距離和交通時間時效能更佳，因此值得取代使用 Directions API 和 Distance Matrix 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 會預設使用「開車」模式。不過，如果要求為路線指定交通方式，Routes API 就不會傳回可用交通方式的陣列，做為要求的替代選項。如果您的用途需要這項功能，請提出問題，說明您如何使用這項功能，我們會進行後續追蹤。

XML 做為回覆格式

Routes API 不提供 XML 做為回應格式。您可以在線上找到許多 JSON 轉 XML 轉換器，應該能滿足您的需求。