Hogyan keressünk közeli járatokat API-val?

Egy pont környezetében való megállókereséshez adja meg a pont szélességi és hosszúsági koordinátáit, valamint a keresési sugarat egy közelségi API-nak. Ezután ellenőrizze a válasz státuszát, a visszaadott entitásokat és a lefedettségi adatokat, mielőtt megjeleníti a listát vagy a térképet.

Az ROOTE roote-1.0.0 szerződésében a GET /v1/transit/nearby útvonal a közeli közlekedési helyszíneket deríti fel. Nem ad vissza indulásokat vagy valós idejű riasztásokat. Egy hely keresése és a következő járatának lekérése két különálló művelet.

Paraméterek beállítása

A lekérdezés a lat paramétert használja a szélességhez, és a lng-t a hosszúsághoz. A lon alias is szerepel a szerződésben. A radius paraméter a méterben mért sugárt adja meg; a limit korlátozza a kért találatok számát. A modes szűrővel meghatározhatók a közlekedési módok.

Ezek a koordináták egy bordeaux-i keresési példa; nem jelentenek garantált megállót. Tekintse meg a ROOTE OpenAPI szerződést a aktuális határokról, mezőkről és feltételekről.

Első kérés elküldése szerver oldalon

Itt egy JavaScript példa Node.js környezethez fetch használatával. A token, ha használatos, környezeti változóban szerver oldalon marad. A példa nem igényli titok helyezését a böngészőbe.

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

A megtekintett szerződés lehetőséget ad anonim vagy tokenes hozzáférésre a vonatkozó szabályok szerint. Ellenőrizze jogosultságait és az elérési korlátokat. Egy helyes HTTP válasz nem helyettesíti a tartalom érvényesítését; éles környezetben használjon sémák szerinti ellenőrzést is.

Az entitások és kapcsolataik olvasása

A stations gyűjtemény tartalmazza a visszakapott helyszíneket. Mindegyiknél érdekes különösen az id, a név (name), az entity_kind, a location és a distance_meters érték. A line_ids és operator_ids hivatkozások a lines és operators gyűjteményekhez kapcsolódnak, ha elérhetők.

A távolságot földrajzi értékeként jelenítse meg. Ne alakítsa át gyaloglási idővé útvonaltervezés nélkül. A „ közeli megálló megtalálása ” útmutató megmagyarázza, hogy a hozzáférések hogyan befolyásolhatják a tényleges utazást.

Kezelje külön az ismeretlen adatokat is. A szerződés szerint az accessibility.wheelchair lehet unknown értékű, ami sem nem igen, sem nem nem. A meghirdetett indulási kapacitás nem azonos a valós indulási listával.

Lista vagy térkép megjelenítése

Használja az azonosítókat az interfész elemeinek stabilizálásához, a neveket a megjelenítéshez és a locationt a pozícióhoz. A járatokat a hivatkozások alapján kapcsolja össze, ne csak a neveik alapján.

Ha színeket vagy szövegeket mutat járatoktól származó adatokból, kezelje ezeket külső bemenetekként, amiket validálni kell. A neveknél használjon szöveget, ne beágyazott HTML-t.

Őrizze meg az adatok forrására vonatkozó kötelező feltüntetéseket, és jelenítse meg azokat, amiket a szerződés előír.

Üres eredmény, részleges válasz és hiba kezelése

Az empty eredmény azt jelenti, hogy a keresés a ismert területen nem adott találatot. Ez nem bizonyítja, hogy nincs fizikailag közösségi közlekedés. A partial válasz adhat hasznos helyszíneket ugyanakkor korlátozásokról is tájékoztat: mutassa meg a találatokat és a megfelelő figyelmeztetést.

Olvassa a coverage, warnings és a meta által jelzett korlátokat. Egy levágott lista nem reprezentál teljes lefedettséget. Hálózati vagy HTTP hiba esetén mutasson elérhetetlenséget, ne helyettesítse az eredményt „nincs megálló” üzenettel.

429-es kód esetén kövesse az újraküldési utasításokat és a szolgáltatás fejléceit. Kerülje a folytonos ismétlést.

Megállók, zónák és peronok megkülönböztetése

Az entity_kind mező különböző helyszíntípusokat különít el. Két közeli találat lehet két külön peron; két hasonló név tartozhat eltérő forrásokhoz.

Ne egyesítse automatikusan a helyeket csak közelség alapján. Használja a szolgáltató által dokumentált kapcsolatokat és identitásokat. Útmutatónk, GTFS, GTFS-RT és GBFS magyarázza az adatkontextust.

Az éles integráció előkészítése

Indítsa el a kereséseket, amikor a pozíció vagy a szűrők érdemben változnak. Egyesítse az azonos hívásokat, állítson be timeoutot és igazítsa a cache-t az adat típusához és a szolgáltatás körülményeihez.

Egy helyszínlista és egy valós idejű elérhetőség különböző frissességi elvárásokat támaszt. Tesztelje az útvonalat teljes, üres, részleges és hibás válaszokkal is, mielőtt a keresést a felhasználók elé tárja.

A keresés kibővítése városi szolgáltatásokra

A megállók és a városi szolgáltatások külön útvonalakon működnek. Ha ugyanazon a pont körül vécéket szeretne keresni, a GET /v1/services/nearby útvonal várja a lat és lon paramétereket, a types=toilets értékkel. Ne küldjön modes=toilets paramétert erre az útvonalra: ez a fogalom a térképes URL-hez tartozik, nem a Szolgáltatások szűrőhöz.

A következő JavaScript példa egy 600 méteres sugarú Services URL-t épít fel. Nem indítja el a kérést; használja újra a fentebb leírt HTTP és szerződés ellenőrzéseket. A várt kollekció a services lesz a stations helyett. Tartsa meg a service_type, location, distance_meters és a ténylegesen jelenlévő attribútumokat.

A REST szerződés dokumentál többek között toilets, drinking_water, fountain, wifi, parking, charging, aed és locker típusokat. A MCP által közzétett típusok eltérhetnek. Az elfogadott paraméterekért, azok határaiért és az Ön hozzáférési korlátaiért tekintse meg a használt interfész sémáját.

Egy szolgáltatás attribútumai nem garantálják a tényleges nyitvatartást a keresés időpontjában. Az ismeretlen hozzáférhetőség nem egyenértékű azzal, hogy a szolgáltatás nem elérhető; egy hibából eredő üres lista nem bizonyítja a vécék hiányát sem. Tartsa meg az adatokat családonként külön, ahelyett, hogy csak egy nevet és pontot redukálna.

Egy összevont térképhez párosítsa az eredményeket azok családjához és azonosítóihoz. Jelenítsen meg Szolgáltatások hibát anélkül, hogy törölné a Transit által visszaadott megállókat. A keresés ugyanazon a ponton marad, de az állapotok és lefedettségek eltérhetnek.

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

Üres vagy hibás keresés diagnosztizálása

Szűrt térkép közvetlen beágyazása egy weboldalba

Segédprogram építése ezek köré a keresések köré

Gyakran ismételt kérdések

A Nearby megmutatja a következő indulásokat?

Nem ebben a bemutatott szerződésben. Ez az útvonal a helyszíneket mutatja, az indulások lekérése külön kapacitást igényel.

Üres listát lehet megjeleníteni hiba után?

Mutasson leállást. Egy hiba nem bizonyítja megállók hiányát.

Az API tokent el lehet helyezni a böngészőben?

Titok a szerveren maradjon. Használja az alkalmazásához és fiókjához megtervezett hozzáférési modellt.