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

> Objevte vyhledávání zastávek v okolí s API ROOTE: souřadnice, poloměr, příklad v JavaScriptu, čtení výsledků a zpracování chyb.

Source: https://www.roote.ai/cs/guides/jak-vyhledat-dopravni-zastavky-blizko-se-pomoci-api/
Language: cs
Author: ROOTE

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.

| Parametr | Příklad | Význam |
| --- | --- | --- |
| lat | 44.8378 | Zeměpisná šířka bodu hledání |
| lng | -0.5792 | Zeměpisná délka bodu hledání |
| radius | 600 | Požadovaný poloměr v metrech |
| limit | 10 | Požadovaný limit výsledků |
| modes | bus,tram | Hledané režimy 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](https://api.roote.ai/openapi.json) .

## 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](https://www.roote.ai/cs/guides/jak-najit-nejblizsi-zastavku-bus-tramvaj/) 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](https://www.roote.ai/cs/guides/gtfs-gtfs-rt-a-gbfs-jake-rozdily/) 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í](https://www.roote.ai/cs/guides/zadny-vysledek-ci-chyba-api-jak-rozeznat/)

[Přímá integrace filtrované mapy do webu](https://www.roote.ai/cs/guides/jak-integrovat-mobilitni-mapu-do-webu/)

[Vytvoření asistenta založeného na tomto vyhledávání](https://www.roote.ai/cs/guides/jak-vytvorit-asistenta-ktory-najde-mobilitu-okolo-adresy/)

## Č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.