欢迎参加我们于 12 月在旧金山举办的下一届 Google Maps Platform 开发者社区日活动！立即申请参加。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

生成大型车辆路线和预计到达时间

本指南的适用对象：如果您是开发者，正在构建使用卡车或其他大型车辆进行行程规划和执行的服务，请阅读本指南。相关应用场景包括计算行程时间和距离、计算预计到达时间，或生成导航应用将使用的路线。

本指南涵盖的内容：本指南介绍了如何将 Routes API 与大型车辆路线规划功能搭配使用，以请求路线、行程距离、预计行程时间和预计到达时间，这些信息会考虑大型车辆（例如商用卡车或客车）的具体属性。

如需了解如何使用 Route Optimization API 为大型车辆执行车队级计算，请参阅 Route Optimization Truck Routing 文档。

学习内容

您将了解如何执行以下操作：

构建有效的路线请求。
使用尺寸、重量和其他特征指定真实车辆的车辆信息。
解读响应，包括路线令牌和出行安全标志。

前提条件

您必须创建 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 的 FieldMask，请参阅这篇文章。

收费站

如需首选不收费路线，请在请求的 routeModifiers 属性中指定 avoidTolls。如需详细了解路线修饰符，请参阅指定要避开的路线特征。

指定 avoidTolls 并不保证响应中会包含不收费路线。在某些情况下，您必须使用收费路段才能在起点和终点之间行驶。如果您在 Routes API 请求的 fieldmask 中添加 routes.warnings，则包含收费路段的路线将在此字段中进行相应注释。

其他路由行为

当您将 travelMode 设置为 TRUCK 时，API 会自动根据大型车辆的机动性优化路线。生成的路线会避开 U 形弯，并优先选择州际公路和高速公路，而不是较小的道路。您无需设置任何其他参数或修饰符即可启用这些行为。

使用 `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 参考文档。