查看路徑回應

Routes API 計算路線時，會將您提供的途經點和設定參數做為輸入內容。接著，API 會傳回包含預設路線和一或多條替代路線的回應。

根據您要求的欄位，回覆內容可能包含不同類型的路線和其他資料：

如需輸入選項的完整清單，請參閱「可用路線選項」和「要求主體」。

您可以根據回覆，提供顧客所需資訊，協助他們選擇符合需求的適當路線。

關於欄位遮罩

呼叫方法計算路線時，您必須指定欄位遮罩，定義要在回應中傳回的欄位。系統不會預設傳回任何欄位。如果省略這份清單，方法會傳回錯誤。

本文範例顯示整個回應物件，未考量欄位遮罩。在實際工作環境中，回應只會包含您在欄位遮罩中明確指定的欄位。

詳情請參閱「選擇要傳回的資訊」。

關於顯示著作權

向使用者顯示結果時，請務必加入下列著作權聲明：

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 陣列

回應包含 routes 陣列，其中每個陣列元素都是 Route 類型。每個陣列元素都代表從起點到目的地的完整路線。API 一律會傳回至少一條路線，稱為預設路線。

你可以要求其他路線。如果要求環保路徑，陣列最多可包含兩個元素：預設路徑和環保路徑。或者，在要求中將 computeAlternativeRoutes 設為 true，即可在回應中加入最多三條替代路線。

陣列中的每條路線都會以 routeLabels 陣列屬性識別：

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"
      ],
     …
    }
  ]
}

瞭解 legs 陣列

回應中的每個 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) 的語言代碼和英制單位，系統會提供 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」語言和公制單位。