ルートを計画する

注: Navigation SDK が計画されたルートをたどる方法の更新（新しい betterRouteTimeTolerance フィールドを含む）は段階的にリリースされ、2026 年 10 月 22 日までにすべてのプロジェクトで利用可能になります。それまでは、Routes API は betterRouteTimeTolerance を含むリクエストを拒否する可能性があります。

アプリがユーザーに提供するルートを計画したい場合があります。Routes API、Routes Preferred API、または Route Optimization API のルートトークンを使用すると、計画ルートに次の 2 つを指定できます。

• ルートのポリライン

• ルートの目標

たとえば、次のようなルーティング目標が考えられます。

• 配達時間を最小限に抑える: 食品を配達するビジネスでは、食品の配達にかかる時間を最小限に抑える必要があります。

• 移動時間または燃料消費量を最小限に抑える: 物流企業は、ドライバーの効率を向上させ、燃料費を削減したいと考えている場合があります。

• 目的地までの時間を最小限に抑える: サービス ディスパッチ オペレーションでは、オペレーターがジョブリクエストに到達するまでの時間を最小限に抑えることが必要になる場合があります。

• コストを削減し、安全性を向上させる: ライドシェアリング ビジネスでは、乗客の費用を抑え、安全上の理由から特定のエリアを避けるルートを見つけることが必要になる場合があります。

重要: ドライバーが走行するルートは、計画したルートと異なる場合があります。 交通状況や道路状況の変化、車両が予定ルートから外れた場合、より速いルートへの切り替えなどにより、移動中にルートが変更されることがあります。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 でルートを調整する必要がある場合は、ルートトークンをリクエストしたときに指定したルート目標が使用されます。

  • アプリのウェイポイント関連のオプション（道路のどちら側を優先するかなど）。ルートトークンをリクエストしたときに指定したウェイポイント関連のオプションと同じものを使用します。