Usługi pozycji i przejazdów

Ta strona wyjaśnia, jak pobierać pozycje pojazdów i historię przejazdów w Fleet API dla odbiorców biznesowych i technicznych.

Skróty i terminy

• API: Application Programming Interface.
• GPS: Global Positioning System.

Którego endpointu użyć?

Użyj poniższego mapowania, gdy klienci pytają o dane lokalizacyjne:

• Wszystkie pozycje GPS / pełna historia punktów tripu:
  • Get events for one vehicle
  • Get events for all vehicles
• Ciągły tracking (widok floty near real-time):
  • Get vehicles status, location, fuel, odometer and more
• Lokalizacje startu i końca tripu:
  • Get all trips
  • Get trips by registration

1) Wszystkie pozycje GPS

Co to oznacza

Pobierz historyczne eventy pozycji w zadanym okresie, aby odtworzyć, gdzie znajdował się pojazd.

Najlepsze endpointy

• Jeden pojazd: Get events for one vehicle
• Wszystkie pojazdy: Get events for all vehicles

Interpretacja biznesowa

• Używaj do dochodzeń, odtwarzania tripów, potwierdzania obecności i audytów operacyjnych.
• To najlepsze źródło, gdy użytkownik oczekuje "wszystkich punktów" w oknie czasowym.

Interpretacja dla dewelopera

• Traktuj eventy jako historyczne punkty telemetryczne.
• Wykonuj zapytania po oknach czasowych i stosuj paginację.
• Dla długich okresów pobieraj dane partiami, aby uniknąć bardzo dużych response.

2) Ciągły tracking (Near Real-Time)

Co to oznacza

Ciągłe prezentowanie ostatniej znanej pozycji pojazdów, podobnie jak na mapie floty na żywo.

Najlepszy endpoint

• Get vehicles status, location, fuel, odometer and more

Interpretacja biznesowa

• Używaj w codziennych operacjach live i monitoringu dyspozytorskim.
• Najlepsze rozwiązanie dla przypadku "gdzie pojazd jest teraz?".

Interpretacja dla dewelopera

• Zaimplementuj polling (np. co 10-30 sekund), aby odświeżać bieżące statusy.
• Jest to near real-time status polling, a nie websocket streaming feed.
• Łącz z endpointami events, gdy potrzebny jest historyczny breadcrumb detail.

3) Pełna historia tripów

Co to oznacza

W zależności od intencji klienta, "historia przejazdu" może oznaczać:

• Pełne punkty breadcrumb z przejazdu, lub
• Podsumowania tripów z lokalizacją startu i końca.

Wybór endpointu

• Dla pełnych punktów breadcrumb przejazdu: użyj endpointów events.
• Dla lokalizacji start/koniec na poziomie tripu:
  • Get all trips
  • Get trips by registration

Interpretacja biznesowa

• Używaj trips do raportowania i analizy KPI na poziomie tripu.
• Używaj events, gdy analitycy potrzebują szczegółów na poziomie przejazdu.

Interpretacja dla dewelopera

• Trips to rekordy podsumowujące i nie powinny być traktowane jako pełne zbiory punktów przejazdu.
• Pełne odtwarzanie przejazdu buduj z danych events dla wybranego interwału.

Zalecany wzorzec implementacji

Dla większości aplikacji flotowych:

1. Odpytuj endpoint statusu pojazdów, aby uzyskać aktualny stan mapy.
2. Odpytuj endpointy events do historycznego odtwarzania trasy.
3. Odpytuj endpointy trips do raportowania przejazdów (start/koniec i kontekst tripu).