規劃路線

有時您可能想規劃應用程式提供給使用者的路線。使用 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 設為 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 中指定的相同航點相關選項。