Kaip ieškoti netoliese esančių transporto stotelių su API?

Norėdami rasti stoteles aplink tam tikrą tašką, perduokite jo platumą, ilgumą ir spindulį netoliese esančių vietų API. Tada patikrinkite atsakymo būseną, grąžintas objektų kolekcijas ir aprėpties informaciją prieš rodydami sąrašą arba žemėlapį.

ROOTE sutartyje roote-1.0.0 GET /v1/transit/nearby maršrutas leidžia atrasti netoliese esančias transporto vietas. Jis negrąžina išvykimų ar realaus laiko įspėjimų. Vietos paieška ir artimiausio jos atvykimo radimas yra dvi atskiros operacijos.

Parametrų nustatymas

Užklausoje naudojama lat platumai ir lng ilgumui. Alias lon taip pat aprašytas sutartyje. Parametras radius apibrėžia spindulį metrais; limit riboja pageidaujamų rezultatų skaičių. Filtras modes gali nurodyti transporto rūšis.

Šios koordinatės yra paieškos pavyzdys Bordo mieste; jos negarantuoja stotelės. Peržiūrėkite ROOTE OpenAPI sutartį dėl galiojančių ribų, laukų ir sąlygų.

Siųsti pirmą užklausą serverio pusėje

Štai JavaScript pavyzdys Node.js aplinkai su fetch palaikymu. Token, jei naudojate prieigą su juo, saugomas serverio aplinkos kintamajame. Šiame pavyzdyje nereikia saugoti slaptumo naršyklėje.

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

Sutartis leidžia anoniminę arba token pagrindu vykdomą prieigą, priklausomai nuo taikomų politikų. Patikrinkite savo teises ir prieigos ribas. Teisingas HTTP atsakymas negarantuoja duomenų tinkamumo; gamyboje taip pat naudokite objektų validaciją pagal schemą.

Nuskaityti objektus ir jų ryšius

Stations kolekcija talpina grąžintas vietas. Kiekvienam peržiūrėkite ypač id, name, entity_kind, location ir distance_meters. Nuorodos line_ids ir operator_ids leidžia susieti lines ir operators kolekcijas, jei jos pateiktos.

Atstumą pateikite geografine prasme. Neskelbkite jo kaip ėjimo laiko be maršruto apskaičiavimo. Vadovas kaip rasti netoliese esančią stotelę paaiškina, kodėl prieigos takai gali keisti tikrąjį judėjimą.

Taip pat aiškiai apdorokite nežinomą informaciją. Sutartyje accessibility.wheelchair gali būti unknown: ši reikšmė nėra nei yes, nei no. Kiekvienas paskelbtas išvykimų pajėgumas nėra pačių išvykimų sąrašas.

Rodyti sąrašą arba žemėlapį

Naudokite identifikatorių elementams stabilizuoti UI, pavadinimą etiketėms ir location pozicijai. Susiekite linijas per nuorodas, o ne pagal vardų panašumą.

Jei rodomos linijų spalvos ar pavadinimai iš duomenų, elkitės su jais kaip su išoriniais duomenimis, kuriuos reikia tikrinti. Pavadinimams naudokite tekstą, o ne įterptą HTML.

Išlaikykite šaltinių priskyrimus ir rodykite tuos, kuriuos sutarčių reikalauja pateikti.

Valdyti tuščius, dalinius rezultatus ir klaidas

Empty rezultatas parodo, jog paieška negrąžino rezultatų žinomame plote. Tai nereiškia, kad fizinis transportas nėra. Partial atsakymas gali turėti naudingų vietų, bet su įspėjimu apie apribojimus: pateikite rezultatus su atitinkamu įspėjimu.

Perskaitykite coverage, warnings ir ribas meta. Apribotas sąrašas nėra išsamus aprėpties aprašymas. Tinklų arba HTTP klaidų atveju, rodykite paslaugos neprieinamumą, neuždengdami to „nėra stotelių“ pranešimu.

Esant 429 kodui, vadovaukitės atsinaujinimo gairėmis ir paslaugos antraštėmis. Venkite užburtų pakartotinių užklausų ciklų.

Atskirti stoteles, zonas ir platformas

entity_kind laukas skiria kelis vietų lygius. Du artimi rezultatai gali būti skirtingos platformos; panašūs pavadinimai gali priklausyti skirtingiems šaltiniams.

Nenustatykite automatinio vietų sujungimo tik pagal artumą. Naudokite paslaugos dokumentuotas sąsajas ir identitetus. Mūsų vadovas GTFS, GTFS-RT ir GBFS paaiškina duomenų kontekstą.

Paruošti integraciją gamybai

Skatinkite paieškas, kai pozicija arba filtrai prasmingai keičiasi. Grupėkite lygiagrečias užklausas, nustatykite laiko limitą ir pritaikykite talpyklą pagal duomenų rūšį ir paslaugos sąlygas.

Transporto vietų sąrašas ir realaus laiko duomenų prieinamumas reikalauja skirtingo duomenų šviežumo. Išbandykite visus scenarijus (pilną, tuščią, dalinį ir klaidos atsakymus), prieš pateikdami paiešką vartotojams.

Išplėsti paiešką iki miesto paslaugų

Stotelės ir miesto paslaugos naudoja skirtingus maršrutus. Norėdami ieškoti tualetų aplink tą patį tašką, GET /v1/services/nearby maršrutas laukia lat ir lon, su types=toilets. Nesiųskite modes=toilets į šį maršrutą: toks žodynas priklauso žemėlapio URL, o ne Paslaugų filtrui.

Šis JavaScript pavyzdys sudaro Paslaugų URL 600 metrų spinduliu. Jis neužkrauna užklausos; pakartotinai naudokite aukščiau aprašytus HTTP ir sutarties valdiklius. Laukiama kolekcija tampa services vietoje stations. Išlaikykite service_type, location, distance_meters ir tikrai esančias atributų reikšmes.

REST sutartyje dokumentuojami tokie tipai kaip toilets, drinking_water, fountain, wifi, parking, charging, aed ir locker. MCP pateikiami tipai gali skirtis. Dėl priimamų parametrų, jų ribų ir jūsų prieigos apribojimų žr. naudojamos sąsajos schemą.

Paslaugos atributai negarantuoja, kad ji veikia paieškos metu. Nežinoma prieinamumas nereiškia, kad paslauga neprieinama; tuščias sąrašas iš klaidos neįrodo tualetų nebuvimo. Išlaikykite duomenis pagal kiekvieną kategoriją, o ne sumažinkite iki pavadinimo ir taško.

Kombinuotam žemėlapiui susiekite rezultatus su jų kategorija ir ID. Rodykite Paslaugų klaidą, nesunaikindami Transit grąžintų stotelių. Paieška vis dar koncentruota į tą patį tašką, tačiau būsenos ir aprėptys gali skirtis.

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

Tuščios arba klaidingos paieškos diagnozavimas

Tiesiogiai įterpti filtruotą žemėlapį į svetainę

Sukurti asistentą remiantis šiomis paieškomis

Dažnai užduodami klausimai

Ar Nearby pateikia artimiausius išvykimus?

Ne šioje prezentuotoje sutartyje. Šis maršrutas atranda transporto vietas; atvykimai reikalauja atskiros funkcijos.

Ar galima po klaidos rodyti tuščią sąrašą?

Rodykite nepavykusios prieigos pranešimą. Klaida nereiškia, kad stotelių nėra.

Ar galima API raktą įdėti naršyklėje?

Slaptumas turi likti serverio pusėje. Naudokite prieigos modelį, skirtą jūsų programai ir paskyrai.