Per mostrare la disponibilità delle bici in tempo reale in un’app, associa il numero restituito alla sua freschezza e alle possibilità di ritiro del veicolo. Un’osservazione descrive ciò che la fonte conosceva in un attimo; non garantisce che una bici sia ancora presente all’arrivo.
Il contratto di mobilità ROOTE distingue stazioni, veicoli individuali e i loro stati. L’interfaccia deve tradurre queste differenze senza confondere un valore sconosciuto, una stazione vuota e una fonte temporaneamente non disponibile.
Distinguere una stazione da un veicolo individuale
Una stazione può esporre contatori di bici e posti per il ritorno. Un veicolo individuale ha uno stato di disponibilità e altre informazioni eventuali. Evita di contare una stazione come una bici o di sommare contatori che rappresentano lo stesso stock.
Nel DTO di mobilità ROOTE, availability.bikes e availability.docks possono essere sconosciuti. I campi di propulsione o batteria devono essere mostrati solo se esistono e sono interpretati secondo il contratto.
Leggere la freschezza e i timestamp
| Campo | Interpretazione |
|---|---|
| freshness.state | Stato dichiarato: fresh, stale, unknown o static |
| freshness.source_updated_at | Data di aggiornamento della fonte, se nota |
| freshness.received_at | Data di ricezione indicata dal contratto |
| freshness.expires_at | Scadenza di validità indicata, se nota |
| availability.bikes | Quantità nota o valore sconosciuto |
| pickup.enabled e pickup.state | Informazioni sul ritiro di una bici alla stazione |
L’ora della tua chiamata non corrisponde automaticamente a quella dell’osservazione. Un risultato ricevuto alle 10 può contenere una fonte aggiornata alle 9:45. Non mostrare “aggiornato ora” basandoti solo sull’ora di ricezione nell’interfaccia.
Prevedere stati di visualizzazione distinti
| Dato ricevuto | Visualizzazione da prevedere |
|---|---|
| Quantità nota e dato fresco | Quantità osservata e indicazione temporale |
| Quantità pari a zero | Nessuna bici osservata, con contesto temporale |
| Quantità null | Disponibilità sconosciuta |
| Stato stale o scadenza superata | Dato obsoleto; suggerire un aggiornamento |
| pickup.enabled=false | Ritiro non disponibile anche se un contatore è positivo |
| Errore di ricerca | Disponibilità momentaneamente non disponibile, senza convertire in zero |
Non considerare uno stato unknown o static come fresco. Una informazione di stazione può essere stabile mentre il contatore cambia rapidamente. Mantieni anche avvertimenti e attribuzioni richieste dalla risposta.
Un esempio di normalizzazione prima della visualizzazione
La seguente funzione produce uno stato di presentazione da una stazione già validata contro lo schema ROOTE. Non è un validatore completo della risposta. Le etichette visibili devono provenire dalle chiavi di traduzione della tua interfaccia.
function availabilityView(station, now = Date.now()) {
const freshness = station.freshness;
const expiresAt = freshness.expires_at
? Date.parse(freshness.expires_at) : null;
const expired = expiresAt !== null &&
Number.isFinite(expiresAt) && expiresAt <= now;
if (station.pickup.enabled === false ||
station.pickup.state === 'unavailable_now') {
return { state: 'pickup_unavailable', count: null };
}
if (expired || freshness.state === 'stale') {
return { state: 'stale', count: null };
}
const count = station.availability.bikes;
if (freshness.state !== 'fresh' || count === null ||
!Number.isFinite(count) || count < 0) {
return { state: 'unknown', count: null };
}
return {
state: count === 0 ? 'empty' : 'observed', count,
sourceUpdatedAt: freshness.source_updated_at,
receivedAt: freshness.received_at,
pickupState: station.pickup.state
};
}Anche con uno stato observed, non trasformare pickupState=unknown in ritiro confermato. Il contatore resta un’osservazione. Mostra il contesto di ritiro se il tuo prodotto aiuta l’utente a scegliere una stazione.
Aggiornare senza moltiplicare inutilmente le chiamate
Adatta l’aggiornamento alla scadenza pubblicata, alle condizioni del servizio e al comportamento dell’utente. Raggruppa le richieste identiche, evita chiamate in background su una pagina inattiva e annulla quelle di una ricerca sostituita.
Un tempo locale di cache non prova la freschezza della fonte. Dopo un errore, puoi mantenere un’ultima osservazione datata se la tua interfaccia la presenta esplicitamente come vecchia. Non cancellare questa distinzione al primo successo se la fonte resta stale.
Comprendere la relazione con GBFS
GBFS descrive i servizi di mobilità condivisa e i loro stati pubblicati. Un’integrazione diretta deve interpretare i file, la versione e i timestamp del feed. Con un’API normalizzata, usa il contratto API; non aggiungere un campo GBFS supposto assente nella risposta.
Scegliere tra GTFS, GTFS Realtime e GBFS
Testare situazioni che ingannano l’utente
Testa uno zero reale, un valore sconosciuto, una scadenza superata, un ritiro disabilitato e un errore dopo un risultato valido. Verifica anche i fusi orari di visualizzazione. Un contatore positivo non deve mai produrre “bici riservata” e una indisponibilità non deve mai produrre uno zero inventato.
Gestire risposte vuote ed errori
Applicare queste regole in un assistente IA
Guida utente per trovare una bici
Domande frequenti
Una quantità positiva garantisce una bici al mio arrivo?
No. Descrive un’osservazione, che può cambiare tra la ricerca e il tuo arrivo.
Si può sostituire null con zero?
No. null indica un valore sconosciuto; zero è una quantità nota e ha un altro significato.
Bisogna aggiornare ogni pochi secondi?
Usa le indicazioni di validità, i limiti del servizio e le esigenze della tua interfaccia. Una frequenza arbitraria non garantisce una fonte più fresca.