ルートデータを処理する

ルートデータを取得すると、ドライバーの乗車状況の詳細を示す 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
  }
}

アクティブな乗車ステータスをモニタリングする

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

ステータス 説明
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 を使用していない。
  • ドライバーがインターネットに接続している。

残りのルートデータを処理する（Waze のみ）

ルート作成時に残りのルートのレポートを有効にしている場合、バックエンドは、運転手の現在地から最終目的地までの残りのルートのポリラインとリアルタイムの交通状況を受け取ります。

このデータを取り込んで処理することで、アプリケーションのさまざまな機能を強化できます。たとえば、次のような機能があります。

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

GetTrip リクエストを送信する場合でも、Google Cloud Pub/Sub を使用してイベント ドリブン アップデートを受信する場合でも、Navigation Connect は 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 パラメータを使用して、重いフィールドを除外します。詳細については、オプションの構成をご覧ください。

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

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

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