Kuinka etsiä lähellä olevia liikennepysäkkejä API-rajapinnalla?

Pysäkkien etsimiseen pisteen ympäriltä lähetä koordinaatit eli leveys- ja pituusaste sekä säde läheisyys-API:lle. Tarkista sen jälkeen vastauksen tila, palautetut objektit ja kattavuustiedot ennen listan tai kartan näyttämistä.

ROOTE-sopimuksessa roote-1.0.0, GET /v1/transit/nearby -reitti hakee lähistöllä olevat liikennepaikat. Se ei hae lähtiä eikä reaaliaikaisia hälytyksiä. Paikan haku ja seuraavan lähdön haku ovat kaksi erillistä toimintoa.

Määritä parametrit

Pyyntö käyttää lat-parameteria leveyspiirille ja lng-parameteria pituuspiirille. Alias lon on myös mainittu sopimuksessa. Parametri radius ilmaisee säteen metreinä; limit rajoittaa pyydettyjen tulosten määrää. Modes-suodatin voi määrittää liikennemuodot.

Nämä koordinaatit ovat esimerkki hausta Bordeaux'ssa; ne eivät takaa pysäkkiä. Tarkista ROOTE OpenAPI -sopimus nykyisille rajoille, kentille ja ehdoille.

Lähetä ensimmäinen pyyntö palvelimella

Tässä on JavaScript-esimerkki Node.js-ympäristössä, jossa on fetch. Jos käytät tokenia, se säilytetään palvelinpuolen ympäristömuuttujassa. Esimerkissä ei tarvitse sijoittaa salaisuutta selaimeen.

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

Tarkasteltu sopimus sallii anonymiteetin tai token-pohjaisen käytön voimassa olevien sääntöjen mukaan. Tarkista käyttöoikeutesi ja rajasi. Oikea HTTP-vastaus ei korvaa sisällön validointia; tuotannossa varmista myös objektien validointi skeemaa vasten.

Lue objektit ja niiden suhteet

Stations-kokoelma sisältää palautetut paikat. Kukin sisältää mm. id:n, nimen, entity_kind:n, sijainnin ja distance_metersin. Viitteet line_ids ja operator_ids yhdistävät lines- ja operators-kokoelmiin, jos ne ovat saatavilla.

Näytä maantieteellinen etäisyys sellaisenaan. Älä muunna sitä kävelyajaksi ilman reitin laskentaa. Opas löydä lähellä oleva pysäkki selittää, miksi kulkureitit voivat erota todellisesta liikkumisesta.

Käsittele myös tuntemattomat tiedot selvästi. Sopimuksessa accessibility.wheelchair voi olla unknown: tämä ei tarkoita ei tai kyllä. Ilmoitettu lähtökapasiteetti ei ole lähtölista.

Näytä lista tai kartta

Käytä id:tä käyttöliittymäelementtien stabilointiin, nimeä niiden nimikkeenä ja locationia sijainnin näyttämiseen. Yhdistä linjat viitteiden avulla, älä pelkkien nimien perustella.

Jos näytät värikoodattuja linjoja tai datasta peräisin olevia nimikkeitä, käsittele ne ulkoisina syötteinä jotka täytyy validoida. Käytä nimissä tekstimuotoa, ei HTML-injektiota.

Pidä lähdeviitteet mukana ja näytä ne, joita sopimus edellyttää.

Käsittele tyhjä tulos, osittainen vastaus ja virhe

Empty-tila tarkoittaa hakua ilman tuloksia tunnetulla alueella, se ei todista liikenteen puuttumista. Partial-vastaus voi sisältää hyödyllisiä paikkoja, mutta ilmoittaa myös rajoituksista: näytä tulokset ja sopiva varoitus.

Lue coverage, warnings ja meta-kohdan sovelletut rajat. Katkaistu lista ei kuvasta täydellistä kattavuutta. Verkko- tai HTTP-virheissä näytä ei saatavilla -viesti, älä korvaa tulosta "ei pysäkkejä" -ilmoituksella.

429-koodin kohdalla noudata palautumisohjeita ja palvelun mahdollisia otsikoita. Vältä silmukkamaista uudelleenyritystä.

Erota asemat, alueet ja laiturit

Entity_kind-kenttä erottaa eri tason paikat. Kaksi lähellä olevaa tulosta voi olla eri laitureita; samankaltaiset nimet voivat tulla eri lähteistä.

Älä yhdistä paikkoja pelkän läheisyyden perusteella. Käytä palvelun dokumentoituja suhteita ja identiteettejä. Opas GTFS, GTFS-RT ja GBFS selittää tietojen kontekstin.

Valmistele tuotantointegraatio

Käynnistä haut kun sijainti tai suodattimet muuttuvat olennaisesti. Ryhmittele samanlaiset haut, määrittele aikakatkaisu ja sovita välimuisti datan ja palvelun ehtojen mukaan.

Paikkalista ja reaaliaikainen saatavuus vaativat erilaisen tuoreusvaatimuksen. Testaa reitti täydellisillä, tyhjillä, osittaisilla ja virheellisillä vastauksilla ennen käyttöliittymän näyttämistä käyttäjille.

Laajenna haku kaupunkipalveluihin

Pysäkit ja kaupunkipalvelut käyttävät eri reittejä. Etsiäksesi wc-tiloja samalta alueelta, GET-reitti /v1/services/nearby odottaa parametrit lat ja lon, sekä types=toilets. Älä lähetä modes=toilets tälle reitille: tämä terminologia kuuluu kartta-URL:iin, ei Services-suodattimeen.

Seuraava JavaScript-esimerkki rakentaa Services-URL:n 600 metrin säteellä. Se ei käynnistä pyyntöä; käytä uudelleen aiemmin kuvattuja HTTP- ja sopimusvalvontamekanismeja. Odotettu kokoelma muuttuu services-muotoon stationsin sijaan. Säilytä service_type, location, distance_meters sekä vain olemassa olevat attribuutit.

REST-sopimus dokumentoi erityisesti toilets, drinking_water, fountain, wifi, parking, charging, aed ja locker. MCP:n esittämät tyypit voivat vaihdella. Hyväksytyt parametrit, niiden rajat ja pääsysi rajoitukset löytyvät käytetyn rajapinnan skeemasta.

Palvelun attribuutit eivät takaa palvelun olevan auki haun tekohetkellä. Tuntematon saavutettavuus ei tarkoita, että palvelu ei olisi käytettävissä; virheestä johtuva tyhjä lista ei todista wc-tilojen puuttumista. Pidä perhekohtaiset tiedot erillään äläkä supista niitä pelkkään nimeen ja pisteeseen.

Yhdistetyssä kartassa yhdistä tulokset niiden perheeseen ja tunnisteisiin. Näytä Services-virheilmoitus ilman, että poistat Transit:n palauttamat pysäkit. Haku kohdistuu samaan pisteeseen, mutta tilat ja kattavuudet voivat vaihdella.

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

Tyhjien tai virheellisten hakujen diagnosointi

Suoraan suodatetun kartan integrointi sivustolle

Rakentaa apuri näiden hakujen ympärille

Usein kysytyt kysymykset

Tarjoaako Nearby seuraavat lähdöt?

Ei tässä esitellyn sopimuksen mukaan. Tämä reitti löytää paikat; lähdöt vaativat oman kapasiteettinsa.

Voiko virheen jälkeen näyttää tyhjän listan?

Näytä saatavuuden puute. Virhe ei todista pysäkkien puuttumista.

Voiko API-tokenin sijoittaa selaimeen?

Salainen avain tulee säilyttää palvelinpuolella. Käytä sovelluksellesi ja tilillesi tarkoitettua käyttömallia.