Routes API 計算路線時，會將您提供的中途點和設定參數做為輸入內容。接著，API 會傳回包含預設路線和一或多個替代路線的回應。
根據您要求的欄位，回應內容可能會包含不同類型的路線和其他資料：
| 如何在回覆中加入這項資訊 | 請參閱這份說明文件 |
|---|---|
| 根據車輛引擎類型，顯示最省油或最節能的路線。 | 設定環保路徑 |
| 最多三個替代路線 | 要求替代路線 |
| 整條路線、路線的每個航段，以及航段的每個步驟的折線。 | 要求路線折線 |
| 預估的通行費，考量駕駛人或車輛可用的任何通行費折扣或通行證。 | 計算通行費 |
| 根據語言代碼和度量單位 (英制或公制) 提供本地化回應。 | 要求本地化值 |
如要將導覽指示格式化為 HTML 文字字串，請將 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 新增至 extraComputations。 |
額外運算 |
如需輸入選項的完整清單，請參閱「可用的路徑選項」和「要求主體」。
您可以利用回應，為客戶提供必要資訊，協助他們根據需求選擇合適的路線。
關於欄位遮罩
呼叫方法來計算路線時，您必須指定欄位遮罩，定義要在回應中傳回哪些欄位。系統不會提供傳回欄位的預設清單。如果省略這個清單，方法會傳回錯誤。
本文件中的範例會顯示整個回應物件，但不會考量欄位遮罩。在實際工作環境中，回應只會包含您在欄位遮罩中明確指定的欄位。
詳情請參閱「選擇要傳回的資訊」。
關於顯示版權
向使用者顯示結果時，請務必加入下列版權聲明：
Powered by Google, ©YEAR Google
例如：
Powered by Google, ©2023 Google
關於路線、路段和步驟
在查看 Routes API 傳回的回應之前，請先瞭解構成路線的元件：
您的回覆可能包含下列路線元件的相關資訊：
路線：從起點路線控點開始，經過任何中繼路線控點，到達目的地路線控點的整個行程。路線包含一或多個路段。
路段：路線中從一個路標到下一個路標的路徑。每個航段都包含一或多個獨立的步驟。
路線包含從每個路線控點到下一個路線控點的路徑，每個路段都各自獨立。舉例來說，如果路線包含單一起點路標和單一目的地路標，則路線就包含單一航段。對於您在起點和目的地後新增至路線的每個額外路標 (稱為「中間路標」)，API 都會新增個別路段。
API 不會為中途路線控點新增車程。舉例來說，路線包含起點路線控點、中繼路線控點和目的地路線控點，只包含從起點到目的地的單一路段，並經過路線控點。如要進一步瞭解中繼路線控點，請參閱「定義中繼路線控點」。
步驟：路線路段中的單一指示。步驟是路線中最小的組成單位。舉例來說，步驟可以指出「在 Main Street 左轉」。
回應內容
代表 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 會嘗試找出最相關的位置，並提供相應的地點 ID。geocodingResults 陣列的每個元素都包含 placeID 欄位，其中包含地點的形式為地點 ID，以及指定地點類型的 type 欄位，例如 street_address、premise 或 airport。
geocodingResults 陣列包含三個欄位：
origin：如果指定為地址字串或 Plus Code，則為來源的 place 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) 和英制單位，您會取得 distanceMeters 的值為 49889.7，但也會取得以德文和英制單位提供該距離測量值的本地化文字，也就是「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」語言和公制單位。