查看路徑回應

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 陣列，其中每個陣列元素的類型為 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"
      ],
     …
    }
  ]
}

瞭解腿部陣列

回應中的每個 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：包含地點 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」語言和公制單位。