Obsługa danych o podróży

Gdy pobierasz dane o przejeździe, Twój backend otrzymuje ładunki JSON ze szczegółowymi informacjami o postępach kierowcy. Przeanalizuj te ładunki, aby monitorować przejazd, aktualizować systemy wysyłania i interpretować bieżące stany przejazdu, aby określić następny krok kierowcy w miarę postępów lub po zakończeniu przejazdu.

Odczytywanie ładunku danych

Mapy Google lub Waze wysyłają ładunki danych o podróży na serwery Navigation Connect, gdy kierowca rozpoczyna nawigację, okresowo na trasie (domyślnie co 60 sekund) i gdy kierowca dociera do miejsca docelowego. Każdy komunikat JSON zawiera odpowiednie dane o podróży, w tym współrzędne kierowcy dopasowane do drogi, przebyty dystans i szacowany czas dotarcia na miejsce. Te aktualizacje odzwierciedlają aktywną trasę kierowcy w czasie rzeczywistym, dlatego mogą się różnić od tras wstępnie obliczonych przez backend (patrz Najczęstsze pytania).

Poniższy przykładowy kod pokazuje ładunek danych przejazdu, gdy kierowca rozpoczyna nawigację na trasie 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 stanów aktywnych przejazdów

Aby potwierdzić, że proces został pomyślnie rozpoczęty, 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ęty.

Obsługa dodanych przystanków

Kierowcy mogą dodawać przystanki do trasy podczas nawigacji. Jeśli tak, 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 zostaną zwiększone, aby uwzględnić dodane przystanki.

Sposób dodawania przystanków zależy od aplikacji do nawigacji i jest zgodny z jej standardowymi funkcjami:

  • 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.

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

Rozwiązywanie problemów z uwierzytelnianiem i uruchamianiem

Jeśli nie otrzymasz stanu ENROUTE, prawdopodobnie wystąpił błąd uwierzytelniania. Najczęstsze przyczyny to błędy w pisowni parametrów interfejsu API lub wygaśnięcie tokena przejazdu. Sprawdź czas ważności 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. Potwierdź te informacje:

  • 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.

Postępowanie z pozostałymi danymi o trasach

Jeśli podczas tworzenia podróży włączysz raportowanie pozostałej trasy, Twój backend będzie otrzymywać łamaną pozostałej trasy i informacje o warunkach na drodze w czasie rzeczywistym od bieżącej lokalizacji kierowcy do miejsca docelowego. Kierowcy muszą mieć Waze w wersji 5.20.0.2 lub nowszej na Androidzie, 5.20.0.1 lub nowszej na iOS albo Mapy Google na Androida w wersji 26.27 lub nowszej.

Możesz pozyskiwać i przetwarzać te dane, aby zasilać kilka funkcji w aplikacjach, takich jak:

  • Mapy śledzenia na żywo: renderuj pozostałą część trasy na mapie internetowej lub mobilnej dla klienta, aby zapewnić mu widoczność trasy kierowcy.
  • Zwiększanie dokładności szacowanego czasu dotarcia na miejsce: połącz linię łamaną dopasowaną do drogi i prędkości w interwałach ruchu, aby ulepszyć wewnętrzną logistykę lub prognozy dotyczące czasu dostawy.
  • Analizowanie zgodności trasy: porównaj geometrię pozostałej trasy z oczekiwanymi trasami wysyłki, aby ocenić, czy kierowca przestrzega trasy (szczegółowe informacje o tym, dlaczego trasy w czasie rzeczywistym i wstępnie obliczone mogą się różnić, znajdziesz w najczęstszych pytaniach).

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. Jednak format i struktura tych danych w ładunku zależą od używanej metody pobierania.

GetTrip metoda

Gdy wywołujesz 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 łamanej.

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

Aktualizacje Google Cloud Pub/Sub

Gdy pobierasz dane o przejazdach za pomocą Pub/Sub, aktualizacje zawsze zwracają dane o pozostałej trasie w ujednoliconym formacie GeoJSON FeatureCollection w polu execution.remainingRoute.

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

Przykładowy ładunek Pub/Sub

Poniższy przykładowy kod pokazuje strukturę GeoJSON zwracaną 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ędnienie pozostałych danych trasy w wiadomościach Pub/Sub może znacznie zwiększyć rozmiar ładunku (do 13–14 KB na wiadomość). Jeśli otrzymujesz częste aktualizacje, może to zwiększyć obciążenie przetwarzania backendu i koszty użytkowania.

Aby zoptymalizować strumień, podczas tworzenia podróży użyj parametru pubsubFieldMask w obiekcie TripConfig, aby wykluczyć duże pola. Szczegółowe informacje znajdziesz w sekcji Konfiguracje opcjonalne.

Obsługa zjechania z trasy (tylko Waze)

Kierowcy muszą mieć Waze w wersji 5.22 lub nowszej.

Jeśli podczas tworzenia podróży włączysz raportowanie o zjechaniu z trasy, gdy kierowca zjedzie z trasy, interfejs API zwróci metadane dotyczące zjechania z trasy. Dostęp do tych danych możesz uzyskać na te sposoby:

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

Odczytywanie ładunku odchylenia

Obiekt last_route_deviation udostępnia te metadane, które ułatwiają analizę 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 tej opcji, aby sprawdzić, czy kierowca podjął nieoczekiwane działanie lub postępował zgodnie ze wskazówkami systemu:
  • DRIVER_INITIATED_REROUTE: kierowca dokonał aktywnego wyboru (np. skręcił w niewłaściwą stronę lub ręcznie wybrał nową trasę).
  • SYSTEM_INITIATED_REROUTE: aplikacja do nawigacji obliczyła nową trasę (np. z powodu zmiany warunków na drodze lub zamknięcia drogi).
client_timestamp Timestamp Czas, w którym urządzenie klienta wykryło odchylenie.
server_timestamp Timestamp Czas przetworzenia przez serwer aktualizacji odchylenia.

Obsługa stanów zakończenia przejazdu

Gdy kierowca dotrze do miejsca docelowego lub zatrzyma nawigację, ładunek zwraca jeden z tych stanów końcowych. Użyj tych stanów, aby wywołać odpowiednie dalsze 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 dokładnie we wskazanych współrzędnych, rozważ podanie w aplikacji trasy pieszej.
SUSPENDED Kierowca ręcznie wyłączył szczegółowe wskazówki dojazdu przed dotarciem do celu.
Mapy Google i Waze nie przekierowują automatycznie kierowców do Twojej aplikacji, gdy przedwcześnie zakończą sesję, dlatego kierowca musi ręcznie kliknąć przycisk powrotu.
Aby pomóc kierowcom dotrzeć do celu, porównaj execution.location z miejscem docelowym. Jeśli odległość pozostaje, udostępnij przycisk lub link, aby wznowić przejazd lub przełączyć się na tryb pieszy.
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, takiej jak Android Auto lub Apple CarPlay.
  • Aplikacja używa tego samego tokena przejazdu w przypadku różnych przejazdów. Na przykład Navigation Connect odrzuca żądania, które zmieniają miejsce docelowe przejazdu lub aktualizują zakończony przejazd.
  • Kierowca znajduje się w Stanach Zjednoczonych w dowolnym momencie przejazdu, ale Twoja aplikacja nie ma włączonego udostępniania danych w Stanach Zjednoczonych, gdy zweryfikujesz aplikację podczas konfiguracji.
Wróć do ręcznego śledzenia stanu w aplikacji.