Jak vyhledat dopravní zastávky v okolí pomocí API?

Pro vyhledání zastávek okolo bodu předejte jeho zeměpisnou šířku, délku a poloměr do proximity API. Poté zkontrolujte stav odpovědi, vrácené entity a informace o pokrytí, než zobrazíte seznam nebo mapu.

V kontraktu ROOTE roote-1.0.0 cesta GET /v1/transit/nearby vyhledává dopravní místa v okolí. Nezískává ale odjezdy ani reálné výstrahy. Vyhledání místa a vyhledání jeho příštího průjezdu jsou dva odlišné procesy.

Nastavte parametry

Dotaz používá lat pro zeměpisnou šířku a lng pro délku. Alias lon je také uveden v kontraktu. Parametr radius udává poloměr v metrech; limit omezuje počet požadovaných výsledků. Filtr modes může specifikovat typy dopravy.

Tyto souřadnice slouží jako příklad hledání v Bordeaux; nezaručují konkrétní zastávku. Pro aktuální rozsahy, pole a podmínky si přečtěte OpenAPI kontrakt ROOTE .

Odešlete první požadavek ze serveru

Zde je příklad v JavaScriptu pro prostředí Node.js s podporou fetch. Token, pokud jej používáte, zůstává ve serverové proměnné prostředí. Tento příklad nevyžaduje ukládání tajemství v prohlížeči.

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
  };
}

Kontrakt umožňuje anonymní přístup nebo přístup s tokenem podle platných pravidel. Zkontrolujte svá práva a limity. Správná HTTP odpověď neznamená validitu obsahu; v produkci použijte také ověření objektů vůči schématu.

Čtení entit a jejich vztahů

Kolekce stations obsahuje vrácená místa. U každého si zejména prohlédněte id, name, entity_kind, location a distance_meters. Odkazy line_ids a operator_ids umožňují spojení s kolekcemi lines a operators, pokud jsou poskytnuty.

Zobrazujte geografickou vzdálenost jako takovou. Nepřevádějte ji na dobu chůze bez výpočtu trasy. Průvodce nalezení blízké zastávky vysvětluje proč přístupy mohou měnit reálný pohyb.

Explicitně zpracujte i neznámé informace. V kontraktu accessibility.wheelchair může mít hodnotu unknown: ta není ani ano, ani ne. Oznámená kapacita odjezdů není seznamem odjezdů.

Zobrazení seznamu nebo mapy

Použijte identifikátor pro stabilitu prvků rozhraní, jméno pro popisk a location pro pozici. Linky přiřazujte pomocí odkazů, nikoliv porovnáváním jejich jmen.

Pokud zobrazujete barvy linek nebo popisky ze zdrojových dat, považujte je za externí vstupy a ověřujte. Pro názvy používejte text, ne vkládaný HTML.

Zachovejte zdroje a zobrazte ty, které kontrakt vyžaduje.

Zpracování prázdného výsledku, částečné odpovědi a chyb

Výsledek empty znamená vyhledávání bez výsledků v známém dosahu. Neprokazuje fyzickou nepřítomnost dopravy. Částečný výsledek partial může obsahovat užitečná místa a současně upozornění na omezení: zobrazte výsledky a odpovídající upozornění.

Přečtěte si coverage, warnings a limity v meta. Zkrácený seznam neznamená úplné pokrytí. V případě chyb sítě nebo HTTP zobrazte nedostupnost a nenahrazujte ji „žádnou zastávkou“.

Pro kód 429 si prostudujte pokyny k opakování a případné hlavičky služby. Vyhněte se nekonečným opakováním.

Rozlišení stanic, zón a nástupišť

Pole entity_kind rozlišuje úrovně míst. Dva sousední výsledky mohou být různá nástupiště; stejná jména mohou patřit do různých zdrojů.

Automaticky neslučujte místa jen na základě blízkosti. Používejte vztahy a identity dokumentované službou. Náš průvodce GTFS, GTFS-RT a GBFS vysvětluje kontext dat.

Příprava produkční integrace

Spouštějte vyhledávání při smysluplné změně pozice nebo filtrů. Sdružte stejné požadavky, nastavte timeout a upravte cache podle typu dat a podmínek služby.

Seznam míst a data v reálném čase mají různé požadavky na čerstvost. Ověřte průběh se všemi typy odpovědí před zpřístupněním uživatelům.

Rozšířit vyhledávání na městské služby

Zastávky a městské služby používají odlišné cesty. Pro vyhledání toalet kolem stejného bodu cesta GET /v1/services/nearby očekává lat a lon s parametrem types=toilets. Neposílejte modes=toilets na tuto cestu: tato terminologie patří k URL mapy, nikoliv filtru Služeb.

Následující příklad v JavaScriptu sestavuje URL pro Služby s rádiem 600 metrů. Neposílá dotaz; znovu použijte HTTP a smluvní kontroly popsané výše. Očekávaná kolekce je services místo stations. Uchovejte service_type, location, distance_meters a skutečně přítomné atributy.

REST smlouva dokumentuje zejména toilets, drinking_water, fountain, wifi, parking, charging, aed a locker. Typy vystavené MCP se mohou lišit. Pro přijaté parametry, jejich rozsahy a omezení vašeho přístupu konzultujte schéma použitého rozhraní.

Atributy služby nezaručují její otevření v době vyhledávání. Neznámá přístupnost neznamená nedostupnost služby; prázdný seznam způsobený chybou nedokazuje absenci toalet. Uchovávejte data specifická pro každou kategorii místo redukce jen na název a bod.

Pro kombinovanou mapu spojte výsledky s rodinou i jejich identifikátory. Zobrazte chybu Služeb, aniž byste vymazali zastávky vrácené Transit. Vyhledávání zůstává zaměřeno na stejný bod, ale stavy a pokrytí se mohou lišit.

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());

Diagnostika prázdného nebo chybného vyhledávání

Přímá integrace filtrované mapy do webu

Vytvoření asistenta založeného na tomto vyhledávání

Často kladené otázky

Poskytuje Nearby příští odjezdy?

Ne v tomto prezentovaném kontraktu. Tato cesta vyhledává dopravní místa; odjezdy vyžadují samostatnou kapacitu.

Mohu zobrazit prázdný seznam po chybě?

Zobrazte nedostupnost. Chyba nevylučuje přítomnost zastávek.

Mohu umístit API token do prohlížeče?

Tajné údaje musí zůstat na straně serveru. Použijte přístupový model určený pro vaši aplikaci a účet.