Routes API 計算路線時,會採用路線控點 您提供的設定參數接著,API 會傳回回應 包含 default 路徑和一或多個替代路徑。
根據 您需要的欄位:
如何在回應中加入這項資訊 | 請參閱這份說明文件 |
---|---|
根據車輛引擎類型,顯示最省油或最節能的路線。 | 設定環保路徑 |
最多三個替代路徑 | 要求替代路線 |
整個路線、路線中每個路段及每個步驟的折線 | 要求路線折線 |
預估通行費,將任何過路費折扣納入考量 或是提供給駕駛人或車輛的票證 | 計算過路費 |
依語言代碼和測量單位 (英製或 指標)。 | 要求本地化值 |
如要將導覽說明的格式設為 HTML 文字字串,請在下列元素中加入 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS :
extraComputations 。 |
額外運算 |
如需輸入選項的完整清單,請參閱「可用的路徑選項」和「要求主體」。
您可以利用回應,為客戶提供必要資訊,協助他們根據需求選擇合適的路線。
關於欄位遮罩
呼叫方法來計算路線時,您必須指定欄位遮罩,定義要在回應中傳回哪些欄位。系統不會提供傳回欄位的預設清單。如果省略此清單,則方法會傳回 錯誤。
本文件中的範例會顯示整個回應物件,但不會考量欄位遮罩。在正式環境中,回應會 只包含您在欄位遮罩中明確指定的欄位。
詳情請參閱「選擇要傳回的資訊」。
關於顯示著作權
向使用者顯示結果時,您必須附上以下著作權聲明:
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 查詢這個陣列的每個元素都包含與地點相對應的 Place 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 會嘗試找出最相關且擁有對應地點的位置
編號。該元件的每個元素
geocodingResults
敬上
陣列包含 placeID
欄位
包含地點做為地點 ID,以及指定地點的 type
欄位
類型,例如 street_address
、premise
或 airport
。
geocodingResults
陣列包含三個欄位:
origin
:如果指定為地址字串或 Plus code, 起點的地點 ID。否則,這個欄位會從回應中省略。destination
:如果是地址字串或 Plus code, 目的地的地點 ID。否則,這個欄位會省略 回應。intermediates
:包含任何中繼位置 ID 的陣列 路線控點,指定為地址字串或 Plus Code。如果指定 由地點 ID 或緯度 回應中會省略經度座標。使用 以回應intermediateWaypointRequestIndex
屬性來判斷 請求中的中繼路線控點與 回應。
"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
方法會推測位置和距離 與原始路線控點之間的單位數如果是美國的轉送要求 可推斷en-US
語言和IMPERIAL
單位。ComputeRouteMatrix
方法預設為「en-US」語言和公制單位。