歡迎參加 12 月在舊金山舉辦的 Google Maps Platform 開發人員社群日！立即報名參加。

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

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

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

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

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

課程內容

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

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

必要條件

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

限制

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

適用地區：大型車輛路線規劃功能適用於美國本土 48 州 (正式發布) 和日本 (實驗功能)。不適用於阿拉斯加、夏威夷或美國領地。
駕駛建議和安全。駕駛人不得僅依賴這個 API 傳回的路線，來確保安全或合法。路線不一定適合車輛行駛，駕駛人可能會遇到危險，例如低矮橋梁或禁止大型車輛通行的道路。
盡力路由。在某些情況下，API 無法找到完全符合行車限制的路線。而是會傳回「盡可能」避開限制區域的路線。Routes API 回應會在 routeRestrictionsPartiallyIgnored 欄位中清楚標示這些路線。在這種情況下，請仔細規劃路線，最好使用其他來源資料。請勿將標記的路線做為規劃或導航的唯一依據。
不支援的功能：大型車輛路線規劃不支援下列功能：
- 卡車過路費
- 速限
- 放射性危險物質路線
用量限制：所有要求都必須遵守標準每秒查詢次數 (QPS) 限制。

建立卡車路線要求

如要取得卡車路線，請向 Routes API 端點傳送 HTTPS 要求，並附上描述車輛的特定參數。本節的概念適用於單一路徑和路徑矩陣要求。

端點

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

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"
  },
  { ... }
]

後續步驟

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