Routes API 計算路徑時,會採用您提供的路線控點和設定參數做為輸入內容。接著,API 會傳回回應,其中包含 default 路徑和一或多個替代路徑。
根據您要求的欄位,您的回應可包含不同類型的路徑和其他資料:
如何在回應中加入這項資訊 | 請參閱這份說明文件 |
---|---|
根據車輛的引擎類型,最省油或最節能的路線。 | 設定環保路徑 |
最多三個替代路徑 | 要求替代路線 |
整個路線、路線中每個路段及路段各折線的折線。 | 要求路線折線 |
預估過路費,包含駕駛人或車輛可用的任何過路價格折扣或票證。 | 計算過路費 |
依語言代碼和測量單位 (英製或指標) 區分的本地化回應。 | 要求本地化值 |
如要將導覽說明的格式設為 HTML 文字字串,請在 extraComputations 中加入 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 。 |
額外運算 |
透過該回應,您可以為客戶提供必要的資訊,以便依據他們的需求選擇合適的路徑。
關於欄位遮罩
呼叫方法來計算路徑時,您必須指定欄位遮罩,以定義要在回應中傳回的欄位。沒有任何傳回欄位的預設清單。如果省略這份清單,方法會傳回錯誤。
本文件中的範例顯示的是整個回應物件,但不會將欄位遮罩納入考量。在實際工作環境中,回應只會包含您在欄位遮罩中明確指定的欄位。
詳情請參閱選擇要傳回的資訊。
關於顯示著作權
向使用者顯示結果時,您必須附上以下著作權聲明:
Powered by Google, ©YEAR Google
例如:
Powered by Google, ©2023 Google
關於路線、路段和步驟
在查看 Routes API 傳回的回應之前,建議您先瞭解構成路徑的元件:
您的回應可能包含每個路線元件的相關資訊:
路線:從起點路線控點到任何中繼路線控點到目的地路線控點的整趟行程。路徑由一或多個「路段」組成。
圖例:路線中一個路線控點到路線中下一個路線控點的路徑。每個航段包含一或多個獨立的步數。
路線包含從每個路線控點到下一個路線的獨立路段。例如,如果路線包含一個起點路線控點和單一目的地路線控點,則路線會包含單一路段。針對每個您在路徑起點和目的地 (稱為「中繼路線控點」) 後新增到路徑的每一個其他路線點,API 都會新增一個路段。
API 不會為直通中繼路點新增航點。例如,包含起點路線點、直通中繼路線控點和目的地路線控點的路線,只包含從起點到目的地的一個路段,同時通過路線控點。如要進一步瞭解直通路線控點,請參閱「定義直通路線控點」。
步驟:路線路段上的單一指示,步驟是路徑中最小的組成單位。例如,步驟可能表示「在主要街道左轉」。
回覆內容
代表 API 回應的 JSON 物件包含下列頂層屬性:
routes
,Route 類型的元素陣列。routes
陣列包含 API 傳回的每條路線的一個元素。陣列最多可包含五個元素:預設路徑、環保路徑和最多三個替代路徑。geocodingResults
,GeocodingResults 類型的元素陣列。只要是您指定為地址字串或 Plus Code 都是在要求中的地點 (起點、目的地或中繼路線點),API 會執行地點 ID 查詢。這個陣列的每個元素都包含對應位置的地點 ID。但不納入要求中以地點 ID 或經緯度座標指定的位置。如果您已使用地點 ID 或經緯度座標指定所有地點,系統就不會提供這個陣列。fallbackInfo
,類型為 FallbackInfo。如果 API 無法從所有輸入屬性計算路徑,可能會改回使用其他運算方式。使用備用模式時,這個欄位會包含備用回應的詳細資訊。否則,系統會取消設定這個欄位。
回應會採用以下形式:
{ // The routes array. "routes": [ { object (Route) } ], // The place ID lookup results. "geocodingResults": [ { object (GeocodedWaypoint) } ], // The fallback property. "fallbackInfo": { object (FallbackInfo) } }
解密路徑陣列
回應會包含 routes
陣列,其中每個陣列元素都是 Route 類型。每個陣列元素都代表從起點到目的地的整條路線。API 一律會傳回至少一個路徑,稱為預設路徑。
您可以要求其他路徑。如果您要求環保路徑,則陣列可以包含兩個元素:預設路徑和環保路徑。您也可以在要求中將 computeAlternativeRoutes
設為 true
,在回應中加入最多三個替代路徑。
陣列中的每條路線都會以 routeLabels
陣列屬性識別:
值 | 說明 |
---|---|
DEFAULT_ROUTE |
識別預設路徑。 |
FUEL_EFFICIENT |
用於識別環保路徑。 |
DEFAULT_ROUTE_ALTERNATE |
I 用於指定替代路線。 |
legs
陣列包含路線中每個路段的定義。其餘屬性 (例如 distanceMeters
、duration
和 polyline,
) 則含有整個路線的相關資訊:
{ "routeLabels": [ enum (RouteLabel) ], "legs": [ { object (RouteLeg) } ], "distanceMeters": integer, "duration": string, "routeLabels": [string], "staticDuration": string, "polyline": { object (Polyline) }, "description": string, "warnings": [ string ], "viewport": { object (Viewport) }, "travelAdvisory": { object (RouteTravelAdvisory) } "routeToken": string }
受目前的行車條件和其他因素影響,預設路線和環保路徑可以相同。在此情況下,routeLabels
陣列包含 DEFAULT_ROUTE
和 FUEL_EFFICIENT
這兩個標籤。
{ "routes": [ { "routeLabels": [ "DEFAULT_ROUTE", "FUEL_EFFICIENT" ], … } ] }
瞭解腿部陣列
回應中的每個 route
都含有 legs
陣列,其中每個 legs
陣列元素都是 RouteLeg 類型。陣列中的各個路段分別定義整條路線中從一個路線控點到下一個路線控點的路徑。路線至少要有一個路段。
legs
屬性包含 steps
陣列中路段上每個步驟的定義。其餘屬性 (例如 distanceMeters
、duration
和 polyline
) 則包含路段的相關資訊。
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "steps": [ { object (RouteLegStep) } ], "travelAdvisory": { object (RouteLegTravelAdvisory) } }
瞭解步數陣列
回應中的每個路段都包含 steps
陣列,其中每個 steps
陣列元素都是 RouteLegStep 類型。每個步驟都會對應到桌腳上的單一指示。一段一律包含至少一個步驟。
steps
陣列中的每個元素都包含 navigationInstruction
屬性,類型為 NavigationInstruction,其中包含步驟指示。例如:
"navigationInstruction": { "maneuver": "TURN_LEFT", "instructions": "Turn left toward Frontage Rd" }
instructions
可能包含步驟的其他資訊。舉例來說:
"navigationInstruction": { "maneuver": "TURN_SLIGHT_LEFT", "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days" }
步驟中的其餘屬性會說明步驟的相關資訊,例如 distanceMeters
、duration
和 polyline
:
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "navigationInstruction": { object (NavigationInstruction) } }
指定步驟操作說明的語言
API 會以當地語言傳迴路線資訊,並視需要將音譯為使用者可理解的指令碼,同時觀察偏好語言。系統傳回地址元件時,一律會以相同語言傳回。
使用要求的
languageCode
參數,明確設定支援語言清單中的路徑語言。Google 經常更新支援的語言,因此這份清單可能不完整。如果名稱沒有指定語言可用,API 會使用最相符的結果。
指定語言可能會影響 API 選擇傳回的結果組合及傳回的順序。地理編碼器會視語言以不同方式解讀縮寫,例如街道類型的縮寫,或是可能在某種語言中有效的同義詞。以匈牙利文為例,「utca」和「tér」是街道的同義詞。
瞭解 geocodingResults 陣列
對於要求指定為地址字串或 Plus Code 的每個地點 (起點、目的地或中繼路線點),API 會嘗試找出最相關且有對應地點 ID 的地點。geocodingResults
陣列的每個元素都包含 placeID
欄位,其中包含地點做為地點 ID,以及用於指定地點類型的 type
欄位,例如 street_address
、premise
或 airport
。
geocodingResults
陣列包含三個欄位:
origin
:如果指定為地址字串或 Plus Code,則為起點的地點 ID。否則,回應會省略此欄位。destination
:如果指定為地址字串或 Plus Code,則為目的地的地點 ID。否則,回應會省略此欄位。intermediates
:包含地點 ID 的陣列,其中任何以地址字串或 Plus Code 指定的中繼路線控點。如果您使用地點 ID 或經緯度座標指定中繼路線控點,回應中會省略這項資訊。使用回應中的intermediateWaypointRequestIndex
屬性,判斷要求中的哪個中繼路線控點與回應中的地點 ID 對應。
"geocodingResults": { "origin": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "destination": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "intermediates": [ { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string }, { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string } ] }
瞭解本地化回應值
本地化回應值是額外的回應欄位,可為傳回的參數值提供本地化文字。針對行程所需時間、距離和單位系統 (公制) 提供本地化文字。您可以使用欄位遮罩要求本地化值,並指定語言和單位系統,或使用 API 推測的值。詳情請參閱 LocalizedValues。
舉例來說,如果您為德文 (de) 和英制單位指定語言代碼,會取得 49889.7 的 distanceMeters
值,另外也會取得以德文和英制單位表示距離的本地化文字,例如「31 Meile」。
以下是本地化值的內容示例:
{ "localized_values": { "distance": { "text": "31,0 Meile/n" }, "duration": { "text": 38 Minuten}. "static_duration": { "text": 36 Minuten}. } }
如果未指定語言或單位系統,API 會推斷語言和單位,如下所示:
ComputeRoutes
方法會從起點路線控點推斷位置和距離單位。因此,針對美國的轉送要求,API 會推論en-US
語言和IMPERIAL
單位。ComputeRouteMatrix
方法預設為「en-US」語言和指標單位。