乗車データを取得すると、ドライバーの乗車状況の詳細を示す JSON ペイロードがバックエンドに送信されます。これらのペイロードを解析して、ルートをモニタリングし、配車システムを更新し、現在のルートのステータスを解釈して、ルートの進行中または完了時にドライバーの次のステップを判断します。
データ ペイロードを読み取る
ドライバーがナビを開始したとき、ルートに沿って定期的に（デフォルトでは 60 秒ごと）、ドライバーが目的地に到着したときに、Google マップまたは Waze がルートデータのペイロードを 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 を使用していない。
- ドライバーがインターネットに接続している。
残りのルートデータを処理する（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 パラメータを使用して、重いフィールドを除外します。詳細については、省略可能な構成をご覧ください。
ルートの逸脱を処理する（Waze のみ）
トリップの作成時にルート逸脱レポートを有効にしている場合、ドライバーがルートから外れると、API はルート逸脱メタデータを返します。このデータには次の方法でアクセスできます。
- オンデマンド:
GetTripメソッドを呼び出します。サーバーは、最後に認識された偏差状態を保持します。 - リアルタイム: Google Cloud Pub/Sub に登録します。サービスは、検出から 5 秒以内に既存の
updated_tripイベントを使用して偏差の更新を公開します。
偏差ペイロードを読み取る
last_route_deviation オブジェクトは、イベントの分析に役立つ次のメタデータを提供します。
| フィールド | タイプ | 説明 |
|---|---|---|
location |
LatLng |
クライアント デバイスが偏差を記録した緯度と経度の座標。 |
source |
TriggerSource |
逸脱の理由。これを使用して、ドライバーが予期しない行動をとったか、システム ガイダンスに従ったかを判断します。
|
client_timestamp |
Timestamp |
クライアント デバイスが偏差を検出した時刻。 |
server_timestamp |
Timestamp |
サーバーが偏差の更新を処理した時刻。 |
乗車終了状態を処理する
ドライバーが目的地に到着するか、ナビゲーションを停止すると、ペイロードは次のいずれかの終了状態を返します。これらのステータスを使用して、アプリで適切な次のステップをトリガーします。
| ステータス | 説明 | 推奨される対処方法 |
|---|---|---|
ARRIVED |
ドライバーが目的地に到着しました。 | remainingDistanceMeters を確認します。ドライバーが近くに駐車したが、正確な座標には駐車していない場合は、アプリで徒歩での行き方を案内することを検討してください。 |
SUSPENDED |
運転手が目的地に到着する前に、ターンバイターン方式ナビを手動で終了した。 Google マップや Waze は、セッションを途中で終了したドライバーを自動的にアプリに戻さないため、ドライバーは手動で戻るボタンをタップする必要があります。 |
ドライバーが目的地に到着できるよう、execution.location と目的地を比較します。距離が残っている場合は、乗車を再開するか、徒歩モードに切り替えるためのボタンまたはリンクを提供します。 |
FAILED |
技術的なエラーにより接続が中断されました。これは、アプリがルートを計算できない場合や、安全に関する警告が表示された場合に発生します。ドライバーは引き続きナビゲーションを行っている可能性がありますが、更新は届きません。 | アプリで手動ステータス トラッキングにフォールバックします。 |
CLIENT_ERROR |
このステータスは、次のいずれかの理由で表示されます。
|
アプリで手動ステータス トラッキングにフォールバックします。 |