Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

ルートを計画する

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

ルートのポリライン
ルートの目標

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

配達時間を最小限に抑える: 食品を配達するビジネスでは、食品の配達にかかる時間を最小限に抑える必要があります。
移動時間または燃料消費量を最小限に抑える: 物流ビジネスでは、ドライバーの効率を向上させ、燃料費を削減したい場合があります。
目的地までの時間を最小限に抑える: サービスディスパッチオペレーションでは、オペレーターがジョブリクエストを受け取るまでの時間を最小限に抑えることが必要になる場合があります。
コストの削減と安全性の向上: ライドシェアリングビジネスでは、乗客の費用を抑え、安全上の理由から特定のエリアを避けるルートを見つけることが求められます。

ルートトークンを使用したルート計画の詳細については、Routes API のルートトークンを取得すると、Route Optimization API の移行ポリラインとルートトークンをご覧ください。

ルート目標にルートトークンを使用する理由

Routes API または Route Optimization API のルートトークンを使用すると、提供されるルートをより細かく制御できます。

Navigation SDK で使用するルートを事前に計画します。
Navigation SDK で使用する最適なルートを選択する。Routes API でルートを生成するときにルートトークンをリクエストすると、生成されたルートごとにルートトークンが取得されます。その後、Navigation SDK に渡すときに使用するルートのトークンを選択できます。
ETA と距離の見積もりを含む料金を事前に見積もります。実際の費用と時間は異なる場合がありますが、この推定により、予想されるルート費用と実際のルート費用の差が縮小されます。
エコルートや最短ルートなど、より高度なルート目標を指定します。

ルートトークンの仕組み

Routes API または Route Optimization API を使用して、ルート目標を使用してルートを計画できます。これらの API のいずれかから返されたルートトークンを Navigation SDK に渡して、車両のルートを案内できます。

ルートトークンをリクエストして使用すると、次のようになります。

Routes API または Route Optimization API は、ルートポリラインとルート目標を含む暗号化されたルートトークンを返します。
ルートトークンを Navigation SDK に渡します。
Navigation SDK は、より速いルートが利用可能な場合でも、計画したルートでナビゲーションを開始します。
移動中に交通状況や道路状況が変化した場合、または車両が予定ルートから外れた場合、Navigation SDK は、ルートトークンで設定されたルート目標とルートオプションに沿って新しいルートを計算します。

このプロセスにより、実際のルートが計画ルートにできるだけ近づくようにします。

計画されたルートに正確に従わない理由

ナビゲーションは計画されたルートで開始されますが、次のような状況では実際のルートが異なる場合があります。

車両が、計画された始点から離れた場所から出発する。
乗車中に交通状況や道路状況が変化した。
車両が予定されたルートから外れる。

これらの違いは、計画した距離、到着予定時刻、その他の重要なルート品質に影響する可能性があります。

ルートトークンを使用してルートを計画する

ルートを計画するには、ルートトークンを作成して Navigation SDK に渡します。手順は次のとおりです。

ステップ 1: Routes API または Route Optimization API を使用してルートトークンを作成する

次のいずれかの方法でルートトークンをリクエストします。
- Routes API: computeRoutes。Routes API でルートトークンをリクエストする方法については、ルートを計算するとルートトークンを取得するをご覧ください。
- Route Optimization API: optimizeTours または batchOptimizeTours。Route Optimization API でルートトークンをリクエストする方法については、遷移ポリラインとルートトークンをご覧ください。
ルートトークンを使用するための要件を満たすように Routes API リクエストを設定します。
- travelMode を DRIVE または TWO_WHEELER に設定します。
- routingPreference を TRAFFIC_AWARE または TRAFFIC_AWARE_OPTIMAL に設定します。
- Via ウェイポイントは使用しないでください。

ステップ 2: ルートトークンを Navigation SDK に渡す

ルートトークンを保存する: Navigation SDK で、ルートトークンを保存する文字列を設定します。次に例を示します。

let routeToken = "route token returned by Routes API"

返されるルートトークンの例:

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

mapView.navigator の setDestinationsWithToken:completionHandler: メソッドを使用して、ルートトークンを Navigation SDK に渡します。Navigation SDK はルートトークンから目的地とルートオプションを取得するため、ウェイポイントを渡す必要はありません。

アプリで設定する移動モード（mapView.travelMode など）は、次のいずれかの値にする必要があります。
- .driving（GMSNavigationTravelModeDriving）: 運転中。これはデフォルト値であるため、ほとんどのアプリでは変更する必要はありません。
- .twoWheeler（GMSNavigationTravelModeTwoWheeler）: 二輪車。
他の移動手段を指定すると、リクエストは .travelModeUnsupported（GMSRouteStatusTravelModeUnsupported）で失敗します。サポートされているいずれかの値を指定すると、ルートトークンに指定された移動手段が使用されます。たとえば、アプリが運転を使用し、ルートトークンが二輪車ルート用の場合、Navigation SDK は二輪車ルートを提供します。ルートで使用されている移動手段を確認するには、resolvedParameters.travelMode を確認します。詳細については、解決済みのルーティングオプションをご覧ください。

注: アプリで 11.3 より前のバージョンの Navigation SDK を使用している場合は、代わりに非推奨の setDestinations:routeToken:callback: メソッドを使用し、ルートトークンの作成に使用したのと同じ目的地のウェイポイントを渡します。
完了ハンドラでルートのステータスを確認します。Navigation SDK は、ルートの計算が完了すると、GMSNavigationRouteDescription を完了ハンドラに渡します。車両の位置からルートトークン内の目的地までのルートが見つかった場合、ルートの説明の routeStatus は .OK（GMSRouteStatusOK）になり、案内を開始できます。それ以外の場合、完了ハンドラはエラーを説明する NSError も受け取ります。次に例を示します。
```
mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  if routeDescription?.routeStatus == .OK {
    self?.mapView.navigator?.isGuidanceActive = true
  }
}
```

Navigation SDK がルートトークンを適用したかどうかを確認する

ルートステータスが .OK の場合、Navigation SDK がルートを見つけたことを意味しますが、計画したルートとは限りません。ルートが予定ルートと一致するかどうかを確認するには、完了ハンドラで次の手順を行います。

ルートの説明の routeStatus が .OK であることを確認します。Navigation SDK は、ルートが見つかった場合にのみルートトークンの詳細を提供します。詳しくは、ステップ 2 をご覧ください。
ルートの説明の routeTokenExecutionDetails（GMSNavigationRouteTokenExecutionDetails プロトコルに準拠するオブジェクト）を取得します。サーバーがルートトークンの詳細を提供しない場合、このプロパティは nil です。
実行の詳細の tokenExecutionStatus プロパティを確認します。.tokenSuccessfullyApplied の場合、ルートは計画したルートと一致します。それ以外のステータスは、ルートが予定ルートと異なる可能性があることを意味します。各ステータスの詳細については、トークン実行ステータスの値をご覧ください。
省略可: ステータスが .tokenSuccessfullyApplied の場合は、同じ実行の詳細の resolvedParameters プロパティをチェックして、ルートが使用するルーティングオプション（有料道路を回避するかどうかなど）を確認します。詳細については、解決済みのルーティングオプションをご覧ください。

トークンの実行ステータスの値

routeStatus が .OK の場合、任意のトークン実行ステータスでガイダンスを開始できます。ステータスは、ルートが計画されたルートに沿っているかどうかを示します。

ステータス	計画されたルートに沿って走行する	説明
`.tokenSuccessfullyApplied`	はい	Navigation SDK がルートトークンを適用しました。
`.tokenAppliedWithLocationMismatch`	必ずしもそうとは限りません	Navigation SDK が計画されたルートを再構築できず、デバイスがルートトークンの出発地から 25 メートル以上離れていました。ルートには、ルートトークンの目的地とルート設定オプションが引き続き使用されます。
`.tokenIgnoredOther`	必ずしもそうとは限りません	Navigation SDK が別の理由で計画されたルートを再構築できなかった（計画されたルート上の道路が閉鎖されているなど）。ルートには、ルートトークンの目的地とルート設定オプションが引き続き使用されます。
`.noTokenProvided`	該当なし	ルートリクエストにルートトークンが含まれていませんでした。
`.unknown`	不明	ステータスが不明です。

ルートが必ずしも計画されたルートに沿っておらず、正確なルートが重要である場合（たとえば、料金の計算に使用した場合）は、ステータスをログに記録するか、車両の現在地から新しいルートトークンをリクエストします。

解決済みのルーティングオプション

resolvedParameters は、GMSNavigationRouteTokenResolvedParameters プロトコルに準拠するオブジェクトです。ルーティングオプションが利用できない場合は nil です。これには次のプロパティがあります。

travelMode: ルートで使用される移動手段（.driving（GMSNavigationTravelModeDriving）など）。Navigation SDK は、一致する値がない移動手段をルートで使用している場合や、移動手段が利用できない場合にも .driving を報告します。
avoidTolls: ルートで有料道路を避けるかどうか。
avoidHighways: ルートで高速道路を避けるかどうか。
avoidFerries: ルートでフェリーを避けるかどうか。
avoidTunnels: 可能であればトンネルを避けるようにルートが計算されたかどうか。
avoidVignettes: 可能な限り有料道路を回避するようにルートが計算された国。Unicode CLDR の 2 文字のリージョンコード（スイスの場合は CH など）で表されます。
rerouteStrategy: ルーティングバックエンドがルート中に新しいルートを計算するために使用する戦略。戦略には、ルートトークンのルーティングパラメータを使用して新しいルートを計算する .bestBasedOnTokenParameters（GMSNavigationRerouteStrategyBestBasedOnTokenParameters）などがあります。

トークンの実行ステータスが .tokenSuccessfullyApplied でない場合、Navigation SDK は travelMode、avoidTolls、avoidHighways、avoidFerries のみを報告します。他のプロパティには、ルートトークンをリクエストしたときにトンネルや有料道路のヴィネットを回避するようにリクエストした場合でも、デフォルト値が設定されます。avoidTunnels は false（NO）、avoidVignettes は空、rerouteStrategy は .unknown（GMSNavigationRerouteStrategyUnknown）です。

例

次のコード例は、ルートトークンを使用してルートを計画し、Navigation SDK がトークンを適用したかどうかを確認して、案内を開始する方法を示しています。

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

複数経由地のシナリオ

最大 25 個のウェイポイントを設定できます。

Navigation SDK は、次の目的地に自動的に進むことはありません。車両がウェイポイントに到着したら、continueToNextDestinationWithCompletion: を呼び出してルートの次の区間を開始します。これは、中間ウェイポイントを含むルートトークンにも適用されます。次の目的地に進むと、Navigation SDK は新しいルートを計画するのではなく、ルートトークンのルートを引き続き使用します。

ルートトークンと Navigation SDK の連携

Navigation SDK が計画されたルートを処理する方法は次のとおりです。

以前に設定された宛先をオーバーライドします。
車両の開始位置を使用します。
道路や交通状況に合わせて調整します。計画されたルートに正確に従わない理由をご覧ください。

アプリの次の設定ではなく、ルートトークンに設定されたルーティングオプションを使用します。これには、移動中に新しいルートを計算する場合も含まれます。
- avoidsHighways
- avoidsTolls
- avoidsFerries
- licensePlateRestriction
- アプリで設定されている移動手段

ルートを計算または調整する際に、次の設定に従います。
- ルートトークンからのルート目標（エコルーティングや最短ルートなど）。Navigation SDK でルートを調整する必要がある場合は、ルートトークンをリクエストしたときに指定したルート目標が使用されます。
- ルートトークンのウェイポイント関連オプション（道路のどちら側を優先するかなど）。