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

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

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

如需了解如何使用 Route Optimization API 为大型车辆执行舰队级计算，请参阅路线优化卡车路线文档。

学习内容

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

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

前提条件

  1. 您必须创建 Google Cloud 项目并启用 Routes API。
  2. 您的项目必须已预配大型车辆路线规划服务。大型车辆路线规划功能仅面向部分客户提供，请与我们联系以申请使用权限

限制

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

  • 适用地区：大型车辆路线规划功能已在美国本土 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"
  },
  { ... }
]

后续步骤