规划路线

有时，您可能需要规划应用向用户提供的路线。使用 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，以指导其如何为您的车辆规划路线。

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

  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。如需详细了解如何在 Route Optimization API 中请求路线令牌，请参阅多段线和路线令牌转换。

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

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

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

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

    let routeToken = "route token returned by Routes API"

    返回的路线令牌示例：

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

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

    mapView.navigator?.continueToNextDestination([waypoint1, waypoint2], routeToken: routeToken, callback: {...})

    Navigator.continueToNextDestination 方法会返回请求的状态。如果找到从用户位置到给定目的地的路线，则会返回 RouteStatus.OK。

多停靠点场景

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

setDestinations 方法不支持多停靠点行程。使用 continueToNextDestination() 将航点推进到行程的下一段。

示例

以下代码示例演示了如何检索规划路线。

Swift

let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)
let waypoint1 = GMSNavigationWaypoint(location: location, title: "waypoint from location")!
let waypoint2 = GMSNavigationWaypoint(placeID: "samplePlaceID", title: "waypoint from Place ID")!

let routeToken = "route token returned by Routes API"
mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})

Objective-C

CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);
GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:coordinate title:@"waypoint from location"];
GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@"samplePlaceID"
                                                                            title:@"waypoint from Place ID"];
NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator continueToNextDestination:@[waypoint1, waypoint2]
                         routeToken:routeToken
                           callback:^(GMSRouteStatus routeStatus){...}];

路线令牌和 Navigation SDK 的交互方式

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

  • 替换 任何先前设置的目的地。

  • 使用 车辆的出发地。

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

  • 忽略 以下与路线规划相关的选项，因为它们是不必要的：

    • avoidsHighways
    • avoidsTolls
    • avoidsFerries
    • licensePlateRestriction

  • 遵循：

    • 与航点相关的选项，例如道路偏好。

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