Jak wyszukać przystanki komunikacji w pobliżu za pomocą API?

Aby wyszukać przystanki wokół punktu, przekaż jego szerokość i długość geograficzną oraz promień do API lokalizacyjnego. Następnie sprawdź status odpowiedzi, zwrócone obiekty oraz informacje o pokryciu, zanim wyświetlisz listę lub mapę.

W kontrakcie ROOTE roote-1.0.0, ścieżka GET /v1/transit/nearby pozwala znaleźć miejsca komunikacji w pobliżu. Nie pobiera ona odjazdów ani alertów w czasie rzeczywistym. Wyszukiwanie lokalizacji i wyszukiwanie jej kolejnego odjazdu to dwie odrębne operacje.

Ustaw parametry

Zapytanie używa lat dla szerokości geograficznej i lng dla długości geograficznej. Alias lon jest również opisany w kontrakcie. Parametr radius oznacza promień w metrach; limit ogranicza liczbę żądanych wyników. Filtr modes może określić tryby transportu.

Te współrzędne są przykładem wyszukiwania w Bordeaux; nie oznaczają gwarantowanego przystanku. Sprawdź kontrakt OpenAPI ROOTE dla aktualnych limitów, pól i warunków.

Wyślij pierwsze zapytanie po stronie serwera

Oto przykład w JavaScript dla środowiska Node.js z obsługą fetch. Token, jeśli Twój dostęp go wymaga, jest przechowywany w zmiennej środowiskowej po stronie serwera. Przykład nie wymaga umieszczania sekretu w przeglądarce.

async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}

Konsultowany kontrakt przewiduje dostęp anonimowy lub z tokenem, zgodnie z obowiązującymi zasadami. Sprawdź swoje prawa i limity dostępu. Prawidłowa odpowiedź HTTP nie zwalnia z walidacji jej zawartości; w produkcji stosuj także walidację obiektów względem schematu.

Odczytaj obiekty i ich powiązania

Kolekcja stations zawiera zwrócone miejsca. Dla każdego sprawdź m.in. id, name, entity_kind, location oraz distance_meters. Odniesienia line_ids i operator_ids pozwalają powiązać kolekcje lines i operators, gdy są dostępne.

Wyświetl odległość geograficzną jako taką. Nie przeliczaj jej na czas chodzenia bez kalkulacji trasy. Przewodnik znajdź przystanek w pobliżu wyjaśnia, dlaczego dojścia mogą zmieniać faktyczny czas podróży.

Uwzględnij też jawnie nieznane informacje. W kontrakcie accessibility.wheelchair może mieć wartość unknown: nie oznacza ani tak, ani nie. Zapowiadana liczba odjazdów nie stanowi listy odjazdów.

Wyświetl listę lub mapę

Użyj identyfikatora do stabilizacji elementów interfejsu, nazwy do ich opisu, a location do ich położenia. Powiąż linie za pomocą odwołań zamiast dopasowywać nazwy.

Jeśli wyświetlasz kolory linii lub etykiety pochodzące z danych, traktuj je jak dane zewnętrzne wymagające walidacji. Dla nazw stosuj tekst, a nie wstrzykiwany HTML.

Zachowaj attrybucje źródeł i wyświetl te, które kontrakt wskazuje jako wymagane.

Radzenie sobie z pustym wynikiem, odpowiedzią częściową i błędem

Wynik empty oznacza wyszukiwanie bez zwróconych wyników na znanym obszarze. Nie dowodzi braku fizycznych środków transportu. Odpowiedź partial może zawierać przydatne miejsca, sygnalizując jednocześnie ograniczenia: przedstaw wyniki i odpowiednie ostrzeżenie.

Przeczytaj coverage, warnings oraz limity zawarte w meta. Lista obcięta nie opisuje pełnego pokrycia. W przypadku błędu sieciowego lub HTTP wyświetl niedostępność, nie zastępując wyniku tekstem „brak przystanków”.

Dla kodu 429 zapoznaj się z instrukcjami ponawiania i ewentualnymi nagłówkami usługi. Unikaj pętli ponownego wysyłania.

Rozróżnienie przystanków, stref i peronów

Pole entity_kind rozróżnia różne poziomy miejsc. Dwa sąsiednie wyniki mogą odpowiadać różnym peronom; dwa podobne nazwy mogą pochodzić z różnych źródeł.

Nie scalaj miejsc automatycznie wyłącznie na podstawie bliskości. Korzystaj z relacji i tożsamości dokumentowanych przez usługę. Nasz przewodnik GTFS, GTFS-RT i GBFS wyjaśnia kontekst danych.

Przygotuj integrację produkcyjną

Uruchamiaj wyszukiwania, gdy pozycja lub filtry zmieniają się istotnie. Grupuj identyczne wywołania, stosuj timeouty i dopasuj cache do typu danych oraz warunków serwisu.

Lista miejsc i dostępność w czasie rzeczywistym mają różne wymagania co do świeżości. Przetestuj działanie na odpowiedziach pełnych, pustych, częściowych i błędnych, zanim udostępnisz wyszukiwanie użytkownikom.

Rozszerzanie wyszukiwania na usługi miejskie

Przystanki i usługi miejskie korzystają z odrębnych tras. Aby wyszukać toalety wokół tego samego punktu, trasa GET /v1/services/nearby oczekuje parametrów lat i lon, z types=toilets. Nie wysyłaj parametru modes=toilets do tej trasy: to słownictwo dotyczy adresu URL mapy, a nie filtra Usług.

Poniższy przykład w JavaScript tworzy adres URL dla Usług na promień 600 metrów. Nie wywołuje on zapytania; ponownie wykorzystaj opisane wcześniej kontrole HTTP i kontrakt. Oczekiwana kolekcja to services, zamiast stations. Zachowaj service_type, location, distance_meters oraz faktycznie obecne atrybuty.

Kontrakt REST dokumentuje m.in. toilets, drinking_water, fountain, wifi, parking, charging, aed i locker. Typy ujawniane przez MCP mogą się różnić. Aby poznać akceptowane parametry, ich zakresy i limity Twojego dostępu, zapoznaj się ze schematem używanego interfejsu.

Atrybuty usługi nie gwarantują jej dostępności w chwili wyszukiwania. Nieznana dostępność nie oznacza braku dostępu; pusta lista wynikająca z błędu nie dowodzi braku toalet. Zachowuj dane charakterystyczne dla każdej kategorii zamiast redukować je do nazwy i punktu.

Dla mapy łączonej powiąż wyniki z ich kategorią i identyfikatorami. Wyświetl komunikat o błędzie Usług bez usuwania przystanków zwróconych przez Transit. Wyszukiwanie pozostaje skupione na tym samym punkcie, choć statusy i zakresy pokrycia mogą się różnić.

const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
  lat: '44.8416106', lon: '-0.5810938',
  radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());

Diagnozowanie pustego lub błędnego wyszukiwania

Bezpośrednia integracja filtrowanej mapy na stronie

Budowanie asystenta wokół tych wyszukiwań

Częste pytania

Czy Nearby zwraca następne odjazdy?

Nie w przedstawionym tu kontrakcie. Ta ścieżka lokalizuje miejsca komunikacji; odjazdy wymagają osobnej funkcji.

Czy można wyświetlić pustą listę po błędzie?

Przedstaw niedostępność. Błąd nie dowodzi braku przystanków.

Czy token API może być umieszczony w przeglądarce?

Sekret powinien pozostać po stronie serwera. Korzystaj z właściwego modelu dostępu dla swojej aplikacji i konta.