Google 地圖平台目前支援 Directions API 和 Distance Matrix API。這個版本的 Routes API 包含現有 Directions API 和 Distance Matrix API 的新一代效能最佳化版本:
- 運算路徑:運用全方位的全域轉送資料和即時流量計算不同位置之間的路線。
- 「Compute Route Matrix」(運算路徑矩陣):計算起點/目的地清單的距離和所需時間。
Routes API 提供許多新功能,包括:
- 機車路線
- 過路費計算
- 交通意識折線
- 折線品質控管機制
- 品質延遲控管機制
- 環保路徑
- 結果串流 (僅限使用 gRPC 的 Compute Route Matrix)
- gRPC 支援
如要進一步瞭解 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
回應屬性的設定方式,並修改目前 Directions API 和 Distance Matrix API 回應中傳回的屬性,如下表所示:旅遊預計到達時間 目前的專案 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 |
---|---|---|
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 |
regionCode |
|
status |
無法使用。針對 HTTP 回應錯誤,請使用 HTTP 回應代碼。詳情請參閱處理要求錯誤。 | |
traffic_model |
不適用。 | |
transit_mode |
無法使用「TRANSIT 」模式,因此無法使用。 |
|
transit_routing_preference |
無法使用「TRANSIT 」模式,因此無法使用。 |
|
units |
不支援路徑矩陣。 | |
waypoints |
intermediates |
|
路線控點為 optimize=true |
不適用。 |
從預覽版本遷移
Routes API 已於 2022 年 9 月發布為公開預先發布版 (正式發布前)。正式發布前產品受到《Google 地圖平台服務專屬條款》的規範。 詳情請參閱發布階段說明。
本節說明如何將應用程式從預覽版本遷移至 Google Analytics (分析) 版本。
Analytics (分析) 版本新增功能
GA 版本新增以下新功能,不包含在預先發布版中:
除了地點 ID 和緯度/經度座標,您現在可以使用以下方式在 Google Analytics (分析) 版本中指定位置:
地址字串 (「Chicago, IL」或「Darwin, NT, Australia」)
地址字串通常是使用者輸入地址的方式。不過,{product_name} 必須先在內部為地址字串進行地理編碼,才能將其轉換為經緯度座標,才能計算路徑。
此外,我們也新增了
regionCode
要求參數,可讓您指定傳回特定地理區域的地理編碼結果。-
Plus Codes 就像是沒有實際地址的使用者或地點的街道地址。Plus Codes 並非使用包含街道名稱和數字的地址,而是以經緯度呈現,並以數字和字母顯示。
運算路徑回應現在包含
geocodingResults
陣列。針對要求中所指定地址字串或加號代碼的每個位置 (出發地、目的地或中繼路線控點),API 都會執行地點 ID 查詢。這個陣列的每一個元素都含有地點對應的地點 ID,以及有關該位置的其他中繼資料。要求中以地點 ID 或緯度/長期座標表示的位置將遭到忽略。
現有預覽功能異動
現在,您必須在要求中加入新陣列 extraComputations
欄位,在 Google Analytics (分析) 中明確啟用以下功能:
在預先發布版中,您使用欄位遮罩指定要在回應中傳回這些功能的相關資訊。現在您必須同時完成以下兩個動作:
- 設定新的
extraComputations
陣列要求參數即可啟用這些功能。 - 設定欄位遮罩,以指定在回應中傳回資訊。
重要須知
除非設定 extraComputations
明確啟用,否則 computeRouteMatrix 回應中將不再包含以下欄位:
travelAdvisory.tollInfo
(收費路段)
除非設定 extraComputations
以明確啟用,否則computeRoutes 回應中將不再包含以下欄位:
routes.legs.travelAdvisory.tollInfo
(收費資訊)routes.travelAdvisory.tollInfo
(收費資訊)routes.travelAdvisory.fuelConsumptionMicroliters
(油耗)routes.travelAdvisory.speedReadingIntervals
(折線上的流量)routes.legs.travelAdvisory.speedReadingIntervals
(折線上的流量)
我需要做些什麼?
要接收折線的收費資訊、油耗或路況的回應欄位,您必須設定新的要求陣列欄位 extraComputations
,以包含下列一或多個值: