Cum să cauți stațiile de transport în apropiere folosind o API?

Pentru a căuta stații în jurul unui punct, transmite latitudinea, longitudinea și o rază către o API de proximitate. Verifică apoi starea răspunsului, entitățile returnate și informațiile de acoperire înainte de a afișa lista sau harta.

În contractul ROOTE roote-1.0.0, ruta GET /v1/transit/nearby descoperă locuri de transport în apropiere. Nu recuperează plecări sau alerte în timp real. Căutarea unui loc și căutarea următorului său pasaj sunt două operațiuni distincte.

Setează parametrii

Cererea folosește lat pentru latitudine și lng pentru longitudine. Aliasul lon este de asemenea descris în contract. Parametrul radius exprimă raza în metri; limit limitează numărul de rezultate solicitate. Filtrul modes poate specifica modurile de transport.

Aceste coordonate sunt un exemplu de căutare în Bordeaux; acestea nu indică o stație garantată. Consultă contractul OpenAPI ROOTE pentru limitele, câmpurile și condițiile actuale.

Trimite o primă cerere pe server

Iată un exemplu JavaScript pentru un mediu Node.js care are fetch. Tokenul, dacă accesul tău îl folosește, rămâne într-o variabilă de mediu pe server. Exemplul nu necesită plasarea unui secret în browser.

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

Contractul consultat prevede acces anonim sau prin token, conform politicilor aplicabile. Verifică-ți drepturile și limitele de acces. Un răspuns HTTP corect nu elimină necesitatea validării conținutului; în producție, folosește și o validare a obiectelor conform schemei.

Citește entitățile și relațiile lor

Colecția stations conține locurile returnate. Pentru fiecare, consultă cel puțin id, name, entity_kind, location și distance_meters. Referințele line_ids și operator_ids permit asocierea colecțiilor lines și operators când sunt disponibile.

Afișează o distanță geografică ca atare. Nu o transforma în timp de mers fără calcul de traseu. Ghidul găsește o stație apropiată explică de ce accesul poate modifica deplasarea reală.

Tratează explicit și informațiile necunoscute. În contract, accessibility.wheelchair poate fi unknown: această valoare nu echivalează nici cu yes nici cu no. O capacitate de plecări anunțate nu constituie o listă de plecări.

Afișează o listă sau o hartă

Folosește identificatorul pentru a stabiliza elementele interfeței, numele pentru etichetele lor și location pentru poziționarea lor. Asociază liniile prin referințe, mai degrabă decât după apropierea numelor lor.

Dacă afișezi culori ale liniilor sau etichete provenind din date, tratează-le ca intrări externe ce trebuie validate. Pentru nume, folosește text în loc de HTML injectat.

Păstrează atribuirile surselor și afișează-le pe cele pe care contractul le indică ca obligatorii.

Gestionarea rezultatului gol, răspunsului parțial și a erorilor

Un rezultat empty descrie o căutare fără rezultate returnate în perimetrul cunoscut. Nu dovedește absența fizică a transporturilor. Un răspuns partial poate conține locuri utile și semnalează limite; prezintă rezultatele și avertismentul potrivit.

Citește coverage, warnings și limitele aplicate în meta. O listă trunchiată nu descrie o acoperire exhaustivă. În caz de eroare rețea sau HTTP, afișează indisponibilitate, fără a înlocui rezultatul cu „nicio stație”.

Pentru un cod 429, consultă instrucțiunile de reluare și eventualele headere ale serviciului. Evită reluările în buclă.

Diferențiază stațiile, zonele și peroanele

Câmpul entity_kind distinge mai multe niveluri de locuri. Două rezultate apropiate pot corespunde unor peroane distincte; două nume similare pot aparține surselor diferite.

Nu fuziona automat locurile doar pe baza proximității. Folosește relațiile și identitățile documentate de serviciu. Ghidul nostru GTFS, GTFS-RT și GBFS explică contextul datelor.

Pregătește integrarea în producție

Declanșează căutările când poziția sau filtrele se modifică util. Grupează apelurile identice, stabilește un timeout și adaptează cache-ul tipului de date și condițiilor serviciului.

O listă de locuri și o disponibilitate în timp real nu au aceleași cerințe de prospețime. Validează parcursul cu răspunsuri complete, goale, parțiale și în eroare înainte de a prezenta căutarea utilizatorilor.

Extindeți căutarea la serviciile urbane

Stațiile și serviciile urbane utilizează rute distincte. Pentru a căuta toalete în jurul aceluiași punct, ruta GET /v1/services/nearby așteaptă lat și lon, cu types=toilets. Nu trimiteți modes=toilets către această rută: acest vocabular aparține URL-ului hărții, nu filtrului Servicii.

Următorul exemplu JavaScript construiește un URL Servicii pentru o rază de 600 metri. Nu declanșează cererea; reutilizați controalele HTTP și de contract descrise mai sus. Colecția așteptată devine services, în loc de stations. Păstrați service_type, location, distance_meters și atributele realmente prezente.

Contractul REST documentează în mod special toilets, drinking_water, fountain, wifi, parking, charging, aed și locker. Tipurile expuse de MCP pot diferi. Pentru parametrii acceptați, limitele și restricțiile accesului dvs., consultați schema interfeței folosite.

Atributele unui serviciu nu garantează că acesta este deschis în momentul căutării. O accesibilitate necunoscută nu echivalează cu un serviciu inaccesibil; o listă goală rezultată în urma unei erori nu dovedește lipsa toaletelor. Păstrați datele specifice fiecărei familii în loc să le reduceți la un nume și un punct.

Pentru o hartă combinată, asociați rezultatele cu familia și identificatorii lor. Afișați o eroare Servicii fără a șterge stațiile returnate de Transit. Căutarea rămâne centrată pe același punct, dar statusurile și acoperirile pot fi diferite.

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

Diagnosticarea unei căutări goale sau cu eroare

Integrarea directă a unei hărți filtrate într-un site

Construirea unui asistent bazat pe aceste căutări

Întrebări frecvente

Nearby oferă următoarele plecări?

Nu în contractul prezentat aici. Această rută descoperă locuri de transport; plecările cer o capacitate distinctă.

Se poate afișa o listă goală după o eroare?

Prezintă o indisponibilitate. O eroare nu demonstrează absența stațiilor.

Se poate plasa tokenul API în browser?

Un secret trebuie să rămână pe server. Folosește modelul de acces prevăzut pentru aplicația și contul tău.