ルートを計画する

アプリでユーザーに提供するルートを計画する必要がある場合もあります。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 に渡します。手順は次のとおりです。

ステップ 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 を DRIVING または TWO_WHEELER に設定します。
   • routing_preference を TRAFFIC_AWARE または TRAFFIC_AWARE_OPTIMAL に設定します。
   • Via ウェイポイントは使用しないでください

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

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

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

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

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

2. Navigator.setDestinations メソッドを使用して ルートトークンを Navigation SDK に渡す。ルートトークンの作成時に使用した同じ目的地のウェイポイントを指定します。

   setDestinations(List destinations, CustomRoutesOptions customRoutesOptions, DisplayOptions displayOptions);

   次に例を示します。

   CustomRoutesOptions customRoutesOptions =
         CustomRoutesOptions.builder()
         .setRouteToken(routeToken)
         .setTravelMode(TravelMode.DRIVING)
         .build();

注: 同じルートをもう一度移動する必要がある場合は、新しいルートトークンをリクエストしてください。

Navigator.setDestinations メソッドはリクエストのステータスを返します。車両の現在地から指定された目的地へのルートが見つかった場合は、RouteStatus.OK を返します。

このメソッドの詳細については、Navigator.setDestinations をご覧ください。

例

次のコードサンプルは、ルートトークンを使用して計画ルートを指定する方法を示しています。

    ArrayList <Waypoint> destinations = Lists.newArrayList();
    Waypoint waypoint1 =
       Waypoint.builder()
          .setLatLng(10, 20)
          .setTitle("title")
          .setVehicleStopover(true)
          .build();
    destinations.add(waypoint1);
    Waypoint waypoint2 =
       Waypoint.builder()
          .setPlaceId("ChIJYV-J-ziuEmsRIMyoFaMedU4")
          .setTitle("title")
          .setVehicleStopover(true)
           .build()
    destinations.add(waypoint2);

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

    CustomRoutesOptions customRoutesOptions =
       CustomRoutesOptions.builder()
          .setRouteToken(routeToken)
          .setTravelMode(TravelMode.DRIVING)
          .build();

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

    // Existing flow for requesting routes.
    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions);

    // Or with display options.
    DisplayOptions displayOptions = new DisplayOptions();

    ListenableResultFuture<RouteStatus> routeStatusFuture =
        navigator.setDestinations(destinations, customRoutesOptions, displayOptions);

ルートトークンと Navigation SDK の相互作用

Navigation SDK によって生成されたルートと、ルートトークンの計画ルートの相互作用は次のとおりです。

• 以前に設定されたデスティネーションをオーバーライドします。

• 車の開始位置を使用します。

• 道路状況や交通状況に合わせて調整されます。計画したルートを正確にたどらない理由をご覧ください。

• 次のルーティング関連のオプションは不要として無視されます。

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• フォロー数:

  • ウェイポイント関連のオプション（道路の側面の設定など）。

  • ルートの目標。Navigation SDK が返されたルートを調整する必要がある場合は、ルートトークンをリクエストするときに指定したルート目標が使用されます。このため、Routes API で指定したのと同じ waypoint 関連のオプションを使用する必要があります。