Google 地圖平台目前支援 Directions API 和 Distance Matrix API。這個新版 Routes API 包含現有 Directions API 和 Distance Matrix API 的新一代效能最佳化版本:
- 運算路徑:運用全方位的全域轉送資料和即時流量計算不同位置之間的路線。
- 「Compute Route Matrix」(運算路徑矩陣):計算起點/目的地清單的距離和所需時間。
Routes API 提供許多新功能,包括:
TWO_WHEELER
轉送- 過路費計算
- 交通意識折線
- 折線品質控管機制
- 品質延遲控管機制
- 結果串流 (僅限使用 gRPC 的 Compute Route Matrix)
- gRPC 支援
如要進一步瞭解 Routes API,請參閱 Routes API。
本指南說明如何遷移使用 Directions API 和 Distance Matrix API 的現有應用程式,以使用新的 Routes API。
新 Routes API 的功能異動
一般而言,Routes API 會對 Directions API 和 Distance Matrix API 進行下列變更:
將 Compute Route 和 Compute Route Matrix 合併在名為 Routes API 的單一服務中
您必須在 API 主控台中啟用 Routes API,才能使用 Compute Routes 和 Compute Route Matrix。您目前在 API 控制台中啟用了 Directions API 和 Distance Matrix API 做為個別服務。
如需詳細資訊,請參閱在 Google API 控制台中設定一文。
New Routes API 使用 HTTP POST 要求
在新的 Routes API 中,您會在要求主體或標頭中傳送參數做為 HTTP POST 要求的一部分。相較之下,使用 Directions API 和 Distance Matrix API 時,您會使用 HTTP GET 要求來傳遞網址參數。
如需範例,請參閱:
需要欄位遮蓋
當您呼叫新的 Routes API 以計算路徑或計算路徑矩陣時,您必須指定要在回應中傳回哪些欄位。系統並未傳回傳回欄位的預設清單。如果省略這個清單,這個方法會傳回錯誤。
建立回應欄位遮罩以指定欄位清單。然後,您可以使用網址參數
$fields
或fields
,或使用 HTTP/gRPC 標頭X-Goog-FieldMask
,將回應欄位遮罩傳遞至每個方法。欄位遮罩是一個不錯的設計做法,可確保您不會要求不必要的資料,以避免不必要的處理時間和帳單費用。
詳情請參閱選擇要傳回的欄位一文。
Compute 路徑矩陣的新要求限制
Distance Matrix API 會強制執行以下要求限制:
- 每個要求最多 25 個起點或 25 個目的地。
- 每個伺服器端要求最多 100 個元素 (起點數 × 目的地數)。
Compute 路徑矩陣會強制執行以下要求限制:
元素數目不得超過 625。
如果指定
TRAFFIC_AWARE_OPTIMAL
,則元素數量不得超過 100。如要進一步瞭解TRAFFIC_AWARE_OPTIMAL
,請參閱設定品質和延遲時間一文。可使用地點 ID 可指定的路線控點 (出發地 + 目的地) 數量上限為 50。
設定品質與延遲時間的新選項
新的 Routes API 支援三種轉送偏好設定,可用來明確設定路徑品質與回應延遲時間:
TRAFFIC_UNAWARE
(預設) - 使用平均獨立時間流量資料 (而非即時路況資料) 來計算路徑,藉此縮短回應延遲時間。這項設定相當於在 Directions API 和 Distance Matrix API 中使用流量時。TRAFFIC_AWARE
- 效能最佳化的即時流量品質以縮短延遲時間。這個路徑是 Routes API 的新設定,在 Directions API 和 Distance Matrix API 中無對等設定。與
TRAFFIC_AWARE_OPTIMAL
相比,某些最佳化作業會大幅縮短延遲時間。TRAFFIC_AWARE_OPTIMAL
- 高品質且完整的車流量資料,且不用套用大部分的效能最佳化。這項設定會產生最高延遲時間,等同於 Directions API 和 Distance Matrix API 中的departure_time
設定。TRAFFIC_AWARE_OPTIMAL
轉送偏好設定相當於 maps.google.com 和 Google 地圖行動應用程式使用的模式。
在 Directions API 和 Distance Matrix API 中,我們只會提供對等的
TRAFFIC_AWARE_OPTIMAL
和TRAFFIC_UNAWARE
選項。系統會根據您是否設定departure_time
,以隱含方式設定這些選項。下表比較了 current Directions API 和 Distance Matrix API 選項以及新的 Routes API 選項:
模式 目前的專案 Routes API Notes 無即時路況 未設定「 departure_time
」屬性TRAFFIC_UNAWARE
三種模式中最快的延遲時間。 已套用即時路況 無對應報告 TRAFFIC_AWARE
由 Routes API 新增模式。這個延遲時間的延遲時間略高於
TRAFFIC_UNAWARE
,且 ETA 費用也略低。延遲時間比
TRAFFIC_AWARE_OPTIMAL
短很多。已套用高品質且完整的即時車流量資料 已設定 departure_time
項屬性TRAFFIC_AWARE_OPTIMAL
等同於 maps.google.com 和 Google 地圖行動應用程式使用的模式。
如果是運算路徑矩陣,要求中的元素數量 (起點數 × 目的地數) 不得超過 100 個。
Routes API 也會修改
duration
回應屬性的設定方式,並修改「目前」回應中傳回的屬性,如下表所示:旅遊預計到達時間 目前的專案 Routes API 路況不受干擾且與時俱進的預計到達時間。 對應於要求中未設定的
departure_time
。duration
回應屬性中包含的延展型文字廣告。- 系統不會傳回
duration_in_traffic
回應屬性。
對應
TRAFFIC_UNAWARE
。duration
回應屬性中包含的延展型文字廣告。duration
和staticDuration
回應屬性中都含有相同的值。
將即時流量納入考量的延展型文字廣告。 對應要求中的
departure_time
設定。- 將即時流量納入考量的延展型文字廣告會包含在
duration_in_traffic
回應屬性中。
對應於
TRAFFIC_AWARE
或TRAFFIC_AWARE_OPTIMAL
。- 將即時流量納入考量的延展型文字廣告會包含在
duration
回應屬性中。 staticDuration
回應屬性包含通過路線時長,且不將路況納入考量。- 系統已不再支援
duration_in_traffic
屬性。
詳情請參閱設定品質與延遲時間。
Routes API 不支援現有功能
Routes API 將不支援以下功能:
XML 做為回應格式。僅支援 JSON 和 gRPC。
反向地址定位
您現在可以使用 Reverse Geocoding API 建立適用於此用途的函式,並提供更優質的品質結果。
遷移至 Routes API
我們在 Routes API 中進行了多項變更。大多數變更都與舊版 API 回溯相容,但下方列出幾項破壞性變更,需要您將應用程式遷移至 Routes API 時才能採用。
更新 REST API 端點
如果您使用 Directions API,請更新程式碼來使用新的 Routes API 端點:
Directions API | https://maps.googleapis.com/maps/api/directions/outputFormat?parameters |
Routes API | https://routes.googleapis.com/directions/v2:computeRoutes |
如果您使用 Distance Matrix API,請更新程式碼來使用新的 Routes API 端點:
Distance Matrix API | https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters |
Routes API | https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix |
轉換網址參數以使用 HTTP 要求主體
您可以利用 Directions API 和 Distance Matrix API 將設定屬性做為網址參數傳遞至 HTTP GET 要求。例如,針對 Directions API:
https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
透過 Routes API,您可以在要求主體或標頭中傳送參數做為 HTTP POST 要求的一部分。如需範例,請參閱:
將目前的參數轉換為 Routes API 參數
下表列出目前 Directions API 和 Distance Matrix API 中已重新命名或修改的 參數,或 預覽 版本 不支援的 參數。使用這些參數時,請更新程式碼。
目前的參數 | Routes API 參數 | Notes |
---|---|---|
destination |
destination |
預先發布版不支援地址和 Plus Code。 |
origin |
origin |
預先發布版不支援地址和 Plus Code。 |
alternatives |
computeAlternativeRoutes |
|
arrival_time |
預覽功能不支援「TRANSIT 」模式,因此無法使用此功能。 |
|
avoid |
routeModifiers |
|
copyrights |
不適用於預先發布版。 | |
departure_time |
departureTime |
|
distance |
distanceMeters |
距離僅適用於公尺。 |
duration_in_traffic |
|
已在 Routes API 中移除,請使用 duration 。詳情請參閱上方的新版 Routes API 的功能異動。 |
language |
languageCode |
|
mode |
travelMode |
新增對 「 |
region |
因為不支援地址,所以無法使用預覽功能。 | |
status |
不適用於預先發布版。針對 HTTP 回應錯誤,請使用 HTTP 回應代碼。詳情請參閱處理要求錯誤。 | |
traffic_model |
不適用於預先發布版。 | |
transit_mode |
預覽功能不支援「TRANSIT 」模式,因此無法使用此功能。 |
|
transit_routing_preference |
預覽功能不支援「TRANSIT 」模式,因此無法使用此功能。 |
|
units |
預先發布版不支援距離矩陣。 | |
waypoints |
intermediates |
預先發布版不支援地址和折線。 |
路線控點為 optimize=true |
不適用於預先發布版。 |