Routes API 計算路徑時,會採用您提供的路線控點和設定參數做為輸入內容。接著,API 會傳回包含 default 路徑和一或多個替代路徑的回應。
根據您要求的欄位,回應可能會包含不同類型的路徑和其他資料:
可在回覆中加入 | 請參閱這份說明文件 |
---|---|
根據車輛的引擎類型,找出最省油或最節能的路線。 | 設定環保路徑 |
最多三條替代路線 | 要求替代路線 |
整個路線、路線中每個路段和路段中每個步驟的折線。 | 要求路線折線 |
預估過路費,已考量司機或車輛可用的任何收費價格折扣或票證。 | 計算過路費 |
依照語言代碼和測量單位 (英製或指標) 本地化的本地化回應。 | 要求本地化值 |
如要將導覽操作說明的格式設為 HTML 文字字串,請在 extraComputations 中加入 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 。 |
額外運算 |
透過回應,您可以為客戶提供必要資訊,以便為他們的需求選取適當的路徑。
關於欄位遮罩
呼叫方法計算路線時,您必須指定欄位遮罩,以定義要在回應中傳回的欄位。沒有傳回欄位的預設清單。如果省略這份清單,這些方法就會傳回錯誤。
本文件中的範例顯示完整的回應物件,而不考慮欄位遮罩。在實際工作環境中,回應只會包含您在欄位遮罩中明確指定的欄位。
詳情請參閱選擇要傳回的資訊。
關於顯示版權
向使用者顯示結果時,您必須加入以下版權聲明:
Powered by Google, ©YEAR Google
例如:
Powered by Google, ©2023 Google
關於路徑、路線和步驟
在查看 Routes API 傳回的回應之前,您應該先瞭解構成路徑的元件:
您的回應可能包含下列每個路徑元件的相關資訊:
路線:從起點路線控點到任何中繼路線控點之間的整趟行程。路徑包含一或多個「路段」。
Leg:從某條路線中到下一個路線控點的路徑。每個路段都包含一或多個獨立的步數。
路徑包含從每個路線點到下一個路線控點的獨立路段。例如,如果路徑包含單一起點路線和一個目的地路線控點,則路徑會包含一個路段。針對您在起點和目的地之後加入路徑的每一個額外路線控點 (稱為「中繼路線控點」),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
:包含地址字串或 Plus code 指定任何中繼路線點的地點 ID 的陣列。如果您使用地點 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」語言和「METRIC」單位。