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 で、ルートトークンを保存する文字列を設定します。次に例を示します。

String routeToken = "route token returned by Routes API";

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

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

Navigator.setDestinationsWithToken メソッドを使用して、Navigation SDK にルートトークンを渡します。Navigation SDK は、ルートトークンから目的地とルート設定を取得するため、ウェイポイントや移動手段を渡す必要はありません。
```
setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
```
注: アプリで 8.1 より前のバージョンの Navigation SDK を使用している場合は、代わりに CustomRoutesOptions を受け取る非推奨の setDestinations メソッドを使用し、ルートトークンの作成に使用したのと同じ目的地のウェイポイントを渡します。
コールバックでルートのステータスを確認します。Navigation SDK は、ルートの計算が完了すると、RouteDescription をコールバックに渡します。車両の位置からルートトークン内の目的地までのルートが見つかった場合、RouteDescription.getRouteStatus は Navigator.RouteStatus.OK を返し、ガイダンスを開始できます。次に例を示します。
```
navigator.setDestinationsWithToken(
    routeToken,
    routeDescription -> {
      if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
        navigator.startGuidance();
      }
    });
```

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

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

RouteDescription.getRouteStatus が Navigator.RouteStatus.OK を返すことを確認します。Navigation SDK は、ルートが見つかった場合にのみルートトークンの詳細を提供します。詳細については、ステップ 2 をご覧ください。
RouteDescription.getRouteTokenExecutionDetails を呼び出して RouteTokenExecutionDetails オブジェクトを取得します。サーバーがルートトークンの詳細を提供しない場合、このメソッドは null を返します。
RouteTokenExecutionDetails オブジェクトで getTokenExecutionStatus を呼び出します。TOKEN_SUCCESSFULLY_APPLIED が返された場合、ルートは計画したルートと一致します。それ以外のステータスは、ルートが予定ルートと異なる可能性があることを意味します。各ステータスの詳細については、トークンの実行ステータスの値をご覧ください。
省略可: ステータスが TOKEN_SUCCESSFULLY_APPLIED の場合は、同じ RouteTokenExecutionDetails オブジェクトで getResolvedParameters を呼び出して、ルートで使用されているルートオプション（有料道路を回避するかどうかなど）を確認します。詳細については、解決済みのルーティングオプションをご覧ください。

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

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

ステータス	計画されたルートに沿って走行する	説明
`TOKEN_SUCCESSFULLY_APPLIED`	はい	Navigation SDK がルートトークンを適用しました。
`TOKEN_APPLIED_WITH_LOCATION_MISMATCH`	必ずしもそうとは限りません	ルートリクエスト内の場所がルートトークン内の一致する場所から 25 メートル以上離れていたため、Navigation SDK は計画されたルートを再構築できませんでした。`setDestinationsWithToken` の場合、デバイスがルートトークンの出発地から 25 メートル以上離れていたことを意味します。ルートは目的地まで続きますが、Navigation SDK は、ルートトークンのルートオプション（有料道路の回避など）が使用されていることを確認できません。
`TOKEN_IGNORED_OTHER`	必ずしもそうとは限りません	Navigation SDK が別の理由で計画されたルートを再構築できなかった（計画されたルート上の道路が閉鎖されているなど）。ルートは目的地まで続きますが、Navigation SDK は、ルートトークンのルートオプション（有料道路の回避など）が使用されていることを確認できません。
`NO_TOKEN_PROVIDED`	該当なし	ルートリクエストにルートトークンが含まれていませんでした。
`UNKNOWN`	不明	ステータスが不明です。

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

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

getResolvedParameters は RouteTokenResolvedParameters オブジェクトを返します。ルーティングオプションが利用できない場合は null を返します。RouteTokenResolvedParameters には次のメソッドがあります。

getTravelMode: ルートで使用する移動手段（RoutingOptions.TravelMode.DRIVING など）。Navigation SDK は、ルートで一致する値がない移動手段が使用されている場合や、移動手段が利用できない場合にも RoutingOptions.TravelMode.DRIVING を報告します。
getAvoidTolls: ルートで有料道路を避けるかどうか。
getAvoidHighways: ルートで高速道路を避けるかどうか。
getAvoidFerries: ルートでフェリーを避けるかどうか。

例

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

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

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

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

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

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

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