Fahrtdaten verarbeiten

Wenn Sie Ihre Fahrtendaten abrufen, erhält Ihr Backend JSON-Nutzlasten mit Details zum Fortschritt der Fahrt des Fahrers. Analysieren Sie diese Nutzlasten, um die Fahrt zu verfolgen, Ihre Dispositions- und Planungssysteme zu aktualisieren und aktuelle Fahrtstatus zu interpretieren, um den nächsten Schritt für den Fahrer zu bestimmen, während er unterwegs ist oder wenn eine Fahrt beendet wird.

Daten-Nutzlast lesen

Google Maps oder Waze sendet die Nutzlasten mit den Fahrtendaten an die Navigation Connect-Server, wenn der Fahrer die Navigation startet, regelmäßig während der Fahrt (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.

Das folgende Codebeispiel zeigt eine Nutzlast mit Fahrtendaten für den Fall, dass 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 Fahrtstatus im Blick behalten

Um einen erfolgreichen Start zu bestätigen und den Fortschritt zu verfolgen, prüfen Sie das Feld „Status“ in jeder Nutzlast.

Status Beschreibung
NEW Die Fahrt wurde erstellt, aber der Fahrer hat die Navigation noch nicht gestartet.
ENROUTE Der Fahrer navigiert aktiv zum Ziel. Mit diesem Status können Sie bestätigen, dass die Fahrt authentifiziert und erfolgreich gestartet wurde.

Hinzugefügte Stopps verarbeiten

Fahrer können während der Navigation Stopps zu ihrer Route hinzufügen. In diesem Fall wird das Feld execution.stopAddedInRoute in der JSON-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 (ETA), die Entfernung und die Dauer werden um die hinzugefügten Stopps erweitert.

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 Stopps hinzufügen.
  • Waze:Fahrer können nur einen Stopp hinzufügen. Wenn ein Fahrer versucht, einen weiteren Stopp hinzuzufügen, fordert Waze ihn auf, stattdessen eine neue Navigationssitzung zu starten.

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 Status ENROUTE 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 in 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 nicht Android Auto oder Apple CarPlay.
  • Der Fahrer hat eine aktive Internetverbindung.

Verbleibende Routendaten verarbeiten (nur Waze)

Wenn Sie die Berichterstellung für die verbleibende Route bei der Erstellung der Fahrt aktiviert haben, erhält Ihr Backend die aktive Routenpolyline und 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, darunter die folgenden Beispiele:

  • Karten für die Live-Verfolgung: Rendern Sie die verbleibende Routenpolyline auf einer für Kunden sichtbaren Web- oder mobilen Karte, um Einblicke in die Fahrt des Fahrers zu geben.
  • Genauigkeit der geschätzten Ankunftszeit verbessern: Kombinieren Sie die an die Straße angepasste Polyline und die Geschwindigkeiten der Verkehrs intervalle, um die interne Logistik oder die Vorhersagen zur Ankunft von Lieferungen zu verbessern.
  • Routing-Compliance analysieren: Vergleichen Sie die Geometrie der verbleibenden Route mit den erwarteten Dispositionsrouten, um die Einhaltung durch den Fahrer zu bewerten.

Navigation Connect gibt die Details der verbleibenden Route im Feld execution.remainingRoute zurück, unabhängig davon, ob Sie eine GetTrip-Anfrage senden oder ereignisgesteuerte Aktualisierungen über Google Cloud Pub/Sub erhalten. Wie die Nutzlast diese Daten formatiert und strukturiert, hängt jedoch von der verwendeten Abrufmethode ab.

GetTrip-Methode

Wenn Sie die Methode GetTrip aufrufen, hängt das Antwortformat für die Polyline vom Parameter routePolylineFormat ab, den Sie in Ihrer Anfrage angegeben haben. Weitere Informationen finden Sie unter Polyline-Formate anpassen.

Für alle Polyline-Formate gibt Navigation Connect den Traffic als separate Liste von SpeedReadingInterval-Objekten im Feld execution.remainingRoute.trafficInformation zurück. Diese Objekte ordnen Traffic-Kategorien den Polyline-Indizes zu. Dabei werden die folgenden Werte verwendet:

  • startPolylinePointIndex: Der Startindex des Verkehrsintervalls auf der Polyline.
  • endPolylinePointIndex: Der Endindex des Verkehrsintervalls.
  • speed: Die Traffic-Kategorie für dieses Segment: NORMAL, SLOW oder TRAFFIC_JAM.

Google Cloud Pub/Sub-Aktualisierungen

Wenn Sie Fahrtendaten mit Pub/Sub abrufen, geben Aktualisierungen immer Daten zur verbleibenden Route in einer einheitlichen GeoJSON FeatureCollection im execution.remainingRoute Feld zurück.

In diesem Format werden die Polyline-Geometrie und die Verkehrsgeschwindigkeiten direkt kombiniert, sodass keine manuelle Zuordnung von Indizes 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 das Einbeziehen von Daten zur verbleibenden Route in Ihre Pub/Sub-Nachrichten die Nutzlastgröße erheblich erhöhen (bis zu 13–14 KB pro Nachricht). Wenn Sie häufig Aktualisierungen erhalten, kann dieses Volumen die Backend-Verarbeitungslast und die Nutzungskosten erhöhen.

Verwenden Sie zur Optimierung Ihres Streams den Parameter pubsubFieldMask in Ihrem TripConfig-Objekt während der Fahrtenerstellung, um große Felder auszuschließen. Weitere Informationen finden Sie unter Optionale Konfigurationen.

Endstatus der Fahrt 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. Prüfen Sie remainingDistanceMeters. Wenn der Fahrer in der Nähe, aber nicht an den genauen Koordinaten geparkt hat , können 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ückleitet, wenn sie eine Sitzung vorzeitig beenden, muss der Fahrer manuell auf die Schaltfläche „Zurück“ tippen. 		Vergleichen Sie execution.location mit dem Ziel, um Fahrern zu helfen, ihre Fahrt abzuschließen. Wenn noch eine Strecke zurückzulegen ist, bieten Sie eine Schaltfläche oder einen Link an, um die Fahrt fortzusetzen oder in den Fußgängermodus zu wechseln.
FAILED Ein technischer Fehler hat die Verbindung unterbrochen. Dies tritt auf, wenn die App keine Route berechnen kann oder eine Sicherheitswarnung angezeigt wird. Der Fahrer navigiert möglicherweise noch, aber Sie erhalten keine Aktualisierungen. Wechseln Sie in Ihrer App zur manuellen Statusverfolgung.
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 Fahrt-Token für eine Fahrt mit einem anderen Ziel wieder.
  • Der Fahrer befindet sich während der Fahrt an einem beliebigen Punkt in den USA, aber in Ihrer App ist die Datenfreigabe in den USA nicht aktiviert, als Sie Ihre App bei der Einrichtung bestätigt haben.
 Wechseln Sie in Ihrer App zur manuellen Statusverfolgung.