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，以包含下列一或多個值：