Hur man söker närliggande kollektivtrafikhållplatser med en API?

För att söka efter hållplatser runt en punkt, skicka dess latitud, longitud och en radie till en närhets-API. Kontrollera sedan svarstatus, returnerade enheter och täckningsinformation innan listan eller kartan visas.

I ROOTE-kontraktet roote-1.0.0, upptäcker GET /v1/transit/nearby transportplatser i närheten. Den hämtar inte avgångar eller realtidsvarningar. Sökning av en plats och sökning efter nästa passage är två separata operationer.

Ange parametrar

Förfrågan använder lat för latitud och lng för longitud. Aliaset lon beskrivs också i kontraktet. Parametern radius anger radien i meter; limit begränsar antalet begärda resultat. Filtret modes kan specificera transportmedel.

Dessa koordinater används som exempel för sökning i Bordeaux; de anger inte en garanterad hållplats. Se ROOTE OpenAPI-kontraktet för aktuella gränser, fält och villkor.

Skicka en första förfrågan från serversidan

Här är ett JavaScript-exempel för en Node.js-miljö med fetch. Token, om ditt åtkomst använder en, lagras i en miljövariabel på serversidan. Exemplet kräver ingen hemlighet i webbläsaren.

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

Det använda kontraktet möjliggör anonym eller token-baserad åtkomst beroende på gällande policyer. Kontrollera dina rättigheter och åtkomstbegränsningar. Ett korrekt HTTP-svar innebär inte att dess innehåll är giltigt; i produktion, använd även validering av objekt mot schemat.

Läs enheter och deras relationer

Samlingen stations innehåller de returnerade platserna. För varje, kolla särskilt id, name, entity_kind, location och distance_meters. Referenserna line_ids och operator_ids möjliggör koppling till samlingarna lines och operators när de finns.

Visa ett geografiskt avstånd som ett sådant. Omvandla det inte till gångtid utan ruttberäkning. Guiden hitta en närliggande hållplats förklarar varför tillgängligheten kan ändra den verkliga resan.

Behandla även okänd information explicit. I kontraktet kan accessibility.wheelchair vara unknown: detta värde motsvarar varken yes eller no. En annonserad avgångskapacitet är ingen lista över avgångar.

Visa lista eller karta

Använd id för att stabilisera gränssnittselement, namn för etiketter och location för position. Koppla linjer via referenserna istället för att matcha namn.

Om du visar färger eller etiketter från data, behandla dem som extern input att validera. Använd text för namn istället för injicerad HTML.

Behåll källornas tillskrivningar och visa de som kontraktet kräver.

Hantera tomt resultat, partiellt svar och fel

Ett resultat empty beskriver en sökning utan resultat inom känd räckvidd. Det bevisar inte fysisk frånvaro av transporter. Ett partial svar kan innehålla användbara platser samtidigt som det signalerar begränsningar: visa resultaten och lämplig varning.

Läs coverage, warnings och tillämpade begränsningar i meta. En avkortad lista är inte en komplett täckning. Vid nätverks- eller HTTP-fel, visa otillgänglighet utan att ersätta med ”inga hållplatser”.

Vid kod 429, se återupptagningsanvisningar och eventuella tjänsthuvuden. Undvik oändliga omförsök.

Skillnad på hållplatser, zoner och perronger

Fältet entity_kind skiljer flera platsnivåer. Två närliggande resultat kan motsvara olika perronger; två liknande namn kan tillhöra olika källor.

Slå inte automatiskt ihop platser enbart på närhet. Använd relationer och identiteter dokumenterade av tjänsten. Vår guide GTFS, GTFS-RT och GBFS förklarar datakontexten.

Förbered produktionsintegration

Starta sökningar när position eller filter ändras relevant. Gruppera identiska anrop, definiera timeout och anpassa cache efter datatyp och tjänsteförhållanden.

En platslista och realtidsdata har olika krav på färskhet. Validera flödet med kompletta, tomma, partiella och felaktiga svar innan presentation till användare.

Utöka sökningen till stadsservice

Hållplatser och stadsservice använder separata vägar. För att söka toaletter runt samma punkt, använder GET-vägen /v1/services/nearby lat och lon, med types=toilets. Skicka inte modes=toilets till denna väg: detta vokabulär hör till kart-URL:en, inte till Service-filter.

Följande JavaScript-exempel bygger en URL för Services med en radie på 600 meter. Den startar inte förfrågan; återanvänd HTTP- och kontraktskontrollerna som beskrivs ovan. Den förväntade samlingen blir services istället för stations. Behåll service_type, location, distance_meters och de attribut som faktiskt finns.

REST-kontraktet dokumenterar bland annat toilets, drinking_water, fountain, wifi, parking, charging, aed och locker. Typerna som exponeras av MCP kan variera. För godkända parametrar, gränser och dina åtkomstbegränsningar, se det använda gränssnittets schema.

Ett servicens attribut garanterar inte att den är öppen vid söktillfället. Okänd tillgänglighet betyder inte otillgänglighet; en tom lista på grund av ett fel bevisar inte att det inte finns toaletter. Behåll data specifika för varje familj istället för att reducera dem till ett namn och en punkt.

För en kombinerad karta, koppla resultaten till deras familj och identifierare. Visa ett Services-fel utan att radera hållplatser som Transit returnerat. Sökningen förblir centrerad på samma punkt, men status och täckning kan skilja sig.

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

Diagnostisera en tom eller felfylld sökning

Integrera direkt en filtrerad karta på en webbplats

Bygg en assistent runt dessa sökningar

Vanliga frågor

Ger Nearby nästa avgångar?

Inte i det här presenterade kontraktet. Denna rutt upptäcker transportplatser; avgångar kräver en separat kapacitet.

Kan man visa en tom lista efter ett fel?

Visa otillgänglighet. Ett fel bevisar inte frånvaro av hållplatser.

Kan API-token placeras i webbläsaren?

En hemlighet måste stanna på serversidan. Använd det åtkomstmönster som din applikation och konto kräver.