Hvordan søger man efter nærmeste transportstop med et API?

For at søge efter stop omkring et punkt sender du dets breddegrad, længdegrad og en radius til et lokaliserings-API. Derefter tjekker du svarets status, de returnerede enheder og dækningsoplysninger, før du viser listen eller kortet.

I ROOTE-kontrakten roote-1.0.0 giver GET /v1/transit/nearby ruten mulighed for at finde transportsteder i nærheden. Den henter ikke afgange eller realtidsalarmer. Søgning efter et sted og søgning efter dets næste passage er to separate operationer.

Definer parametrene

Forespørgslen bruger lat for breddegrad og lng for længdegrad. Aliaset lon er også beskrevet i kontrakten. Parameteren radius udtrykker radius i meter; limit sætter en grænse for antal ønskede resultater. Filteret modes kan specificere transportformer.

Disse koordinater er et søgeeksempel for Bordeaux; de garanterer ikke et specifikt stop. Se ROOTE OpenAPI-kontrakten for de aktuelle grænser, felter og betingelser.

Send en første forespørgsel på serversiden

Her er et JavaScript-eksempel til et Node.js-miljø med fetch. Token, hvis din adgang kræver det, opbevares som en miljøvariabel på serversiden. Eksemplet kræver ikke hemmeligheder i browseren.

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

Den konsulterede kontrakt tillader anonym adgang eller adgang med token afhængig af gældende politikker. Tjek dine rettigheder og adgangsgrænser. Et korrekt HTTP-svar fritager dig ikke for at validere dets indhold; i produktion bør du også validere objekter mod skemaet.

Læs enhederne og deres relationer

Samlingen stations indeholder de returnerede steder. For hver især, se især id, name, entity_kind, location og distance_meters. Referencerne line_ids og operator_ids gør det muligt at forbinde samlingerne lines og operators, når disse er angivet.

Vis en geografisk afstand som netop en afstand. Omdan den ikke til gangtid uden en ruteudregning. Guiden find et nært stop forklarer hvorfor adgangsveje kan ændre den faktiske bevægelse.

Behandl også ukendte oplysninger eksplicit. I kontrakten kan accessibility.wheelchair være unknown: denne værdi svarer hverken til yes eller no. En angivet afgangskapacitet er ikke en afgangsliste.

Vis en liste eller et kort

Brug id for at stabilisere interfaceelementer, navn til deres etiketter og location til deres position. Forbind linjerne via referencer, ikke ved at matche deres navne.

Hvis du viser linjefarver eller etiketter hentet fra data, behandl dem som eksterne input, der skal valideres. Brug tekst til navne, ikke injiceret HTML.

Bevar kildeangivelser og vis dem, som kontrakten fordrer.

Håndter tomt resultat, delvist svar og fejl

Et resultat empty angiver en søgning uden returnerede resultater inden for kendt område. Det beviser ikke fysisk fravær af transport. Et partial svar kan indeholde brugbare steder, men samtidig advare om begrænsninger: vis resultaterne og den passende advarsel.

Læs coverage, warnings og gældende begrænsninger i meta. En afkortet liste beskriver ikke fuldstændig dækning. Ved netværks- eller HTTP-fejl vis en utilgængelighed, uden at erstatte resultatet med “intet stop”.

Ved kode 429, se genoptagelsesinstruktioner og eventuelle serviceheaders. Undgå løbende gentagelser.

Skil mellem stationer, zoner og perroner

Feltet entity_kind skelner mellem flere niveauer af steder. To naboliggende resultater kan svare til forskellige perroner; to lignende navne kan komme fra forskellige kilder.

Sammenflet ikke automatisk steder baseret kun på nærhed. Brug relationer og identiteter dokumenteret af tjenesten. Vores guide GTFS, GTFS-RT og GBFS forklarer datakonteksten.

Forbered produktionintegration

Ud­løs søgninger når position eller filtre ændres væsentligt. Saml identiske kald, sæt timeout og tilpas cache efter datatyper og serviceforhold.

En liste over steder og realtidsopdateringer har forskellige friskhedskrav. Validér scenarier med komplette, tomme, delvise og fejlede svar, før søgningen præsenteres for brugerne.

Udvid søgningen til byservice

Stoppesteder og byservice benytter forskellige ruter. For at søge efter toiletter omkring samme punkt bruger du GET /v1/services/nearby med lat og lon samt types=toilets. Send ikke modes=toilets til denne rute: dette vokabularium tilhører kort-URL’en, ikke Service-filteret.

Følgende JavaScript-eksempel bygger en URL til Services med en radius på 600 meter. Det udløser ikke forespørgslen; genbrug de HTTP- og kontrolkontroller, der er beskrevet ovenfor. Den forventede samling bliver services i stedet for stations. Behold service_type, location, distance_meters og de faktisk tilstedeværende attributter.

REST-kontrakten dokumenterer bl.a. toilets, drinking_water, fountain, wifi, parking, charging, aed og locker. De typer, MCP eksponerer, kan variere. For accepterede parametre, deres grænser og dine adgangsbegrænsninger, se det anvendte interfaceskema.

Attributterne for en service garanterer ikke, at den er åben på søgetidspunktet. Ukendt tilgængelighed svarer ikke til utilgængelig service; en tom liste som følge af en fejl beviser ikke, at der ikke er toiletter. Bevar data for hver familie i stedet for at samle dem til et navn og punkt.

For et kombineret kort, associer resultaterne med deres familie og ID’er. Vis en Services-fejl uden at slette stoppestederne returneret af Transit. Søgningen er stadig centreret på samme punkt, men status og dækning kan være forskellige.

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

Diagnosticer en tom eller fejlagtig søgning

Integrer et filtreret kort direkte på et website

Byg en assistent baseret på disse søgninger

Ofte stillede spørgsmål

Giver Nearby næste afgange?

Ikke i denne kontrakt. Denne rute finder transportsteder; afgange kræver en separat kapacitet.

Kan man vise en tom liste efter en fejl?

Vis utilgængelighed. En fejl beviser ikke, at stop ikke findes.

Kan API-token placeres i browseren?

En hemmelighed skal forblive på serversiden. Brug adgangsmodellen, der er beregnet til din app og konto.