Wenn Sie Ihre Fahrtdaten abrufen, erhält Ihr Backend JSON-Payloads mit Details zum Fortschritt der Fahrt des Fahrers. Sie können diese Nutzlasten parsen, um die Fahrt zu überwachen, Ihre Dispatchsysteme zu aktualisieren und aktuelle Fahrtstatus zu interpretieren, um den nächsten Schritt für den Fahrer zu bestimmen, wenn er vorankommt oder wenn eine Fahrt abgeschlossen ist.
Datennutzlast lesen
Google Maps oder Waze senden die Nutzlasten der Fahrtdaten an die Navigation Connect-Server, wenn der Fahrer die Navigation startet, regelmäßig entlang der Route (standardmäßig alle 60 Sekunden) und wenn der Fahrer am Ziel ankommt. Jede JSON-Nachricht enthält relevante Fahrtdaten, einschließlich der koordinatenbezogenen Daten des Fahrers, der zurückgelegten Strecke und der voraussichtlichen Ankunftszeit (ETA). Da diese Aktualisierungen die aktive Echtzeitroute des Fahrers widerspiegeln, können sie von Routen abweichen, die von Ihrem Backend vorab berechnet wurden (siehe Häufig gestellte Fragen).
Das folgende Codebeispiel zeigt die Nutzlast für Fahrtdaten, wenn ein Fahrer die Navigation für eine Fahrt von King's Cross nach Central St. Giles startet.
{
"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
}
}
Aktive Fahrten im Blick behalten
Prüfen Sie das Statusfeld in jeder Nutzlast, um einen erfolgreichen Start zu bestätigen und den Fortschritt zu überwachen.
| Status | Beschreibung |
|---|---|
NEW |
Die Fahrt wurde erstellt, aber der Fahrer hat die Navigation noch nicht gestartet. |
ENROUTE |
Der Fahrer navigiert aktiv zum Ziel. Anhand dieses Status können Sie bestätigen, dass die Fahrt authentifiziert und erfolgreich gestartet wurde. |
Hinzugefügte Stopps verarbeiten
Fahrer können ihrer Route während der Navigation Zwischenstopps hinzufügen. Wenn das der Fall ist, wird das Feld execution.stopAddedInRoute in der JSON-Daten-Nutzlast von Navigation Connect auf true gesetzt. Die Navigation Connect API verfolgt den Fahrer weiterhin in Richtung des ursprünglichen Ziels. Messwerte wie die voraussichtliche Ankunftszeit, die Entfernung und die Dauer werden erhöht, um die zusätzlichen Stopps zu berücksichtigen.
Das Verhalten beim Hinzufügen von Stopps hängt von der Navigations-App ab und entspricht ihrer Standardfunktionalität:
- Google Maps:Fahrer können ihrer Route mehrere Zwischenstopps hinzufügen.
- Waze:Fahrer können nur einen Zwischenstopp hinzufügen. Wenn ein Fahrer versucht, einen weiteren Stopp hinzuzufügen, fordert Waze ihn auf, eine neue Navigationssitzung zu starten, anstatt den Stopp zur aktuellen Route hinzuzufügen.
Sie müssen Ihre Backend-Eingaben nicht anpassen, um diese Funktion zu unterstützen.
Probleme bei der Authentifizierung und beim Start beheben
Wenn Sie keinen ENROUTE-Status erhalten, ist wahrscheinlich ein Authentifizierungsfehler aufgetreten. Häufige Ursachen sind falsch geschriebene API-Parameter oder ein abgelaufenes Fahrt-Token. Prüfen Sie die Ablaufzeit des Tokens in Ihrer ersten CreateTrip-Antwort.
Wenn sich der Status nicht von NEW zu ENROUTE ändert, verhindert das Gerät des Fahrers möglicherweise die Authentifizierung. Navigation Connect sendet in diesen Fällen keine Fehlermeldungen. Gehen Sie so vor:
- Auf dem Gerät des Fahrers ist Waze Version 5.15.5 oder höher oder Google Maps Version 26.14 oder höher installiert.
- Der Fahrer verwendet Android Auto oder Apple CarPlay nicht.
- Der Fahrer hat eine aktive Internetverbindung.
Verbleibende Routendaten verarbeiten (nur Waze)
Wenn Sie die Meldung der verbleibenden Route beim Erstellen der Fahrt aktiviert haben, erhält Ihr Backend die Polylinie der verbleibenden Route und die Echtzeit-Verkehrslage vom aktuellen Standort des Fahrers bis zum Ziel.
Sie können diese Daten aufnehmen und verarbeiten, um verschiedene Funktionen in Ihren Anwendungen zu nutzen, z. B.:
- Karten für die Live-Standortverfolgung: Rendern Sie die verbleibende Routen-Polylinie auf einer kundenorientierten Web- oder mobilen Karte, um die Fahrt des Fahrers sichtbar zu machen.
- Genauigkeit der voraussichtlichen Ankunftszeit verbessern: Kombinieren Sie die auf die Straße ausgerichtete Polylinie und die Geschwindigkeiten der Verkehrsintervalle, um interne Logistik- oder Lieferankunftsprognosen zu verbessern.
- Routing-Compliance analysieren: Vergleichen Sie die verbleibende Routengeometrie mit den erwarteten Dispositionsrouten, um die Einhaltung durch den Fahrer zu bewerten. Weitere Informationen dazu, warum sich Echtzeit- und vorab berechnete Routen unterscheiden können, finden Sie in den häufig gestellten Fragen.
Navigation Connect gibt die verbleibenden Routendetails im Feld execution.remainingRoute zurück, unabhängig davon, ob Sie eine GetTrip-Anfrage senden oder ereignisgesteuerte Updates über Google Cloud Pub/Sub empfangen. Wie die Nutzlast diese Daten formatiert und strukturiert, hängt jedoch von der verwendeten Abrufmethode ab.
Methode GetTrip
Wenn Sie die Methode GetTrip aufrufen, hängt das Antwortformat für die Polylinie vom Parameter routePolylineFormat ab, den Sie in Ihrer Anfrage angegeben haben. Weitere Informationen finden Sie unter Polylinienformate anpassen.
Bei allen Polylinienformaten gibt Navigation Connect den Verkehr als separate Liste von SpeedReadingInterval-Objekten im Feld execution.remainingRoute.trafficInformation zurück. Diese Objekte ordnen Traffic-Kategorien den Polylinienindexen zu. Dabei werden die folgenden Werte verwendet:
startPolylinePointIndex: Der Startindex des Verkehrsintervalls auf der Polylinie.endPolylinePointIndex: Der Endindex des Traffic-Zeitraums.speed: Die Traffic-Kategorie für dieses Segment:NORMAL,SLOWoderTRAFFIC_JAM.
Google Cloud Pub/Sub-Updates
Wenn Sie Fahrtdaten mit Pub/Sub abrufen, werden bei Aktualisierungen immer verbleibende Routendaten in einem einheitlichen GeoJSON-FeatureCollection im Feld execution.remainingRoute zurückgegeben.
In diesem Format wird die Polyliniengeometrie direkt mit den Verkehrsgeschwindigkeiten kombiniert, sodass keine manuelle Zuordnung von Indexen erforderlich ist.
Beispiel für eine Pub/Sub-Nutzlast
Das folgende Codebeispiel zeigt die GeoJSON-Struktur, die im Feld execution.remainingRoute innerhalb des updatedTrip-Objekts einer Pub/Sub-Nachricht zurückgegeben wird:
{ "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" } } ] }
Nutzlastgröße optimieren
Da Koordinaten-Arrays groß sind, kann die Einbeziehung der verbleibenden Routendaten in Ihre Pub/Sub-Nachrichten die Nutzlastgröße erheblich erhöhen (bis zu 13–14 KB pro Nachricht). Wenn Sie häufige Aktualisierungen erhalten, kann dieses Volumen die Backend-Verarbeitungslast und die Nutzungskosten erhöhen.
Um Ihren Stream zu optimieren, verwenden Sie den Parameter pubsubFieldMask in Ihrem TripConfig-Objekt beim Erstellen des Trips, um umfangreiche Felder auszuschließen. Weitere Informationen finden Sie unter Optionale Konfigurationen.
Endzustände von Fahrten verarbeiten
Wenn ein Fahrer das Ziel erreicht oder die Navigation beendet, gibt die Nutzlast einen der folgenden Endstatus zurück. Mit diesen Status können Sie die entsprechenden nächsten Schritte in Ihrer App auslösen.
| Status | Beschreibung | Empfohlene Maßnahmen |
|---|---|---|
ARRIVED |
Der Fahrer hat das Ziel erreicht. | Sehen Sie sich die remainingDistanceMeters an. Wenn der Fahrer in der Nähe, aber nicht an den genauen Koordinaten geparkt hat, sollten Sie in Ihrer App eine Wegbeschreibung für Fußgänger anbieten. |
SUSPENDED |
Der Fahrer hat die detaillierte Routenführung manuell beendet, bevor er das Ziel erreicht hat. Da Google Maps oder Waze Fahrer nicht automatisch zu Ihrer App zurückleiten, wenn sie eine Sitzung vorzeitig beenden, müssen sie manuell auf die Schaltfläche „Zurück“ tippen. |
Vergleiche execution.location mit dem Ziel, um Fahrern bei der Fahrt zu helfen. Wenn die Entfernung bestehen bleibt, stellen Sie einen Button oder Link bereit, um die Fahrt fortzusetzen oder in den Fußgängermodus zu wechseln. |
FAILED |
Die Verbindung wurde durch einen technischen Fehler unterbrochen. Dies ist der Fall, wenn die App keine Route berechnen kann oder eine Sicherheitswarnung angezeigt wird. Der Fahrer wird möglicherweise weiterhin navigiert, Sie erhalten jedoch keine Updates. | Wechseln Sie in Ihrer App zum manuellen Status-Tracking. |
CLIENT_ERROR |
Dieser Status wird aus einem der folgenden Gründe angezeigt:
|
Wechseln Sie in Ihrer App zum manuellen Status-Tracking. |