為何要遷移至 Routes API？

Routes API 可提供更佳的效能，用於計算路線、距離和行車時間，因此值得取代目前使用 Directions API 和 Distance Matrix API 的應用程式。路徑 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 個元素 (起點數量 × 目的地數量)。

加快要求回應速度

Compute Route Matrix 功能可改善下列延遲問題：

  • 在計算整個矩陣之前，接收回應的串流元素。
  • 使用欄位遮罩自訂回應詳細資料，只要求所需的資料，這也是節省成本的最佳做法。
  • 強化流量路徑計算功能，讓您在資料品質和回應時間之間取得平衡。

路由強化功能

Compute Route 功能提供下列轉送強化功能：

  • 除了距離和預估到達時間外，還會顯示通行費資訊。
  • 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 進行設定。

  • 考量即時流量的 ETA 會包含在 duration 回應資源屬性中。
  • staticDuration 回應屬性包含路線的旅行時間，不考慮交通狀況。
  • 系統不再傳回 duration_in_traffic 屬性。

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

  • 考量即時流量的 ETA 會包含在 duration_in_traffic 回應資源屬性中。

折線路線控點

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

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

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

可用的交通方式

與 Directions API 一樣，如果路線要求未指定交通方式，Routes API 會使用 DRIVE 做為預設模式。不過，如果要求指定路線的交通方式，Routes API 就不會傳回可用交通方式的陣列，做為要求的替代選項。如果您的用途仰賴這項功能，請提交問題，說明您如何使用這項功能，以便我們進行後續追蹤。

使用 XML 做為回應格式

Routes API 不會以 XML 做為回應格式。您可以在線上找到許多 JSON 到 XML 轉換器，這些轉換器應該能符合您的需求。