有時候,您可能會想規劃應用程式為司機提供的路線。使用 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 的路徑權杖時會發生的情況:
Routes API 會傳回加密路徑權杖,其中包含路線折線和路徑目標。
將路徑權杖傳遞至 Navigation SDK。
Navigation SDK 會擷取路徑;或者,如果路線因條件變動而無法使用,則會擷取最相符的路徑。
在駕駛路線時,如果車流量或其他路況發生變化,或車輛與預定路線不同,經過修改的路徑就會持續根據符記中的路線目標,持續嘗試比對最佳路線。
這個過程可將實際路線與規劃路徑的相近程度最大化。
為什麼規劃的路線不一定能完全追蹤
請將規劃的路線和路線目標視為應遵循的準則:它們並不規定。您可能會發現規劃路徑與引導導航提供的路線不同,這是因為道路狀況、起點或在您建立規劃路徑後曾變更的其他參數有所變更。這種差異可能會導致您規劃與實際距離、預計到達時間,以及其他重要的行程品質目標不一致。
使用路線權杖規劃路徑
如要規劃路徑,請建立路徑權杖,然後將該權杖傳送至 Navigation SDK,如以下步驟所示:
步驟 1:使用 Routes 或 Routes Preferred API 建立路徑符記
透過下列其中一種方法要求路徑符記:
設定路徑要求,以符合使用路徑符記的需求條件:
- 將
travel_mode
設為DRIVING
- 將
routing_preference
設為TRAFFIC_AWARE
或TRAFFIC_AWARE_OPTIMAL
- 「勿」使用路線控點
- 將
步驟 2:將路徑權杖傳遞至 Navigation SDK
儲存路徑權杖:在 Navigation SDK 中,設定用來儲存路徑權杖的字串。例如:
String routeToken = "route token returned by Routes API";
傳回的路徑權杖範例:
{ // Other fields "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g", }
使用
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 中指定的路線點相關選項。