規劃路線

有時候，您可能會想規劃應用程式為司機提供的路線。使用 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 中，設定用來儲存路徑權杖的字串。例如：

    let routeToken = "route token returned by Routes API"

    傳回的路徑權杖範例：

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

  2. 使用 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 中指定的路線點相關選項。