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

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

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

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

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

学习内容

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

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

前提条件

您必须创建 Google Cloud 项目并启用 Routes API。
您的项目必须针对大型车辆路线规划进行了预配。请与您的 Google 代表联系，以完成此步骤。

限制

在开始之前，您必须了解以下限制和要求。

地理位置限制：大型车辆路线规划功能仅适用于美国本土 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，则包含收费公路的路线将在此字段中相应地添加注释。

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

后续步骤

提供精细导航：了解如何使用routeToken中的提供适合卡车的精细导航路线。
执行车队级优化：使用 Route Optimization API 和大型车辆路线规划。
API 参考文档：如需查看所有可能的字段和值的完整列表，请参阅 Routes API 参考文档。