規劃路線

有時候，您可能會想規劃應用程式為使用者提供的路線。使用 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 API：computeRoutes。如要進一步瞭解如何在 Routes API 中要求路徑權杖，請參閱「計算路徑」和「要求路徑權杖」。

    • Routes Preferred API：computeCustomRoutes。如要進一步瞭解如何在 Routes Preferred API 中要求路徑權杖，請參閱「規劃路徑」。

  2. 設定路徑要求，以符合使用路徑權杖的需求條件：

    • 將 travel_mode 設為 DRIVING
    • 將「routing_preference」設為「TRAFFIC_AWARE」或「TRAFFIC_AWARE_OPTIMAL」
    • 請勿使用透過路線控點

步驟 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)
      .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 必須調整傳回的路徑，則會使用您在要求路徑權杖時指定的路徑目標。因此，您應使用與 Routes API 中指定的路線控點相關選項相同。