# Kuidas otsida lähimaid ühistranspordi peatusi API abil?

> Avasta lähipeatused ROOTE API abil: koordinaadid, raadius, JavaScripti näide, tulemuste lugemine ja vigade haldamine.

Source: https://www.roote.ai/et/guides/kuidas-ukasida-ligidal-olevaid-ylalaiu-api-ga/
Language: et
Author: ROOTE

Lähimate peatuskohtade leidmiseks edasta asukoha laius- ja pikkuskraad ning raadius lähipeatuste otsimise API-le. Kontrolli vastuse staatust, tagastatud üksusi ja katvuse infot enne nimekirja või kaardi kuvamist.

ROOTE lepingus roote-1.0.0 avastab GET /v1/transit/nearby teekond lähedal asuvad transpordikohad. See ei too vastu reaalajas väljumisi ega teateid. Koha otsing ja järgmise läbipääsu otsing on kaks eraldi toimingut.

## Parameetrite määramine

Päringus kasutatakse lat laiuskraadi ja lng pikkkraadi tähistamiseks. Alias lon on samuti lepingus kirjeldatud. Parameeter radius näitab raadiust meetrites; limit piirdub soovitud tulemite arvuga. Filter modes võib täpsustada transpordiliigid.

| Parameeter | Näide | Selgitus |
| --- | --- | --- |
| lat | 44.8378 | Otsipunkti laiuskraad |
| lng | -0.5792 | Otsipunkti pikkuskraad |
| radius | 600 | Soovitud raadius meetrites |
| limit | 10 | Soovitud tulemuste piirang |
| modes | bus,tram | Otsitud transpordiliigid |

Need koordinaadid on näidis Bordeaux´st; need ei taga konkreetset peatuskohta. Vaata täpsemalt [ROOTE OpenAPI lepingut](https://api.roote.ai/openapi.json) piirangute, väljade ja tingimuste kohta.

## Esimese serveripoolse päringu tegemine

Järgnevalt on näide JavaScriptist Node.js keskkonnas, kus on kasutusel fetch. Kui juurdepääsuks on vaja tokenit, hoitakse seda serveri keskkonnamuutujana. Näide ei nõua saladuse hoidmist brauseris.

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

Vaadeldav leping lubab anonüümset või tokenipõhist ligipääsu sõltuvalt kehtivatest reeglitest. Kontrolli oma õigusi ja ligipääsupiiranguid. Õnnestunud HTTP vastus ei asenda vastuse sisu valideerimist; tootmiskeskkonnas kasuta objektide valideerimist skeemi vastu.

## Üksuste ja nende seoste lugemine

Kogumik stations sisaldab tagastatud kohti. Iga kohta puhul vaata eelkõige id, name, entity_kind, location ja distance_meters. Viited line_ids ja operator_ids võimaldavad kujundada seoseid lines ja operators kogumitega, kui need on kättesaadavad.

Kuva geograafiline kaugus sellisena. Ära muuda seda läbikäidavaks ajaks ilma marsruudiarvutuseta. Juhend [lähedal asuva peatuse leidmine](https://www.roote.ai/et/guides/kuidas-leida-korgeim-linna-kinni-ja-trammipeatus/) selgitab, miks ligipääsud võivad tegelikku teekonda mõjutada.

Käsitle selgelt ka tundmatuid andmeid. Lepingus võib accessibility.wheelchair olla väärtus unknown: see ei ole ei yes ega no. Kuulutatud väljumisvõime ei ole sama mis väljumiste nimekiri.

## Nimekirja või kaardi kuvamine

Kasutage liidese elementide stabiliseerimiseks id-d, nimetusväärtust silte jaoks ja location asukoha määramiseks. Seo liinid viidetega, mitte nimedega lähendades.

Kui kuvad andmetest pärit liinivärve või silte, käsitle neid nagu välist sisendit, mis vajab valideerimist. Nimede puhul kasutage tavalist teksti, mitte HTML-i süstimist.

Hoidke allikate viited ja kuvage need, mida leping nõuab.

## Tühi tulemus, osaline vastus ja vea haldamine

Tühi (empty) tulemus tähendab, et otsing ei andnud tulemusi teadaolevas piirkonnas. See ei tõesta transpordi füüsilist puudumist. Osaline (partial) vastus võib sisaldada kasulikke kohti ja märkida piiranguid: esitage tulemused koos hoiatustega.

Lugege coverage, warnings ja meta alt kehtivaid piiranguid. Lõikunud nimekiri ei katva kogu ala täielikult. Võrgu- või HTTP- vea korral kuvage teenuse kättesaamatus, ärge asendage tulemust sõnumiga "puuduvad peatused".

Koodi 429 puhul järgige taaskäivitamise juhiseid ja teenuse päiseid. Vältige lõputut taaskäivitamist.

## Peatuste, tsoonide ja platvormide eristamine

Väli entity_kind eristab eri tasemega kohti. Kaks lähedal olevat tulemust võivad esindada erinevaid platvorme; sarnase nimetusega võivad pärineda eri allikatest.

Ärge automaatselt liituge kohti ainult lähedusel põhinedes. Kasutage teenuse dokumenteeritud suhteid ja identifitseerijaid. Meie juhend [GTFS, GTFS-RT ja GBFS](https://www.roote.ai/et/guides/gtfs-gtfs-rt-ja-gbfs-mis-on-eraldised/) selgitab andmete tausta.

## Tootmisesse viimise ettevalmistus

Käivitage otsingud siis, kui asukoht või filtrid oluliselt muutuvad. Koondage identsed päringud, määrake ooteajad ja kohandage vahemälu andmetüübi ja teenuse tingimuste põhjal.

Ülalaiad ja reaalajas saadavus ei vaja võrdset andmete värskust. Testige kogu protsessi tühjade, täielike, osaliste ja vigaste vastustega enne kasutajatele otsingu kuvamist.

## Otsi laiendamine linnateenustele

Peatused ja linnateenused kasutavad erinevaid teid. Tualettide otsimiseks sama punkti lähedal kasutab GET /v1/services/nearby teid lat ja lon, koos types=toilets parameetriga. Ärge saatke sellele teele modes=toilets: see sõnavara kuulub kaardilingile, mitte teenuste filtrisse.

Järgmine JavaScripti näide loob teenuse URL-i 600 meetri raadiuses. See ei käivita päringut; taaskasutage eespool kirjeldatud HTTP ja lepingu kontrollid. Oodatud kogumikuks saab services, mitte stations. Säilitage service_type, location, distance_meters ja reaalselt olemasolevad atribuudid.

REST leping dokumenteerib muu hulgas toilets, drinking_water, fountain, wifi, parking, charging, aed ja locker. MCP eksponeeritavad tüübid võivad erineda. Aktsepteeritud parameetrite, nende piiride ja teie ligipääsu piirangute kohta vaadake kasutatava liidese skeemi.

Teenusatribuudid ei taga teenuse avatud olekut otsingu hetkel. Teadmata ligipääsetavus ei võrdu ligipääsmatusega; vea tõttu tühi nimekiri ei tõesta tualettide puudumist. Hoidke andmed iga pere kohta eraldi, mitte ainult nime ja punkti kujul.

Ühiskaardi jaoks siduge tulemused nende pere ja identifikaatoritega. Kuvage teenuste viga ilma Transiti tagastatud peatusi kustutamata. Otsing jääb samale punktile keskendunuks, kuid olekud ja kaetud alad võivad erineda.

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

[Tühi või veaga otsing diagnoosimine](https://www.roote.ai/et/guides/mitte-ulemust-v%C3%B5i-api-viga-kuidas-eristada/)

[Filtreeritud kaardi otse saidile integreerimine](https://www.roote.ai/et/guides/kuidas-lisada-liikumiskaart-veebilehele/)

[Nende otsingute ümber assistendi loomine](https://www.roote.ai/et/guides/kuidas-luua-assistent-mobiliteedile-aadressi-lahedal/)

## Korduma kippuvad küsimused

### Kas Nearby annab järgmised väljumised?

Siin esitatud lepingu kohaselt mitte. See marsruut leiab transpordikohad; väljumised vajavad eraldi võimekust.

### Kas vigade järel võib kuvada tühja nimekirja?

Kuva teenuse kättesaamatus. Viga ei tõesta, et peatusi pole olemas.

### Kas API token võib olla brauseris?

Salajane võti peab jääma serverisse. Kasuta oma rakenduse ja konto ligipääsumudelit.