Fahrtdaten verarbeiten

Wenn Sie Ihre Fahrtdaten abrufen, erhält Ihr Backend JSON-Nutzlasten mit Details zum Fortschritt der Fahrt. Diese Nutzlasten können Sie parsen, um die Fahrt zu überwachen, Ihre Dispositionssysteme zu aktualisieren und den aktuellen Fahrtstatus zu interpretieren, um den nächsten Schritt für den Fahrer während der Fahrt oder nach Abschluss einer Fahrt zu bestimmen.

Datennutzlast lesen

Google Maps oder Waze sendet 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 an die Straße angepassten Koordinaten des Fahrers, der zurückgelegten Strecke und der voraussichtlichen Ankunftszeit. Da diese Aktualisierungen die aktive Echtzeitroute des Fahrers widerspiegeln, können sie von den Routen abweichen, die von Ihrem Backend vorab berechnet wurden (siehe FAQ).

Das folgende Codebeispiel zeigt eine Nutzlast mit 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
  }
}

Status aktiver Fahrten überwachen

Wenn Sie einen erfolgreichen Start bestätigen und den Fortschritt überwachen möchten, werten Sie das Feld state in jeder Nutzlast aus.

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 prüfen, ob die Fahrt erfolgreich authentifiziert und gestartet wurde.

Hinzugefügte Haltestellen verarbeiten

Fahrer können ihrer Route während der Navigation Zwischenstopps hinzufügen. Wenn ja, setzt Navigation Connect das Feld execution.stopAddedInRoute in der JSON-Datennutzlast auf true. Die Navigation Connect API verfolgt den Fahrer weiterhin zum ursprünglichen Ziel. Messwerte wie die voraussichtliche Ankunftszeit, die Entfernung und die Dauer werden entsprechend den hinzugefügten Zwischenstopps erhöht.

Das Verhalten beim Hinzufügen von Zwischenstopps hängt von der Navigations-App ab und entspricht deren Standardfunktionen:

  • 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 Zwischenstopp hinzuzufügen, wird er von Waze aufgefordert, eine neue Navigationssitzung zu starten, anstatt den Zwischenstopp der 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 den Status ENROUTE nicht erhalten, ist wahrscheinlich ein Authentifizierungsfehler aufgetreten. Häufige Ursachen sind falsch geschriebene API-Parameter oder ein abgelaufenes Fahrttoken. 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:

  • Der Fahrer hat Waze ab Version 5.15.5 oder Google Maps ab Version 26.14 installiert.
  • Der Fahrer verwendet weder Android Auto noch Apple CarPlay.
  • Der Fahrer hat eine aktive Internetverbindung.

Verbleibende Routendaten verarbeiten

Wenn Sie die Berichterstellung für die verbleibende Route bei der Erstellung der Fahrt aktiviert haben, erhält Ihr Backend die Polylinie für die verbleibende Route und die Echtzeit-Verkehrslage vom aktuellen Standort des Fahrers bis zum endgültigen Ziel. Fahrer benötigen Waze-Version 5.20.0.2 oder höher für Android, 5.20.0.1 oder höher für iOS oder Google Maps für Android-Version 26.27 oder höher.

Sie können diese Daten aufnehmen und verarbeiten, um mehrere Funktionen in Ihren Anwendungen zu unterstützen, darunter die folgenden Beispiele:

  • Karten für das Live-Tracking: Rendern Sie die Polylinie der verbleibenden Route auf einer kundenorientierten Web- oder Mobilkarte, um die Fahrt des Fahrers sichtbar zu machen.
  • Genauigkeit der voraussichtlichen Ankunftszeit verbessern: Kombinieren Sie die an die Straße angepasste Polylinie und die Geschwindigkeiten der Verkehrsintervalle, um die interne Logistik oder die Vorhersagen für die Ankunftszeit von Lieferungen zu verbessern.
  • Routen-Compliance analysieren: Vergleichen Sie die verbleibende Routengeometrie mit den erwarteten Versandrouten, um die Einhaltung durch den Fahrer zu beurteilen. Weitere Informationen dazu, warum Echtzeit- und vorab berechnete Routen voneinander abweichen können, finden Sie in den FAQs.

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 erhalten. 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 die Verkehrsinformationen als separate Liste von SpeedReadingInterval-Objekten im Feld execution.remainingRoute.trafficInformation zurück. Diese Objekte ordnen Verkehrskategorien den Polylinien-Indizes mit den folgenden Werten zu:

Google Cloud Pub/Sub-Updates

Wenn Sie Fahrtdaten mit Pub/Sub abrufen, werden bei Aktualisierungen immer die verbleibenden 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 ansehen

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 Koordinatenarrays groß sind, kann das Einbeziehen 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 Verarbeitungslast im Backend und die Nutzungskosten erhöhen.

Wenn Sie Ihren Stream optimieren möchten, verwenden Sie beim Erstellen der Fahrt den Parameter pubsubFieldMask im Objekt TripConfig, um große Felder auszuschließen. Weitere Informationen finden Sie unter Optionale Konfigurationen.

Routenabweichungen verarbeiten (nur Waze)

Fahrer benötigen die Waze-Version 5.22 oder höher.

Wenn Sie die Berichterstellung für Routenabweichungen bei der Erstellung der Fahrt aktiviert haben, gibt die API Metadaten zur Routenabweichung zurück, wenn ein Fahrer von der Route abweicht. Sie können auf diese Daten folgendermaßen zugreifen:

  • On-Demand: Rufen Sie die Methode GetTrip auf. Der Server speichert den letzten bekannten Abweichungsstatus.
  • Echtzeit: Abonnieren Sie Google Cloud Pub/Sub. Der Dienst veröffentlicht Abweichungsaktualisierungen mit dem vorhandenen updated_trip-Ereignis innerhalb von 5 Sekunden nach der Erkennung.

Abweichungs-Nutzlast lesen

Das Objekt last_route_deviation stellt die folgenden Metadaten bereit, mit denen Sie das Ereignis analysieren können.

Feld Typ Beschreibung
location LatLng Die Breiten- und Längengradkoordinaten, an denen das Clientgerät die Abweichung aufgezeichnet hat.
source TriggerSource Der Grund für die Abweichung. Anhand dieser Informationen können Sie feststellen, ob die Fahrerin oder der Fahrer eine unerwartete Aktion ausgeführt oder die Systemanweisungen befolgt hat:
  • DRIVER_INITIATED_REROUTE: Der Fahrer hat eine aktive Entscheidung getroffen (z. B. falsch abgebogen oder manuell eine neue Route ausgewählt).
  • SYSTEM_INITIATED_REROUTE: Die Navigations-App hat eine neue Route berechnet (z. B. aufgrund einer geänderten Verkehrslage oder Straßensperrungen).
client_timestamp Timestamp Der Zeitpunkt, zu dem das Clientgerät die Abweichung erkannt hat.
server_timestamp Timestamp Der Zeitpunkt, zu dem der Server die Aktualisierung der Abweichung verarbeitet hat.

Endstatus von Fahrten verarbeiten

Wenn ein Fahrer das Ziel erreicht oder die Navigation beendet, gibt die Nutzlast einen der folgenden Endstatus zurück. Verwenden Sie diese Status, um die entsprechenden nächsten Schritte in Ihrer App auszulösen.

Status Beschreibung Empfohlene Maßnahmen
ARRIVED Der Fahrer hat das Ziel erreicht. Beachten Sie die remainingDistanceMeters. Wenn der Fahrer in der Nähe, aber nicht an den genauen Koordinaten geparkt hat, können Sie in Ihrer App eine Fußgängerroute anbieten.
SUSPENDED Der Fahrer hat die detaillierte Routenführung vor Erreichen des Ziels manuell beendet.
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.
Vergleichen Sie execution.location mit dem Ziel, um Fahrern zu helfen, ihr Ziel zu erreichen. Wenn noch eine Strecke zurückzulegen ist, stellen Sie eine Schaltfläche oder einen Link bereit, um die Fahrt fortzusetzen oder in den Fußgängermodus zu wechseln.
FAILED Die Verbindung wurde durch einen technischen Fehler unterbrochen. Das ist der Fall, wenn die App keine Route berechnen kann oder ein Sicherheitshinweis angezeigt wird. Der Fahrer navigiert möglicherweise noch, aber Sie erhalten keine Updates mehr. Wechseln Sie in Ihrer App zum manuellen Status-Tracking.
CLIENT_ERROR Dieser Status wird aus einem der folgenden Gründe angezeigt:
  • Der Fahrer widerruft die Einwilligung.
  • Der Fahrer verwendet eine nicht unterstützte Plattform wie Android Auto oder Apple CarPlay.
  • Ihre App verwendet ein Fahrttoken für mehrere Fahrten. Beispielsweise werden in Navigation Connect Anfragen abgelehnt, mit denen das Ziel einer Fahrt geändert oder eine abgeschlossene Fahrt aktualisiert werden soll.
  • Der Fahrer befindet sich während der Fahrt in den USA, aber Sie haben die Datenweitergabe in den USA nicht aktiviert, als Sie Ihre App bei der Einrichtung bestätigt haben.
Wechseln Sie in Ihrer App zum manuellen Status-Tracking.