瞭解運算路徑回應

如要計算路線，Routes API 會將路線控點和設定參數清單視為輸入內容。API 就會傳回包含預設路徑和一或多個選用路徑的回應。

計算路線的要求支援多個輸入選項。舉例來說，您可以要求：

  • 根據車輛引擎類型，最省油或最節能路線的環保路徑。

  • 最多三種替代路線。

  • 整條路線的路段、每段路段的路段和每段路段的折線。

  • 預估車資費，包括駕駛或司機的任何免付費價格折扣或票證。

  • 其他選項，如需輸入選項的完整清單，請參閱要求內文。

您可以利用這個回應，為客戶提供所需資訊，選取符合需求的客戶路線指引。

關於欄位遮罩

呼叫路線時，您必須指定欄位遮罩，以定義您希望在回應中傳回的欄位。沒有傳回預設欄位的清單。如果省略這份清單，方法會傳回錯誤。

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

詳情請參閱選擇要傳回的欄位。

關於顯示版權

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

Powered by Google, ©YEAR Google

例如：

Powered by Google, ©2023 Google

關於路線、路段和步數

在查看 Routes API 傳回的回應之前，您應該先瞭解組成路徑的元件：

路線、腿部和步驟。

在此情況下：

  • 路徑：從起點路線控點到完整路線控點的完整行程。路徑包含一或多個路段。

  • 路段：從路線中的一個路線控點到路徑中下一個路線控點的路徑。每個路段包含一或多個獨立步驟。

    路線包含兩條路線中各自指向下一個路線控點的路徑。例如，如果路線包含一個單一起點路線控點和一個目的地路線控點，路線就會包含一個路段。您在起點和目的地之後，為路線加入的每個額外路線控點 (稱為「中繼路線控點」) 都會新增一個路段。

    API 不會為「直通」中繼路線控點新增路段。例如，包含起點路線控點、通過的中繼路線控點和目的地路線控點，只會從起點到目的地之間傳遞一個路段，在經過路線控點時則會傳送。如要進一步瞭解直通路線，請參閱「定義直通路線」。

  • 步驟：路線沿途的單一指示。步數是路徑中最小的組成單位。例如，一個步驟可以顯示「左轉至主要街道」。

關於回覆

代表 API 回應的 JSON 物件包含下列頂層屬性：

  • routes，Route 類型的陣列。routes 陣列包含 API 傳回的每個路線一個元素。陣列最多只能包含五個元素：預設路徑、環保路徑和最多三個替代路徑。

  • geocodingResults，GeocodingResults 類型的元素陣列。針對指定為地址字串或指定為 Plus Code 的要求，每個要求 (起點、目的地或中繼路線控點) 都會執行地點 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 陣列屬性在陣列中指出每個路徑。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"
      ],
     …
    }
  ]
}

瞭解路段陣列

回應中的每個 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 參數，API 會嘗試使用 Accept-Language 標頭中指定的偏好語言。

  • 使用要求的 languageCode 參數，明確設定支援語言清單中的路徑語言。Google 會經常更新支援的語言，因此這份清單可能未涵蓋所有情況。

  • 如果偏好語言不提供名稱，API 會使用最接近的值。

  • 偏好語言對 API 選擇傳回的結果集及其產生順序的影響較小。地理編碼器會以不同語言解讀縮寫，例如街道類型的縮寫，或是可能適用於某種語言的同義詞。舉例來說，utca 和 tér 是匈牙利的街道同義詞。

瞭解 GeocodingResults 陣列

針對在地址字串或 Plus Code 指定為要求的每個位置 (出發地、目的地或中繼路線控點)，API 會嘗試尋找具有對應地點 ID 的最相關位置。geocodingResults 陣列的每個元素都包含一個 placeID 欄位，其中含有地點 ID 和地點介面的 type 欄位，例如 street_address、premise 或 airport。

geocodingResults 陣列包含三個欄位：

  • origin：如果指定為地址字串或 Plus 代碼，地點起點的地點 ID。否則回應中會省略這個欄位。

  • destination：如果指定地址字串或 Plus 代碼，目的地的地點 ID。否則回應中會省略這個欄位。

  • intermediates：這個陣列包含任何中繼路線控點的地點 ID，指定為地址字串或 Plus 代碼。如果將中繼路線控點指定為地點 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
        }
    ]
}