有時候,您可能會想規劃應用程式為使用者提供的路線。使用 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 中,設定用來儲存路徑權杖的字串。例如:
let routeToken = "route token returned by Routes API"
傳回的路徑符記範例:
{ // Other fields "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g", }
使用
mapView.navigator setDestinations
方法將路徑權杖傳遞至 Navigation SDK,並指定您在建立路徑權杖時使用的相同目的地路線點:mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})
Navigator.setDestinations
方法會傳回要求的狀態。如果發現從使用者位置到指定目的地的路線,則會傳回 RouteStatus.OK
。
如要進一步瞭解這個方法,請參閱 Navigator.setDestinations
。
範例
以下程式碼範例示範如何擷取規劃的路徑。
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 setDestinations:@[waypoint1, waypoint2]
routeToken:routeToken
callback:^(GMSRouteStatus routeStatus){...}];
路徑權杖與 Navigation SDK 的互動方式
以下為 Navigation SDK 產生的路徑和路徑權杖中的預定路徑互動方式:
覆寫任何先前設定的目的地。
使用車輛的起點位置。
調整道路和路況。請參閱「為何無法完全遵循預定路徑」一節。
視需要忽略下列轉送相關選項:
avoidsHighways
avoidsTolls
avoidsFerries
licensePlateRestriction
追蹤次數:
路線控點相關選項,例如道路側邊偏好設定。
路徑目標。如果 Navigation SDK 必須調整傳回的路徑,則會使用您在要求路徑權杖時指定的路徑目標。因此,您應使用與 Routes API 中指定的路線控點相關選項相同。