生成大型車輛路線和預計抵達時間

本指南適用對象：如果您是開發人員，且要使用卡車或其他大型車輛建構行程規劃和執行服務，請參閱本指南。相關用途包括計算行程時間和距離、計算預計抵達時間，或是產生導航應用程式會使用的路線。

本指南涵蓋內容：本指南說明如何搭配大型車輛路線規劃功能使用 Routes API，要求路線、行車距離、預計行車時間和預計抵達時間，並將大型車輛的特定屬性納入考量，例如商用卡車或客運巴士。

如要瞭解如何使用 Route Optimization API，為大型車輛執行機群層級的計算作業，請參閱 Route Optimization 貨車路線規劃說明文件。

課程內容

您將瞭解如何執行下列操作：

  • 建構有效的轉送要求。
  • 使用尺寸、重量和其他特徵，為實際車輛指定車輛設定檔。
  • 解讀回應，包括路徑權杖和旅遊安全標記。

必要條件

  1. 您必須建立 Google Cloud 雲端專案，並啟用 Routes API。
  2. 專案必須佈建大型車輛路線規劃。請與 Google 代表聯絡，完成這個步驟。

限制

開始之前，請務必瞭解下列限制和規定。

  • 適用地區：大型車輛路線規劃功能僅適用於美國本土 48 州。
  • 大型車輛路線規劃功能目前為預覽階段。駕駛人不得僅依據這個 API 傳回的路線，確保行車安全或合法。系統無法保證路線適合車輛，如果按照路線行駛，駕駛人可能會遇到低矮橋梁或禁止大型車輛通行的道路等危險情況。
  • 盡力而為路徑。在某些情況下，API 可能無法找到完全符合旅遊限制的路線。而是傳回「盡力處理」的路線，這類路線仍可能經過管制區域。Routes API 回應會在 routeRestrictionsPartiallyIgnored 欄位中清楚標示這些路線。在這種情況下，請仔細規劃路線，最好使用其他來源資料。請勿使用標記的路線做為規劃或導航的單一事實來源。
  • 不支援的功能：我們正努力為這項服務提供更多功能，但大型車輛路線規劃目前不支援下列功能：
    • 卡車通行費
    • 速限
    • 放射性有害物質的路線
  • 用量限制：所有要求均須遵守標準的每秒查詢次數 (QPS) 限制。

建立卡車路線要求

如要取得卡車路線，請將 HTTPS 要求傳送至 Routes API 端點，並附上描述車輛的特定參數。

端點

您可以使用兩個端點進行貨車路線規劃：

  • computeRoutes：計算一個出發地和一個目的地之間的單一路線。
  • computeRouteMatrix：計算起點和目的地矩陣的距離和時間，但不傳回路線折線。

重要要求參數

要求內容必須包含下列項目：

  • travelMode：將這個值設為 TRUCK。
  • routingPreference：將這個值設為 TRAFFIC_AWARE_OPTIMAL。
  • routeModifiers：這個物件包含 vehicleInfo 物件，您可以在其中定義車輛的屬性。下文將詳細說明 vehicleInfo 物件。

指定車輛設定檔

如要傳送要求，您必須提供要求主體，其中包含描述車輛的 vehicleInfo 物件。這項資訊可視為與實體車輛相符的規格。這項服務需要這些詳細資料，才能根據車輛屬性傳回考量道路限制的路線。

車輛測量

請按照欄位名稱指示，以公斤為單位提供車輛重量，並以公釐為單位提供車輛尺寸。舉例來說，總高度應以毫米 (totalHeightMm) 為單位。由於卡車尺寸通常以英尺或公尺表示，因此可能需要轉換單位。

從英制轉換為公制

從英制單位轉換時，請務必考量車輛的具體尺寸，以及道路和地下道的標準尺寸限制。這對分數值來說尤其重要。視實際車輛大小而定，將分數值無條件進位可能會導致車輛的路線過於受限。

例如：

  • 寬度：許多美國拖車的寬度為 8 呎 6 吋，換算為 2,590.8 公釐。如果四捨五入為 2,591 公釐，表示車輛寬度超過 8 呎 6 吋，在美國道路上屬於超寬車輛。這樣一來，系統就會根據與預期不同的限制條件計算路徑。
  • 高度：如果路線會經過 11 英尺高的橋梁下方，就不適合 13.5 英尺高的典型曳引車。不過，10 呎左右的小型廂型車應該可以通過地下道。因此，請務必準確指定車輛屬性。

圖表：卡車尺寸與地下通道尺寸的比較

以下程式碼片段顯示範例 vehicleInfo 物件：

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo 個物件欄位

下表列出所有可透過要求傳送的車輛和載重定義。

欄位 說明 附註 / 值
totalHeightMm 車輛高度上限。 以公釐為單位，並無條件捨去小數。 如要進一步瞭解四捨五入，請參閱「英制單位換算為公制單位」。
totalWidthMm 車輛的最大寬度。 以公釐為單位，並無條件捨去小數。
totalLengthMm 車輛和所有拖車的總長度。 以公釐為單位，並無條件捨去小數。
totalWeightKg 車輛總重 (包括拖車和負載)。 以公斤為單位，並無條件捨去小數。
totalAxleCount 車輛和任何拖車的車軸總數。 完全比對。
trailerInfo (選填) 物件陣列，每個預告片各有一個物件。 如果車輛沒有拖車 (例如廂型貨車)，請省略這項資訊。
hazardousGoodsTypes (選填) 指定船上任何危險物質的陣列。 EXPLOSIVES、GASES、FLAMMABLE、COMBUSTIBLE、ORGANIC、POISON、CORROSIVE、ASPIRATION_HAZARD、ENVIRONMENTAL_HAZARD、OTHER

使用欄位遮罩

為獲得最佳結果，請在要求中加入 X-Goog-FieldMask 標頭，明確指定您希望在回應中取得的欄位。欄位遮罩可縮短延遲時間，確保您收到重要的建議欄位。至少一律要在欄位遮罩中加入 routes.travelAdvisory.routeRestrictionsPartiallyIgnored，因為這會指出路由是否有一或多項適用於車輛的限制。

如要進一步瞭解 Routes API 的 FieldMasks，請參閱這篇文章。

收費路段

如要優先選擇免付費路線，請在要求的 routeModifiers 屬性中指定 avoidTolls。如要進一步瞭解路徑修飾符，請參閱「指定要避開的路徑特徵」。

指定 avoidTolls 並不保證回應中會提供免付費路線。在某些情況下，您必須行經收費路段，才能往返起點和目的地。如果在 Routes API 要求的 fieldmask 中加入 routes.warnings，系統會在該欄位中，為包含收費道路的路線加上註解。

完整的 curl 要求範例

以下是典型半拖車的完整 curl 要求。這個範例包含端點、標頭和要求主體。

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

解讀 computeRoutes 回應

如果對 Routes API 的要求成功，系統會傳回 JSON 回應物件，其中包含一或多條可能的路線。

重要回應欄位

  • 編碼路徑幾何圖形：routes.polyline。可用於在地圖上算繪路線。
  • 預估行程時間：routes.duration (以秒為單位)。大型車輛路線的行程時間會使用新模型，該模型是根據路網中實際卡車的觀測行車速度訓練而成。您也可以將預估行程時間加到預計出發時間，藉此計算預計到達時間。
  • 路線總距離：routes.distanceMeters (以公尺為單位)。
  • 路線權杖：routes.routeToken。這是代表確切計算路徑的不透明權杖。您會將這個權杖傳遞至 Navigation SDK，確保系統向駕駛人顯示相同的卡車專屬路線。如要進一步瞭解如何操作，請參閱「提供逐步導航」指南。

檢查路線安全旗標

收到回覆後，請先檢查路線安全旗標。如果提供的路線包含一或多項限制，導致車輛不適合行駛，您會發現 travelAdvisory.routeRestrictionsPartiallyIgnored 欄位設為 true。

這個欄位會做為標記，回答「這條路由是否標示為有潛在問題？」這個問題。

  • false(或從回應中省略)：路線未標示。系統找到的路線完全符合您在要求中提供的參數。
  • true：路線已標記。系統找不到完全符合規定的路線，因此傳回「盡力而為」的路線，但這條路線可能不安全或不合法。請務必謹慎使用這條路線。

範例：computeRoutes 回應

這是上述要求的回應範例。請注意，在 travelAdvisory 物件中，不包含 routeRestrictionsPartiallyIgnored 旗標。這表示路線未標示，且系統認為完全符合車輛設定檔。

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

取得卡車路線矩陣

如要一次計算多個潛在行程的交通時間，請使用 computeRouteMatrix 端點進行高階規劃，有效比較多個出發地和目的地之間的交通時間和距離。舉例來說，您可能會使用這項功能，找出離新上車地點最近的卡車。找出要使用的車輛來源後，即可發出 computeRoutes 要求，取得建議車輛的路線詳細資料和路線權杖。

如要使用 computeRouteMatrix，請在每個來源物件中指定 vehicleInfo。

要求範例

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

回應範例

回應是陣列，每個物件都包含一組起點和目的地的所需時間和 distanceMeters。

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

後續步驟