規劃路線

有時，您可能需要規劃應用程式提供給使用者的路線。使用 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，引導 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 設為 DRIVE 或 TWO_WHEELER
    • 將 routing_preference 設為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL
    • 請勿使用Via路線控點

步驟 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: {...})

    setDestinations 方法會將要求的狀態傳遞至回呼。如果找到從使用者位置到指定目的地的路線，狀態會是 .OK (GMSRouteStatusOK)。

多站點情境

最多可設定 25 個路線控點。

setDestinations 方法不支援多站行程。使用 continueToNextDestinationWithCompletion() 將路線控點推進至旅程的下一段。

範例

下列程式碼範例示範如何擷取規劃路線。

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:location 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 中指定的相同航點相關選項。