規劃路線

注意： Navigation SDK 遵循規劃路線的方式更新 (包括新增 betterRouteTimeTolerance 欄位) 正在逐步推出，預計 2026 年 10 月 22 日前會向所有專案開放。在此之前，Routes API 可能會拒絕包含 betterRouteTimeTolerance 的要求。

有時，您可能需要規劃應用程式提供給使用者的路線。使用 Routes API、Routes Preferred API 或 Route Optimization API 的路線權杖，可協助您為規劃路線指定兩項資訊：

• 路線的折線

• 路線目標

以下列舉幾個可能的轉送目標：

• 盡可能縮短運送時間：外送餐點的商家可能希望盡可能縮短外送餐點所需的時間。

• 盡可能縮短行程時間或減少燃料消耗：物流公司可能希望提高司機效率並降低燃料成本。

• 盡可能縮短抵達目的地的時間：服務派遣作業可能需要盡可能縮短操作員抵達工作地點的時間。

• 降低成本並提高安全性：多元計程車業者可能想找出乘客費用較低的路線，並基於安全考量避開特定區域。

重要事項： 司機行駛的路線可能與你規劃的路線不同。 路況或道路狀況改變、車輛偏離規劃路線，或切換至更快的路線，都可能導致行程中路線變更。每當 Navigation SDK 計算新路線時，都會使用路線權杖中設定的路線選項，例如避開收費路段。

如要進一步瞭解如何使用路線權杖規劃路線，請參閱 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 要求，才能取得新的路線權杖。

路徑權杖的運作方式

您可以使用 Routes API、Routes Preferred API 或 Route Optimization API，根據路線目標規劃路線。您可以將上述任一 API 傳回的路徑權杖傳遞至 Navigation SDK，引導車輛行駛。

要求及使用路徑權杖時，會發生以下情況：

1. Routes API、Routes Preferred API 或 Route Optimization API 會傳回加密路徑權杖，其中包含路徑折線和路徑目標。

2. 將路徑權杖傳遞至 Navigation SDK。

3. Navigation SDK 會按照規劃路線開始導航，即使有更快的路線也一樣。

4. 在行程中，如果路況或道路狀況有變，或車輛偏離規劃路線，Navigation SDK 會根據路線權杖中設定的路線目標和路線選項，計算新路線。

這項程序可盡量縮短實際路線與規劃路線之間的距離。

未完全按照規劃路線行駛的可能原因

導航會從規劃的路線開始，但實際路線可能會與規劃路線不同，例如：

• 車輛從預定起點以外的位置出發。
• 行程期間路況或道路條件有變。
• 車輛偏離預定路線。

這些差異可能會影響您規劃的距離、預計到達時間和其他重要行程品質。

提示： 最佳做法是每次在 Navigation SDK 中設定目的地時，一律要求新的路線權杖，並預留一些緩衝時間，以免對業務造成任何影響。

使用路線權杖規劃路線

您可以建立路徑權杖，然後傳遞至 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 要求，以符合使用路線權杖的規定：

   • 將 travelMode 設為 DRIVE 或 TWO_WHEELER。
   • 將 routingPreference 設為 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() 將路線控點推進到旅程的下一段。

注意： 呼叫 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 必須調整路線，會使用您在要求路線權杖時指定的路線目標。

  • 應用程式中與路線控點相關的選項，例如偏好的道路側。請使用與要求路線權杖時指定的相同路線控點相關選項。