Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

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

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

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

課程內容

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

建構有效的轉送要求。
使用尺寸、重量和其他特徵，指定真實車輛的資訊。
解讀回覆內容，包括路線權杖和旅遊安全標記。

必要條件

您必須建立 Google Cloud 雲端專案，並啟用 Routes API。
專案必須佈建大型車輛路線規劃。大型車輛路線規劃功能僅開放部分客戶使用，如要要求存取權，請與我們聯絡

限制

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

適用地區：大型車輛路線規劃功能適用於美國本土 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，系統會在該欄位中，為包含收費道路的路線加上註解。

其他轉送行為

將 travelMode 設為 TRUCK 時，API 會自動針對大型車輛的機動性調整路線。系統產生的路線會避開迴轉，且相較於小型道路，更偏好州際公路和高速公路。您不需要設定任何額外參數或修飾符，即可啟用這些行為。

使用 `computeRoutes` 計算單一路線

使用 computeRoutes 端點計算一個起點和一個目的地之間的卡車專屬路線。

範例 `computeRoutes` 要求

以下是典型半拖車的完整 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` 回覆範例

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

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

解讀 `computeRoutes` 回覆

向 computeRoutes 端點發出要求成功後，系統會傳回 JSON 回應物件，其中包含一或多條可能的路線。

重要回應欄位

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

檢查路線安全旗標

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

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

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

計算路線矩陣 (`computeRouteMatrix`)

使用 computeRouteMatrix 端點，有效率地比較多個起點和目的地之間的交通時間和距離。舉例來說，您可以使用這項功能，找出離新取貨地點最近的卡車。找出要使用的車輛來源後，您可以發出 computeRoutes 要求，取得建議車輛的路線詳細資料和路線權杖。

如要使用 computeRouteMatrix，請在每個 origin 物件中指定 vehicleInfo，而非在要求根層級指定。

範例 `computeRouteMatrix` 要求

{
  "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"
}

`computeRouteMatrix` 回覆範例

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

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

後續步驟

提供即時路況導航：瞭解如何在 Navigation SDK for Android 或 iOS 中使用 routeToken。
執行車隊層級最佳化：使用Route Optimization API with Large Vehicle Routing。
API 參考資料：如要查看所有可能的欄位和值完整清單，請參閱 Routes API 參考資料。