Per cercare fermate attorno a un punto, trasmetti la sua latitudine, longitudine e un raggio a una API di prossimità. Controlla poi lo stato della risposta, le entità restituite e le informazioni di copertura prima di mostrare la lista o la mappa.
Nel contratto ROOTE roote-1.0.0, il percorso GET /v1/transit/nearby scopre i luoghi di trasporto vicini. Non recupera le partenze né gli avvisi in tempo reale. La ricerca di un luogo e la ricerca del suo prossimo passaggio sono due operazioni distinte.
Definisci i parametri
La richiesta usa lat per la latitudine e lng per la longitudine. L’alias lon è anch’esso descritto nel contratto. Il parametro radius indica il raggio in metri; limit limita il numero di risultati richiesti. Il filtro modes può specificare i mezzi di trasporto.
| Parametro | Esempio | Significato |
|---|---|---|
| lat | 44.8378 | Latitudine del punto di ricerca |
| lng | -0.5792 | Longitudine del punto di ricerca |
| radius | 600 | Raggio richiesto in metri |
| limit | 10 | Limite richiesto di risultati |
| modes | bus,tram | Mezzi ricercati |
Queste coordinate servono da esempio di ricerca a Bordeaux; non indicano una fermata garantita. Consulta il contratto OpenAPI ROOTE per i limiti, i campi e le condizioni attuali.
Trova le fermate intorno a te.
Esplora le fermate registrate attorno a una città o alla tua posizione. Consulta il dettaglio per verificare i mezzi e le informazioni disponibili.
Invia una prima richiesta lato server
Ecco un esempio JavaScript per un ambiente Node.js con fetch. Il token, se il tuo accesso lo richiede, resta in una variabile di ambiente lato server. L’esempio non necessita di mettere un segreto nel 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
};
}
Il contratto consultato prevede un accesso anonimo o tramite token, secondo le politiche applicabili. Verifica i tuoi diritti e i limiti di accesso. Una risposta HTTP corretta non solleva dall’obbligo di validarne il contenuto; in produzione usa anche una validazione degli oggetti contro lo schema.
Leggi le entità e le loro relazioni
La collezione stations contiene i luoghi restituiti. Per ciascuno, consulta in particolare id, name, entity_kind, location e distance_meters. I riferimenti line_ids e operator_ids permettono di associare le collezioni lines e operators quando sono presenti.
Mostra una distanza geografica come tale. Non la trasformare in tempo a piedi senza calcolo d’itinerario. La guida trovare una fermata vicina spiega perché gli accessi possono modificare lo spostamento reale.
Gestisci anche le informazioni ignote esplicitamente. Nel contratto, accessibility.wheelchair può valere unknown: questo valore non equivale né a yes né a no. Una capacità di partenze annunciate non costituisce una lista di partenze.
Mostra una lista o una mappa
Usa l’identificativo per stabilizzare gli elementi dell’interfaccia, il nome per la loro etichetta e location per la loro posizione. Associa le linee tramite riferimenti, piuttosto che avvicinando i loro nomi.
Se mostri i colori delle linee o etichette provenienti dai dati, trattali come input esterni da convalidare. Per i nomi, usa testo piuttosto che HTML iniettato.
Conserva le attribuzioni delle fonti e mostra quelle che il contratto indica come obbligatorie.
Gestisci risultato vuoto, risposta parziale ed errore
Un risultato empty descrive una ricerca senza risultato restituito nel perimetro conosciuto. Non prova l’assenza fisica di trasporti. Una risposta partial può contenere luoghi utili segnalando però limiti: presenta i risultati e l’avviso adeguato.
Leggi coverage, warnings e i limiti applicati in meta. Una lista troncata non descrive una copertura esaustiva. In caso di errore di rete o HTTP, mostra un’indisponibilità, senza sostituire il risultato con « nessuna fermata ».
Per un codice 429, consulta le istruzioni di ripresa e eventuali header del servizio. Evita tentativi in loop.
Distingui stazioni, zone e banchine
Il campo entity_kind distingue vari livelli di luoghi. Due risultati vicini possono corrispondere a banchine distinte; due nomi simili possono appartenere a fonti diverse.
Non fusionare automaticamente i luoghi solo per prossimità. Usa le relazioni e le identità documentate dal servizio. La nostra guida GTFS, GTFS-RT e GBFS spiega il contesto dei dati.
Prepara l’integrazione in produzione
Attiva le ricerche quando la posizione o i filtri cambiano utilmente. Raggruppa le chiamate identiche, definisci un timeout e adatta la cache al tipo di dato e alle condizioni del servizio.
Una lista di luoghi e una disponibilità in tempo reale non hanno le stesse esigenze di freschezza. Verifica il percorso con risposte complete, vuote, parziali ed errore prima di mostrare la ricerca agli utenti.
Estendere la ricerca ai servizi urbani
Le fermate e i servizi urbani utilizzano percorsi distinti. Per cercare toilettes attorno allo stesso punto, il percorso GET /v1/services/nearby richiede lat e lon, con types=toilets. Non inviare modes=toilets a questo percorso: questo vocabolario appartiene all’URL della mappa, non al filtro Servizi.
L’esempio JavaScript seguente costruisce un URL per i Servizi con un raggio di 600 metri. Non avvia la richiesta; riutilizza i controlli HTTP e di contratto descritti sopra. La collezione attesa diventa services invece di stations. Mantieni service_type, location, distance_meters e gli attributi effettivamente presenti.
Il contratto REST documenta in particolare toilets, drinking_water, fountain, wifi, parking, charging, aed e locker. I tipi esposti dal MCP possono differire. Per i parametri accettati, i loro limiti e le restrizioni del tuo accesso, consulta lo schema dell’interfaccia usata.
Gli attributi di un servizio non garantiscono la sua apertura al momento della ricerca. Un’accessibilità sconosciuta non equivale a un servizio inaccessibile; una lista vuota causata da un errore non dimostra l’assenza di toilettes. Conserva i dati specifici di ogni famiglia invece di ridurli a un nome e un punto.
Per una mappa combinata, associa i risultati alla loro famiglia e ai loro identificativi. Mostra un errore Servizi senza cancellare le fermate restituite da Transito. La ricerca rimane centrata sullo stesso punto, ma gli stati e le coperture possono essere differenti.
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());Diagnosticare una ricerca vuota o in errore
Integrare direttamente una mappa filtrata in un sito
Costruire un assistente attorno a queste ricerche
Domande frequenti
Nearby fornisce le prossime partenze?
Non nel contratto presentato qui. Questo percorso scopre i luoghi di trasporto; le partenze richiedono una capacità distinta.
Si può mostrare una lista vuota dopo un errore?
Mostra una indisponibilità. Un errore non dimostra l’assenza di fermate.
Si può mettere il token API nel browser?
Un segreto deve restare lato server. Usa il modello di accesso previsto per la tua applicazione e il tuo account.