Routes API 計算路線時，會將您提供的中途點和設定參數做為輸入內容。接著，API 會傳回回應，其中包含預設路線和一或多個替代路線。
根據您要求的欄位，您的回應可包含不同類型的路徑和其他資料：
| 如何在回應中加入這項資訊 | 請參閱這份說明文件 |
|---|---|
| 根據車輛引擎類型，顯示最省油或最節能的路線。 | 設定環保路徑 |
| 最多三個替代路徑 | 要求替代路線 |
| 整條路線、路線的每個航段，以及航段的每個步驟的折線。 | 要求路線折線 |
| 預估的通行費，考量駕駛人或車輛可用的任何通行費折扣或通行證。 | 計算通行費 |
| 依語言代碼和測量單位 (英製或指標) 區分的本地化回應。 | 要求本地化值 |
如要將導覽指示格式化為 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 會嘗試找出最相關的位置，並提供相應的地點 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」語言和公制單位。