查看路徑回應

歐洲經濟區 (EEA) 開發人員

Routes API 計算路線時，會將您提供的路線控點和設定參數做為輸入內容。API 隨即會傳回回應，其中包含「預設」路線和一或多條替代路線。

回應可包含不同類型的路線和其他資料，具體取決於您要求的欄位：

如要在回覆中加入這項資訊 請參閱這份說明文件
根據車輛引擎類型，找出最省油或最高效節能的路線。 設定環保路徑
最多三條替代路線 要求替代路線
整條路線、路線各路段和路段各步驟的折線。 要求路線折線
預估過路費，考量駕駛人或車輛可享有的過路費折扣或通行證。 計算過路費
依語言代碼和測量單位 (英制或公制) 提供的本地化回應。 要求本地化值
如要將導航指示格式化為 HTML 文字字串，請將 HTML_FORMATTED_NAVIGATION_INSTRUCTIONS 新增至 extraComputations。 額外運算

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

您可以根據回應，向客戶提供必要資訊，協助他們根據需求選擇合適的路線。

關於欄位遮罩

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

本文中的範例會顯示整個回應物件，不考慮欄位遮罩。在正式環境中，回應只會包含您在欄位遮罩中明確指定的欄位。

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

關於顯示著作權

向使用者顯示結果時，必須附上以下著作權聲明：

Powered by Google, ©YEAR Google

例如：

Powered by Google, ©2023 Google

關於路線、路段和步驟

查看 Routes API 傳回的回應前，請先瞭解路線的組成要素：

路線、路段和步驟。

回覆可能包含下列各個路線元件的資訊：

  • 路線：從起點路線控點出發，經過任何中途路線控點，直到目的地路線控點的整趟行程。路線由一或多個路段組成。

  • 路段：路線中從一個路線控點到下一個路線控點的路徑。每個航段包含一或多個不連續的步驟。

    路線包含不同的路段，代表從每個路線控點到下一個控點的路徑。舉例來說，如果路線包含單一起點路線控點和單一目的地路線控點，則路線包含單一路段。在起點和目的地之間，每新增一個路線控點 (稱為「中繼路線控點」)，API 就會新增一個路段。

    API 不會為「pass-through」中繼路線控點新增路段。舉例來說，如果路線包含起點路線控點、中途經過的路線控點和目的地路線控點，則只有一個從起點到目的地的路段，且會經過路線控點。如要進一步瞭解穿越路線控點，請參閱「定義穿越路線控點」。

  • 步驟：路線中某段路程的單一指示。步驟是路線中最小的組成單位。例如，步驟可以指示「在中山路左轉」。

回應內容

代表 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 表示替代路線。

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) 的語言代碼和英制單位，則會取得 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 單位。