规划路线

有时,您可能想要规划应用为用户提供的路线。使用 Routes API(或 Routes Preferred API) 为计划的路线设置两点

  • 路线的多段线

  • 您的路线目标

例如,下面是一些您可能有的“转送”目标:

  • 最大限度地缩短送货时间:送餐商家可能希望尽可能减少送货时间 送货所需的时间

  • 尽量减少行程时间或燃料消耗:物流公司可能希望 提升司机效率并降低燃油成本。

  • 最大限度地缩短到达目的地所需的时间:服务调度操作可能需要 尽可能缩短操作员获得任务请求所需的时间。

  • 降低成本并提高安全性:拼车商家可能希望了解 一条对乘客费用更低且避开某些安全区域的路线 。

有关使用路线令牌规划路线的更多信息,请参阅 请求路由令牌

为什么要为路线目标使用路线令牌

利用 Routes 或 Routes Preferred API 中的路线令牌,您可以获得更多 控制:

  • 提前规划路线以供 Navigation SDK 使用 。

  • 为 Navigation SDK 选择最佳路线。 如果您在 Routes API 中生成路由时请求路由令牌, 每个生成的路线都会获得一个路由令牌。然后,您可以选择 传递给 Navigation SDK。

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

  • 指定更高级的路线目标,例如节能路线或最短路线 。

Routes API 路由令牌的工作原理

您可以使用 Routes API 或 Routes Preferred API 使用路线目标规划路线Routes API 会返回一个 路由令牌,您可以将其传递给 Navigation SDK,以指导它 为您的车辆规划路线。

当您从 Routes API:

  1. Routes API 会返回包含相应路线的加密路线令牌 多段线和路线目标

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

  3. Navigation SDK 会检索路线,或者路线 它会检索与 。

  4. 在驾车过程中,如果路况或其他路况发生变化,或 车辆偏离计划路线,修改的路线会不断 尝试根据令牌中的路线目标匹配最佳路线。

此过程可以最大限度地增加实际路线与计划路线的距离。

为什么规划的路线没有严格执行

请将规划的路线和路线目标视为要遵循的指南: 并不是规定性的您可能会发现规划的路线和 由于道路差异,引导式导航提供的路线 条件、出发位置或其他在您应用后更改的 并成功创建了计划路由这种差异可能会导致 您针对距离和预计到达时间以及其他重要行程制定的计划目标和实际目标 质量。

使用路线令牌规划路线

您可以通过以下方式规划路线:创建路线令牌,然后将其传递给 Navigation SDK,如以下步骤所述:

第 1 步:使用 Routes 或 Routes Preferred API 创建路线令牌

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

    • Routes APIcomputeRoutes。如需详细了解 请求路线令牌,请参阅 计算路线请求路由令牌

    • Routes Preferred APIcomputeCustomRoutes。如需详细了解 在 Routes Preferred API 中请求路线令牌,请参阅 规划路线

  2. 设置您的路线请求,以满足使用路线的要求 令牌:

    • travel_mode 设置为 DRIVING
    • routing_preference 设置为 TRAFFIC_AWARETRAFFIC_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 方法,指定相同的目的地 您在创建路线令牌时使用的航点:

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

    例如:

    CustomRoutesOptions customRoutesOptions =
          CustomRoutesOptions.builder()
          .setRouteToken(routeToken)
          .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(CustomRoutesOptions.TravelMode.TWO_WHEELER)
          .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 必须 调整返回的路线,它会使用您在 请求路线令牌因此,您应该使用 与航点相关的选项。