规划路线

有时，您可能需要规划应用为用户提供的路线。使用来自 Routes API、Routes Preferred API 或 Route Optimization API 的路线令牌，您可以为规划的路线指定两项内容：

  • 路线的多段线

  • 您的路线目标

例如，以下是一些您可能有的路线规划目标：

  • 尽可能缩短送达时间：送餐企业可能希望尽可能缩短送餐时间。

  • 尽量缩短出行时间或减少燃料消耗：物流企业可能希望提高司机的效率并降低燃料成本。

  • 最大限度地缩短到达目的地的时间：服务调度操作可能需要最大限度地缩短操作员到达作业请求地点的时间。

  • 降低费用并提高安全性：一家网约车公司可能希望找到一条对乘客来说费用更低且出于安全原因而避开某些区域的路线。

如需详细了解如何使用路线令牌规划路线，请参阅 Routes API 中的请求路线令牌和 Route Optimization API 中的过渡折线和路线令牌。

为何要为路线目标使用路线令牌

借助 Routes API、Routes Preferred API 或 Route Optimization API 提供的路线令牌，您可以更好地控制所提供的路线：

  • 提前规划路线，以便 Navigation SDK 在可能的情况下使用。

  • 选择 Navigation SDK 要使用的最佳路线。如果您在 Routes API 中生成路线时请求路线令牌，则会为每条生成的路线获取一个路线令牌。然后，您可以选择要使用的路线的令牌，并将其传递给 Navigation SDK。

  • 提前估算价格，包括估算预计到达时间和距离。虽然实际费用和时间可能会有所不同，但此估算值可缩小预期路线费用与实际路线费用之间的差距。

  • 指定更高级的路线目标，例如环保路线或最短路线。

路线令牌的工作原理

您可以使用 Routes API、Routes Preferred API 或 Route Optimization API，根据路线目标规划路线。您可以将从上述任何 API 返回的路线令牌传递给 Navigation SDK，以指导该 SDK 如何为您的车辆规划路线。

以下是您请求和使用路线令牌时发生的情况：

  1. Routes API、Routes Preferred API 或 Route Optimization API 会返回一个加密的路线令牌，其中包含路线折线和路线目标。

  2. 您将路线令牌传递给 Navigation SDK。

  3. Navigation SDK 会检索路线，如果由于情况变化而无法检索到路线，则会检索最匹配的路线。

  4. 在驾驶路线期间，如果交通或其他路况发生变化，或者车辆偏离了规划的路线，修改后的路线会根据令牌中的路线目标不断尝试匹配最佳路线。

此流程可最大限度地缩小实际路线与规划路线之间的差距。

为什么可能无法完全按照规划的路线行驶

将规划的路线和路线目标视为要遵循的指导原则，而不是规定。由于路况、出发地点或自您创建规划路线以来发生变化的其他参数存在差异，您可能会发现规划路线与引导式导航提供的路线有所不同。这种差异可能会导致您在距离和预计到达时间等其他重要行程质量方面，计划目标与实际目标不符。

使用路线令牌规划路线

您可以按照以下步骤中的说明，通过创建路线令牌并将其传递给 Navigation SDK 来规划路线：

第 1 步：使用 Routes API、Routes Preferred API 或 Route Optimization API 创建路线令牌

  1. 使用以下方法之一请求路线令牌：

    • Routes API：computeRoutes。如需详细了解如何在 Routes API 中请求路线令牌，请参阅计算路线和请求路线令牌。

    • Routes Preferred API：computeCustomRoutes。如需详细了解如何在 Routes Preferred API 中请求路线令牌，请参阅规划路线。

    • Route Optimization API：optimizeTours 或 batchOptimizeTours。如需详细了解如何在路线优化 API 中请求路线令牌，请参阅过渡折线和路线令牌。

  2. 设置 Routes API 或 Routes Preferred API 请求，以满足使用路线令牌的要求：

    • 将 travel_mode 设置为 DRIVING 或 TWO_WHEELER
    • 将 routing_preference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL
    • 请勿使用 Via 航点

第 2 步：将路线令牌传递给 Navigation SDK

  1. 存储路线令牌：在 Navigation SDK 中，设置一个字符串来存储路线令牌。例如：

    String routeToken = "route token returned by Routes API";

    返回的路线令牌示例：

    {
// Other fields
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
}

  2. 使用 Navigator.setDestinations 方法将路线令牌传递给 Navigation SDK，并指定与创建路线令牌时使用的相同的目的地途经点：

    setDestinations(List destinations, CustomRoutesOptions customRoutesOptions, DisplayOptions displayOptions);

    例如：

    CustomRoutesOptions customRoutesOptions =
      CustomRoutesOptions.builder()
      .setRouteToken(routeToken)
      .setTravelMode(TravelMode.DRIVING)
      .build();

Navigator.setDestinations 方法会返回请求的状态。如果找到从车辆位置到指定目的地的路线，则返回 RouteStatus.OK。

如需详细了解此方法，请参阅 Navigator.setDestinations。

示例

以下代码示例演示了如何使用路线令牌指定规划的路线。

    ArrayList <Waypoint> destinations = Lists.newArrayList();
    Waypoint waypoint1 =
       Waypoint.builder()
          .setLatLng(10, 20)
          .setTitle("title")
          .setVehicleStopover(true)
          .build();
    destinations.add(waypoint1);
    Waypoint waypoint2 =
       Waypoint.builder()
          .setPlaceId("ChIJYV-J-ziuEmsRIMyoFaMedU4")
          .setTitle("title")
          .setVehicleStopover(true)
           .build()
    destinations.add(waypoint2);

    String routeToken = "route token returned by Routes API";

    CustomRoutesOptions customRoutesOptions =
       CustomRoutesOptions.builder()
          .setRouteToken(routeToken)
          .setTravelMode(TravelMode.DRIVING)
          .build();

    // Existing flow to get a Navigator.
    NavigationApi.getNavigator(...);

    // Existing flow for requesting routes.
    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions);

    // Or with display options.
    DisplayOptions displayOptions = new DisplayOptions();

    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions, displayOptions);

路线令牌和 Navigation SDK 如何交互

以下是 Navigation SDK 生成的路线与路线令牌中的规划路线之间的互动方式：

  • 替换之前设置的所有目的地。

  • 使用车辆的出发地点。

  • 根据道路和交通状况进行调整。请参阅为什么可能无法完全按照规划的路线行驶。

  • 忽略以下与路由相关的选项（因为它们是不必要的）：

    • avoidsHighways
    • avoidsTolls
    • avoidsFerries
    • licensePlateRestriction

  • 关注者人数：

    • 与途经点相关的选项，例如道路一侧偏好设置。

    • 路线目标。如果 Navigation SDK 必须调整返回的路线，它会使用您在请求路线令牌时指定的路线目标。因此，您应使用在 Routes API 中指定的与途经点相关的相同选项。