处理行程数据

当您检索行程数据时，后端会收到 JSON 载荷，其中详细说明了司机的行程进度。解析这些载荷，以监控行程、更新调度系统，并解读当前的行程状态，以便在司机行进过程中或行程结束时确定司机的下一步行动。

读取数据载荷

当司机开始导航时，Google 地图或 Waze 会将行程数据载荷发送到 Navigation Connect 服务器，并在沿途定期发送（默认情况下每 60 秒发送一次），以及在司机到达目的地时发送。每条 JSON 消息都包含相关的行程数据，包括司机的道路贴合坐标、行驶距离和预计到达时间 (ETA)。

以下代码示例展示了当司机开始从国王十字车站到圣吉尔斯中心车站的行程导航时，行程数据载荷的情况。

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

监控活跃行程状态

如需确认行程已成功开始并监控进度，请评估每个载荷中的状态字段。

状态 说明
NEW 行程已创建，但司机尚未开始导航。
ENROUTE 司机正在积极导航前往目的地。使用此状态确认行程已成功通过身份验证并已开始。

处理添加的经停点

司机可以在导航期间向路线添加经停点。如果司机添加了经停点，Navigation Connect 会在 JSON 数据载荷中将 execution.stopAddedInRoute 字段设置为 true。Navigation Connect API 会继续跟踪司机前往原始目的地。预计到达时间 (ETA)、距离和时长等指标会增加，以包含添加的经停点。

添加经停点的行为取决于导航应用，并与其标准功能相匹配：

  • Google 地图 ：司机可以向路线添加多个经停点。
  • Waze ：司机只能添加一个经停点。如果司机尝试添加另一个经停点，Waze 会提示他们开始新的导航会话，而不是将经停点添加到当前路线。

您无需调整后端输入即可支持此功能。

排查身份验证和启动问题

如果您未收到 ENROUTE 状态，则可能发生了身份验证错误。常见原因包括 API 参数拼写错误或行程令牌已过期。请在初始 CreateTrip 响应中检查令牌到期时间。

如果状态未从 NEW 更改为 ENROUTE，则可能是司机的设备阻止了身份验证。Navigation Connect 不会针对这些情况发送错误消息。请验证以下事项：

  • 司机安装了 Waze 5.15.5 或更高版本，或者 Google 地图 26.14 或更高版本。
  • 司机未使用 Android Auto 或 Apple CarPlay。
  • 司机已连接到互联网。

处理剩余路线数据（仅限 Waze）

如果您在创建行程期间启用了剩余路线报告 during trip creation, 则后端会收到从司机当前位置到最终目的地的活跃路线折线和实时路况信息 。

您可以提取和处理此数据，以支持应用中的多项功能，包括以下示例：

  • 支持实时跟踪地图：在 面向客户的网站或移动地图上呈现剩余路线折线，以便客户了解司机的 行程。
  • 提高 ETA 准确性：结合道路贴合折线和路况 间隔速度，改进内部物流或配送到达 预测。
  • 分析路线合规性：将剩余路线几何图形与 预期调度路线进行比较，以评估司机是否遵守路线。

无论您是发送 GetTrip 请求还是使用 Google Cloud Pub/Sub 接收事件驱动型更新，Navigation Connect 都会在 execution.remainingRoute 字段中返回剩余路线详细信息。不过，载荷如何格式化和构建此数据取决于您使用的数据检索方法。

GetTrip 方法

当您调用 GetTrip 方法时，折线的响应格式取决于您在请求中指定的 routePolylineFormat 参数。如需了解更多 信息，请参阅自定义折线格式。

对于所有折线格式，Navigation Connect 都会在 execution.remainingRoute.trafficInformation 字段中将路况作为单独的 SpeedReadingInterval 对象列表返回。这些对象使用以下值将路况类别映射到多段线索引：

  • startPolylinePointIndex：折线上路况间隔的起始索引。
  • endPolylinePointIndex：路况间隔的结束索引。
  • speed：此路段的路况类别：NORMAL、SLOW 或 TRAFFIC_JAM。

Google Cloud Pub/Sub 更新

当您 使用 Pub/Sub 检索行程数据， 更新始终会在 execution.remainingRoute 字段中以统一的 GeoJSON FeatureCollection 格式返回剩余路线数据。

此格式直接将多段线几何图形与路况速度相结合，无需手动映射索引。

查看 Pub/Sub 载荷示例

以下代码示例展示了在 Pub/Sub 消息的 updatedTrip 对象内的 execution.remainingRoute 字段中返回的 GeoJSON 结构：

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}

优化载荷大小

由于坐标数组很大，因此在 Pub/Sub 消息中包含剩余路线数据可能会显著增加载荷大小（每条消息最多 13-14 KB）。如果您收到高频率的更新，此数据量可能会增加后端处理负载和使用费用。

如需优化数据流，请在创建行程期间使用 TripConfig 对象中的 pubsubFieldMask 参数排除大型字段。如需了解 详情，请参阅 可选配置。

处理行程结束状态

当司机到达目的地或停止导航时，载荷会返回以下结束状态之一。使用这些状态触发应用中相应的后续步骤。

状态 说明 推荐措施
ARRIVED 司机已到达目的地。 检查 remainingDistanceMeters。如果司机停在 附近但不在确切坐标处，请考虑在应用中提供步行 路线。
SUSPENDED 司机在到达目的地之前手动退出了精细导航 。
由于 Google 地图或 Waze 不会在司机提前退出会话时自动将其返回到您的应用，因此司机必须手动点按返回按钮。		 为了帮助司机完成行程，请将 execution.location 与目的地进行比较。如果仍有距离 ，请提供一个按钮或链接以恢复行程或切换到 步行模式。
FAILED 技术错误中断了连接。如果应用 无法计算路线或出现安全警告，则会发生这种情况。司机可能 仍在导航，但您不会收到更新。 在应用中回退到手动状态跟踪。
CLIENT_ERROR 出现此状态的原因如下之一： 在应用中回退到手动状态跟踪。