ルートデータを処理する

ルートデータを取得すると、バックエンドはドライバーのルートの進行状況を詳しく示す JSON ペイロードを受け取ります。これらのペイロードを解析して、ルートのモニタリング、配車システムの更新、現在のルート ステータスの解釈を行い、ドライバーの次のステップを決定します。

データ ペイロードを読み取る

Google マップまたは Waze は、ドライバーがナビを開始したとき、ルートに沿って定期的に(デフォルトでは 60 秒ごと)、ドライバーが目的地に到着したときに、ルートデータのペイロードを Navigation Connect サーバーに送信します。各 JSON メッセージには、ドライバーの道路にスナップされた座標、移動距離、予定到着時刻(ETA)など、関連するルートデータが含まれています。これらの更新はドライバーのアクティブなリアルタイム ルートを反映しているため、バックエンドで事前に計算されたルートとは異なる場合があります(よくある質問をご覧ください)。

次のコードサンプルは、ドライバーがキングス クロスからセントラル セント ジャイルズへのルートのナビゲーションを開始したときのルートデータ ペイロードを示しています。

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

アクティブなトリップのステータスをモニタリングする

正常に開始されたことを確認し、進行状況をモニタリングするには、すべてのペイロードの state フィールドを評価します。

ステータス 説明
NEW トリップは作成されていますが、ドライバーはまだナビゲーションを開始していません。
ENROUTE ドライバーが目的地に向かってナビゲーションを使用している。このステータスを使用して、トリップが正常に認証され、開始されたことを確認します。

追加された経由地を処理する

ドライバーは、ナビゲーション中にルートに経由地を追加できます。その場合、Navigation Connect は JSON データ ペイロードの execution.stopAddedInRoute フィールドを true に設定します。Navigation Connect API は、元の目的地に向かうドライバーの追跡を継続します。予定到着時刻(ETA)、距離、所要時間などの指標は、追加された停車地を含めるように増加します。

経由地を追加する際の動作は、ナビゲーション アプリによって異なり、その標準機能に準じます。

  • Google マップ: ドライバーはルートに複数の経由地を追加できます。
  • Waze: ドライバーが追加できる経由地は 1 つのみです。ドライバーが別の経由地を追加しようとすると、Waze は現在のルートに経由地を追加するのではなく、新しいナビゲーション セッションを開始するよう促します。

この機能をサポートするために、バックエンドの入力を調整する必要はありません。

認証と起動に関する問題のトラブルシューティング

ENROUTE ステータスが返されない場合は、認証エラーが発生した可能性があります。一般的な原因としては、API パラメータのスペルミスや、トリップ トークンの有効期限切れなどが挙げられます。最初の CreateTrip レスポンスでトークンの有効期限を確認します。

ステータスが NEW から ENROUTE に変わらない場合は、ドライバーのデバイスが認証を妨げている可能性があります。Navigation Connect は、このような場合にエラー メッセージを送信しません。以下を確認します。

  • ドライバーが Waze バージョン 5.15.5 以降、または Google マップ バージョン 26.14 以降をインストールしている。
  • ドライバーが Android Auto または Apple CarPlay を使用していない。
  • ドライバーがインターネットに接続している。

残りのルートデータを処理する

旅程の作成時に残りのルートの報告を有効にしている場合、バックエンドは、ドライバーの現在地から最終目的地までの残りのルートのポリラインとリアルタイムの交通状況を受信します。ドライバーは、Android の場合は Waze バージョン 5.20.0.2 以降、iOS の場合は 5.20.0.1 以降、または Android の場合は Google マップ バージョン 26.27 以降が必要です。

このデータを取り込んで処理することで、アプリケーションのいくつかの機能(以下に例を示します)を強化できます。

  • ライブ トラッキング マップを強化する: 顧客向けのウェブマップまたはモバイルマップに残りのルートのポリラインをレンダリングして、ドライバーの移動状況を可視化します。
  • 到着予定時刻の精度を向上させる: 道路にスナップされたポリラインと交通区間の速度を組み合わせて、社内物流や配送の到着予測を改善します。
  • ルートのコンプライアンスを分析する: 残りのルート ジオメトリを、想定される配送ルートと比較して、ドライバーのコンプライアンスを評価します(リアルタイム ルートと事前計算ルートが異なる理由の詳細については、よくある質問をご覧ください)。

Navigation Connect は、GetTrip リクエストを送信するか、Google Cloud Pub/Sub を使用してイベント ドリブン アップデートを受信するかに関係なく、execution.remainingRoute フィールドに残りのルートの詳細を返します。ただし、ペイロードがこのデータをフォーマットして構造化する方法は、使用する取得方法によって異なります。

GetTrip メソッド

GetTrip メソッドを呼び出すと、ポリラインのレスポンス形式は、リクエストで指定した routePolylineFormat パラメータによって異なります。詳細については、ポリライン形式をカスタマイズするをご覧ください。

すべてのポリライン形式で、Navigation Connect は execution.remainingRoute.trafficInformation フィールドに SpeedReadingInterval オブジェクトの個別のリストとして交通情報を返します。これらのオブジェクトは、次の値を使用して、トラフィック カテゴリをポリライン インデックスにマッピングします。

  • startPolylinePointIndex: ポリライン上の交通状況の間隔の開始インデックス。
  • endPolylinePointIndex: トラフィック間隔の終了インデックス。
  • speed: このセグメントのトラフィック カテゴリ(NORMAL、SLOW、TRAFFIC_JAM)。

Google Cloud Pub/Sub の更新

Pub/Sub でルートデータを取得すると、更新では常に、execution.remainingRoute フィールドの統合された GeoJSON FeatureCollection で残りのルートデータが返されます。

この形式では、ポリライン ジオメトリと交通速度が直接結合されるため、インデックスを手動でマッピングする必要がありません。

Pub/Sub ペイロードの例を確認する

次のコードサンプルは、Pub/Sub メッセージの updatedTrip オブジェクト内の execution.remainingRoute フィールドで返される GeoJSON 構造を示しています。

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}
    

ペイロード サイズを最適化する

座標配列は大きいため、Pub/Sub メッセージに残りのルートデータを含めると、ペイロード サイズが大幅に増加する可能性があります(メッセージあたり最大 13 ~ 14 KB)。更新が頻繁に発生すると、このボリュームによってバックエンドの処理負荷と使用コストが増加する可能性があります。

ストリームを最適化するには、旅程の作成時に TripConfig オブジェクトの pubsubFieldMask パラメータを使用して、重いフィールドを除外します。詳細については、オプションの構成をご覧ください。

ルート逸脱を処理する(Waze のみ)

ドライバーは Waze バージョン 5.22 以降が必要です。

旅程の作成時にルート逸脱レポートを有効にしている場合、ドライバーがルートを外れると、API はルート逸脱メタデータを返します。このデータには次の方法でアクセスできます。

  • オンデマンド: GetTrip メソッドを呼び出します。サーバーは、最後に確認された偏差状態を保持します。
  • リアルタイム: Google Cloud Pub/Sub に登録します。このサービスは、検出から 5 秒以内に既存の updated_trip イベントを使用して偏差の更新を公開します。

偏差ペイロードを読み取る

last_route_deviation オブジェクトは、イベントの分析に役立つ次のメタデータを提供します。

フィールド タイプ 説明
location LatLng クライアント デバイスが偏差を記録した緯度と経度の座標。
source TriggerSource 逸脱の理由。これを使用して、ドライバーが予期しない行動をとったのか、システム ガイダンスに従ったのかを判断します。
  • DRIVER_INITIATED_REROUTE: ドライバーが積極的な選択を行った(例: 間違った方向に曲がった、手動で新しい経路を選択した)。
  • SYSTEM_INITIATED_REROUTE: ナビゲーション アプリが新しいルートを計算しました(交通状況の変化や通行止めなど)。
client_timestamp Timestamp クライアント デバイスが偏差を検出した時刻。
server_timestamp Timestamp サーバーが偏差の更新を処理した時刻。

ルートの終了状態を処理する

ドライバーが目的地に到着するか、ナビゲーションを停止すると、ペイロードは次のいずれかの終了状態を返します。これらのステータスを使用して、アプリで適切な次のステップをトリガーします。

ステータス 説明 推奨される対処方法
ARRIVED ドライバーが目的地に到着した。 remainingDistanceMeters を確認します。ドライバーが近くに駐車したものの、正確な座標に駐車していない場合は、アプリで徒歩経路を提供することを検討してください。
SUSPENDED ドライバーが目的地に到着する前に、ターンバイターン方式のナビを手動で終了した。
Google マップや Waze では、ドライバーがセッションを早期に終了しても、ドライバーをアプリに自動的に戻すことはありません。ドライバーは手動で戻るボタンをタップする必要があります。
ドライバーが目的地に到着できるよう、execution.location と目的地を比較します。距離が残っている場合は、ルートを再開するか、徒歩モードに切り替えるためのボタンまたはリンクを表示します。
FAILED 技術的なエラーにより接続が中断されました。これは、アプリがルートを計算できない場合や、安全に関する警告が表示された場合に発生します。ドライバーは引き続きナビを使用している可能性がありますが、更新情報は届きません。 アプリで手動ステータス トラッキングにフォールバックします。
CLIENT_ERROR このステータスは、次のいずれかの理由で表示されます。
  • ドライバーが同意を取り消した。
  • ドライバーが、Android Auto や Apple CarPlay などのサポートされていないプラットフォームを使用している。
  • アプリが、別々のトリップでトリップ トークンを再利用している。たとえば、Navigation Connect は、ルートの目的地を変更するリクエストや、完了したルートを更新するリクエストを拒否します。
  • ドライバーがルートの途中で米国内にいるが、セットアップ中にアプリを検証したときに、アプリで米国内でのデータ共有が有効になっていない。
アプリで手動ステータス トラッキングにフォールバックします。