规划路线

注意： Navigation SDK 遵循规划路线的方式更新正在逐步推出，并将于 2026 年 10 月 22 日之前面向所有项目提供。在此之前，Routes API 可能会拒绝包含 betterRouteTimeTolerance 的请求。

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

• 路线的多段线

• 您的路线目标

例如，以下是您可能需要实现的一些转送目标：

• 最大限度地缩短送货时间：送餐企业可能希望最大限度地缩短送餐时间。

• 最大限度地缩短行程时间或减少燃料消耗：物流企业可能希望提高司机的效率并降低燃料成本。

• 尽可能缩短到达目的地的时间：服务调度操作可能希望尽可能缩短操作员到达作业请求地点所需的时间。

• 降低成本并提高安全性：拼车业务可能希望找到一条对乘客来说成本更低的路线，并出于安全原因避开某些区域。

重要提示： 司机行驶的路线可能与您规划的路线不同。 路况或道路状况的变化、车辆偏离规划路线或切换到更快的路线都可能会在行程中改变路线。每当 Navigation SDK 计算新路线时，都会使用路线令牌中设置的路线选项，例如避开收费路段。

如需详细了解如何使用路线令牌规划路线，请参阅 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 请求，才能获取新的路线令牌。

路线令牌的工作原理

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

请求和使用路线令牌时，会发生以下情况：

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

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

3. Navigation SDK 会在您规划的路线（即使有更快的路线）上启动导航。

4. 在行程中，如果路况或道路状况发生变化，或者车辆偏离规划路线，Navigation SDK 会根据路线令牌中设置的路线目标和路线选项计算新路线。

此过程可最大限度地缩短实际路线与规划路线之间的距离。

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

导航会从规划的路线开始，但在以下情况下，实际路线可能会与规划的路线不同：

• 车辆从规划的起点以外的位置出发。
• 行程期间路况或道路条件发生变化。
• 车辆偏离规划路线。

这些差异可能会影响您规划的距离、预计到达时间和其他重要行程质量。

提示： 作为最佳实践，请始终在 Navigation SDK 中设置目的地时请求新的路线令牌，并做好应对一些变化的准备，以免对您的业务产生任何影响。

使用路线令牌规划路线

您可以按照以下步骤创建路线令牌，然后将其传递给 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。如需详细了解如何在 Route Optimization API 中请求路线令牌，请参阅过渡多段线和路线令牌。

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

   • 将 travelMode 设置为 DRIVE 或 TWO_WHEELER。
   • 将 routingPreference 设置为 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);

注意： 您最多可以配置 25 个航点。

路线令牌和 Navigation SDK 如何交互

Navigation SDK 会按以下方式处理您规划的路线：

• 覆盖之前设置的所有目的地。

• 使用车辆的出发地点。

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

• 使用路线令牌中设置的路线选项，而不是应用中的以下设置，包括在行程期间计算新路线时：

  • RoutingOptions.avoidHighways()
  • RoutingOptions.avoidTolls()
  • RoutingOptions.avoidFerries()
  • Navigator.setLicensePlateRestrictionInfo()
  • 应用中设置的出行方式

• 在计算或调整路线时，遵循以下设置：

  • 路线令牌中的路线目标，例如环保路线或最短路线。如果 Navigation SDK 必须调整路线，它会使用您在请求路线令牌时指定的路线目标。

  • 应用中与航点相关的选项，例如道路一侧偏好设置。使用您在请求路线令牌时指定的相同航点相关选项。