Obsługa danych o podróży

Gdy pobierzesz dane o podróży, Twój backend otrzyma ładunki JSON zawierające szczegółowe informacje o postępach kierowcy w podróży. Analizuj te ładunki, aby monitorować przejazd, aktualizować systemy wysyłkowe i interpretować bieżące stany przejazdu, aby określić następny krok dla kierowcy w trakcie przejazdu lub po jego zakończeniu.

Odczytywanie ładunku danych

Mapy Google lub Waze wysyłają pakiety danych o podróży na serwery Navigation Connect, gdy kierowca rozpoczyna nawigację, okresowo w trakcie podróży (domyślnie co 60 sekund) oraz gdy dociera do miejsca docelowego. Każda wiadomość JSON zawiera odpowiednie dane o podróży, w tym współrzędne kierowcy połączone z drogą, pokonany dystans i szacowany czas dotarcia na miejsce (ETA). Ponieważ te aktualizacje odzwierciedlają aktywną trasę kierowcy w czasie rzeczywistym, mogą się różnić od tras wstępnie obliczonych przez Twój backend (patrz FAQ).

Poniższy przykładowy kod pokazuje ładunek danych o podróży, gdy kierowca rozpoczyna nawigację podczas przejazdu z King's Cross do Central St. Giles.

{
  "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
  }
}

Monitorowanie stanu aktywnych przejazdów

Aby potwierdzić, że uruchomienie się powiodło, i monitorować postępy, sprawdź pole state w każdym ładunku.

Stan Opis
NEW Przejazd został utworzony, ale kierowca nie rozpoczął jeszcze nawigacji.
ENROUTE Kierowca aktywnie nawiguje do miejsca docelowego. Użyj tego stanu, aby potwierdzić, że przejazd został uwierzytelniony i rozpoczął się prawidłowo.

Obsługa dodanych przystanków

Kierowcy mogą dodawać przystanki do trasy podczas nawigacji. Jeśli tak jest, Navigation Connect ustawia pole execution.stopAddedInRoute na true w ładunku danych JSON. Interfejs Navigation Connect API nadal śledzi kierowcę w kierunku pierwotnego miejsca docelowego. Dane takie jak szacowany czas dotarcia na miejsce, odległość i czas trwania zwiększają się, aby uwzględnić dodane przystanki.

Sposób dodawania przystanków zależy od aplikacji do nawigacji i jest zgodny z jej standardową funkcjonalnością:

  • Mapy Google: kierowcy mogą dodawać do trasy wiele przystanków.
  • Waze: kierowcy mogą dodać tylko 1 przystanek. Jeśli kierowca spróbuje dodać kolejny przystanek, Waze poprosi go o rozpoczęcie nowej sesji nawigacji zamiast dodawania przystanku do bieżącej trasy.

Aby obsługiwać tę funkcję, nie musisz dostosowywać danych wejściowych backendu.

Rozwiązywanie problemów z uwierzytelnianiem i uruchamianiem

Jeśli nie otrzymasz stanu ENROUTE, prawdopodobnie wystąpił błąd uwierzytelniania. Typowe przyczyny to m.in. błędnie napisane parametry interfejsu API lub wygaśnięcie tokena podróży. Sprawdź czas wygaśnięcia tokena w początkowej odpowiedzi CreateTrip.

Jeśli stan nie zmieni się z NEW na ENROUTE, urządzenie kierowcy może uniemożliwiać uwierzytelnianie. W takich przypadkach Navigation Connect nie wysyła komunikatów o błędach. Sprawdź te kwestie:

  • Kierowca ma zainstalowaną aplikację Waze w wersji 5.15.5 lub nowszej albo Mapy Google w wersji 26.14 lub nowszej.
  • Kierowca nie korzysta z Androida Auto ani Apple CarPlay.
  • Kierowca ma aktywne połączenie z internetem.

Obsługa pozostałych danych trasy (tylko Waze)

Jeśli podczas tworzenia przejazdu włączysz raportowanie pozostałej części trasy, Twój backend będzie otrzymywać polilinię pozostałej części trasy i informacje o natężeniu ruchu w czasie rzeczywistym od bieżącej lokalizacji kierowcy do miejsca docelowego.

Możesz pozyskiwać i przetwarzać te dane, aby korzystać z różnych funkcji w aplikacjach, np. z tych:

  • Zasilanie map śledzenia na żywo: renderowanie pozostałej części trasy na mapie internetowej lub mobilnej widocznej dla klienta, aby zapewnić wgląd w podróż kierowcy.
  • Zwiększanie dokładności szacowanego czasu dotarcia na miejsce: połączenie polilinii dopasowanej do drogi i prędkości w interwałach ruchu, aby poprawić wewnętrzną logistykę lub prognozy czasu dotarcia dostawy.
  • Analizowanie zgodności z wyznaczaniem trasy: porównaj pozostałą geometrię trasy z oczekiwanymi trasami przejazdu, aby ocenić, czy kierowca się do nich stosuje (szczegółowe informacje o tym, dlaczego trasy w czasie rzeczywistym i wcześniej obliczone mogą się różnić, znajdziesz w sekcji z odpowiedziami na najczęstsze pytania).

Navigation Connect zwraca pozostałe szczegóły trasy w polu execution.remainingRoute, niezależnie od tego, czy wysyłasz żądanie GetTrip, czy otrzymujesz aktualizacje oparte na zdarzeniach za pomocą Google Cloud Pub/Sub. Sposób formatowania i strukturyzowania tych danych w ładunku zależy jednak od używanej metody pobierania.

GetTrip metoda

Gdy wywołasz metodę GetTrip, format odpowiedzi dla linii łamanej zależy od parametru routePolylineFormat określonego w żądaniu. Więcej informacji znajdziesz w sekcji Dostosowywanie formatów linii łamanych.

W przypadku wszystkich formatów linii łamanych Navigation Connect zwraca informacje o ruchu jako osobną listę obiektów SpeedReadingInterval w polu execution.remainingRoute.trafficInformation. Te obiekty mapują kategorie ruchu na indeksy linii łamanych za pomocą tych wartości:

Aktualizacje Google Cloud Pub/Sub

Gdy pobierasz dane o podróży za pomocą Pub/Sub, aktualizacje zawsze zwracają pozostałe dane trasy w ujednoliconym formacie GeoJSONFeatureCollection w poluexecution.remainingRoute.

Ten format łączy geometrię linii łamanej bezpośrednio z prędkościami ruchu, eliminując potrzebę ręcznego mapowania indeksów.

Zobacz przykładowy ładunek Pub/Sub

Poniższy przykładowy kod pokazuje strukturę GeoJSON zwróconą w polu execution.remainingRoute w obiekcie updatedTrip wiadomości Pub/Sub:

{
  "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"
      }
    }
  ]
}

Optymalizowanie rozmiaru ładunku

Tablice współrzędnych są duże, więc uwzględnianie w wiadomościach Pub/Sub pozostałych danych o trasie może znacznie zwiększyć rozmiar ładunku (nawet do 13–14 KB na wiadomość). Jeśli otrzymujesz aktualizacje o wysokiej częstotliwości, ta ilość może zwiększyć obciążenie przetwarzania backendu i koszty użytkowania.

Aby zoptymalizować strumień, podczas tworzenia przejazdu użyj parametru pubsubFieldMask w obiekcie TripConfig , aby wykluczyć duże pola. Więcej informacji znajdziesz w sekcji Opcjonalne konfiguracje.

Obsługa odchyleń od trasy (tylko Waze)

Jeśli podczas tworzenia podróży włączysz raportowanie odchyleń od trasy, gdy kierowca zjedzie z trasy, interfejs API zwróci metadane odchyleń od trasy. Dostęp do tych danych możesz uzyskać w ten sposób:

  • Na żądanie: wywołaj metodę GetTrip. Serwer zachowuje ostatni znany stan odchylenia.
  • W czasie rzeczywistym: subskrybuj Google Cloud Pub/Sub. Usługa publikuje aktualizacje odchyleń za pomocą istniejącego zdarzenia updated_trip w ciągu 5 sekund od wykrycia.

Odczytywanie ładunku odchylenia

Obiekt last_route_deviation zawiera te metadane, które ułatwiają analizowanie zdarzenia:

Pole Typ Opis
location LatLng Współrzędne szerokości i długości geograficznej, w których urządzenie klienta zarejestrowało odchylenie.
source TriggerSource Powód odchylenia. Użyj tego, aby określić, czy kierowca wykonał nieoczekiwane działanie lub postępował zgodnie z wskazówkami systemu:
  • DRIVER_INITIATED_REROUTE: kierowca podjął aktywną decyzję (np. skręcił w złą stronę lub ręcznie wybrał nową trasę).
  • SYSTEM_INITIATED_REROUTE: aplikacja do nawigacji wyznaczyła nową trasę (np. z powodu zmiany warunków ruchu lub zamknięcia drogi).
client_timestamp Timestamp Czas, w którym urządzenie klienta wykryło odchylenie.
server_timestamp Timestamp Czas, w którym serwer przetworzył aktualizację odchylenia.

Obsługa stanów zakończenia przejazdu

Gdy kierowca dotrze do miejsca docelowego lub przestanie korzystać z nawigacji, ładunek zwróci jeden z tych stanów końcowych: Używaj tych stanów, aby wywoływać odpowiednie kolejne kroki w aplikacji.

Stan Opis Zalecane działanie
ARRIVED Kierowca dotarł do miejsca docelowego. Zapoznaj się z: remainingDistanceMeters Jeśli kierowca zaparkował w pobliżu, ale nie w dokładnych współrzędnych, rozważ podanie w aplikacji wskazówek dotyczących dojścia pieszo.
SUSPENDED Kierowca ręcznie zamknął szczegółowe wskazówki dojazdu przed dotarciem do miejsca docelowego.
Gdy kierowca przedwcześnie zakończy sesję, Mapy Google lub Waze nie przekierują go automatycznie z powrotem do Twojej aplikacji. Musi on ręcznie kliknąć przycisk powrotu. 		Aby pomóc kierowcom w ukończeniu przejazdu, porównaj execution.location z celem podróży. Jeśli pozostała odległość, udostępnij przycisk lub link umożliwiający wznowienie podróży lub przejście do trybu pieszego.
FAILED Połączenie zostało przerwane z powodu błędu technicznego. Dzieje się tak, gdy aplikacja nie może obliczyć trasy lub pojawia się ostrzeżenie dotyczące bezpieczeństwa. Kierowca może nadal korzystać z nawigacji, ale nie będziesz otrzymywać aktualizacji. Wróć do ręcznego śledzenia stanu w aplikacji.
CLIENT_ERROR Ten stan pojawia się z jednego z tych powodów:
  • Kierowca wycofuje zgodę.
  • Kierowca korzysta z nieobsługiwanej platformy, np. Androida Auto lub Apple CarPlay.
  • Aplikacja ponownie wykorzystuje token podróży w przypadku różnych przejazdów. Na przykład Navigation Connect odrzuca prośby o zmianę miejsca docelowego podróży lub zaktualizowanie zakończonej podróży.
  • Kierowca znajduje się w Stanach Zjednoczonych w dowolnym momencie przejazdu, ale w Twojej aplikacji nie jest włączone udostępnianie danych w Stanach Zjednoczonych, gdy podczas konfiguracji zweryfikowano aplikację.
 Wróć do ręcznego śledzenia stanu w aplikacji.