Para mostrar la disponibilidad de bicicletas en tiempo real en una aplicación, asocia la cantidad devuelta con su frescura y las posibilidades de tomar el vehículo. Una observación describe lo que la fuente conocía en un momento dado; no garantiza que una bicicleta seguirá allí a la llegada.
El contrato de movilidad ROOTE distingue las estaciones, los vehículos individuales y sus estados. La interfaz debe reflejar estas diferencias sin confundir un valor desconocido, una estación vacía y una fuente temporalmente indisponible.
Separar una estación de un vehículo individual
Una estación puede mostrar contadores de bicicletas y de plazas para devolución. Un vehículo individual tiene un estado de disponibilidad y otra información eventual. Evita contar una estación como una bicicleta o sumar contadores que representan el mismo stock.
En el DTO de movilidad ROOTE, availability.bikes y availability.docks pueden ser desconocidos. Los campos de propulsión o de batería sólo deben mostrarse si existen y se interpretan según el contrato.
Leer la frescura y las marcas temporales
| Campo | Interpretación |
|---|---|
| freshness.state | Estado anunciado: fresh, stale, unknown o static |
| freshness.source_updated_at | Fecha de actualización de la fuente, si se conoce |
| freshness.received_at | Fecha de recepción indicada por el contrato |
| freshness.expires_at | Fecha de expiración indicada de validez, si se conoce |
| availability.bikes | Cantidad conocida o valor desconocido |
| pickup.enabled y pickup.state | Información sobre la posibilidad de tomar una bici en la estación |
La hora de tu llamada no es automáticamente la de la observación. Un resultado recibido a las 10 h puede contener una fuente actualizada a las 9:45 h. No muestres “actualizado ahora” solamente por la hora de recepción en tu interfaz.
Prever estados de visualización distintos
| Dato recibido | Visualización a prever |
|---|---|
| Cantidad conocida y dato fresco | Cantidad observada e indicación temporal |
| Cantidad igual a cero | Ninguna bicicleta observada, con su contexto temporal |
| Cantidad null | Disponibilidad desconocida |
| Estado stale o expiración superada | Dato antiguo; sugerir actualización |
| pickup.enabled=false | Toma no disponible aunque un contador sea positivo |
| Error de búsqueda | Disponibilidad momentáneamente no disponible, sin convertir a cero |
No clasifiques un estado unknown o static como fresco. Una información de estación puede ser estable mientras el contador evoluciona rápidamente. Conserva también las advertencias y atribuciones requeridas por la respuesta.
Un ejemplo de normalización antes de la representación
La función siguiente produce un estado de presentación a partir de una estación ya validada contra el esquema ROOTE. No es un validador completo de respuesta. Las etiquetas visibles deben provenir de las claves de traducción de tu interfaz.
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
};
}Incluso con un estado observed, no conviertas pickupState=unknown en toma confirmada. El contador sigue siendo una observación. Muestra el contexto de toma si tu producto ayuda al usuario a elegir una estación.
Actualizar sin multiplicar llamadas innecesariamente
Adapta la actualización a la expiración publicada, a las condiciones del servicio y al comportamiento del usuario. Agrupa las solicitudes idénticas, evita las llamadas en segundo plano en una página inactiva y cancela las de una búsqueda que se ha reemplazado.
Un tiempo local de caché no prueba la frescura de la fuente. Tras un error, puedes conservar una última observación fechada si tu interfaz la presenta explícitamente como antigua. No borres esta distinción en el primer éxito si la fuente sigue stale.
Comprender la relación con GBFS
GBFS describe los servicios de movilidad compartida y sus estados publicados. Una integración directa debe interpretar los archivos, la versión y las marcas temporales del flujo. Con una API normalizada, usa el contrato de la API; no añadas un campo GBFS que se supone ausencia en su respuesta.
Elegir entre GTFS, GTFS Realtime y GBFS
Probar situaciones que confunden al lector
Prueba un cero real, un valor desconocido, una expiración superada, una toma desactivada y un error tras un resultado válido. También verifica las zonas horarias de visualización. Un contador positivo nunca debe mostrar “bicicleta reservada” y una indisponibilidad nunca debe mostrar un cero inventado.
Gestionar respuestas vacías y errores
Aplicar estas reglas en un asistente IA
Guía de usuario para encontrar una bicicleta
Preguntas frecuentes
¿Una cantidad positiva garantiza una bici a mi llegada?
No. Describe una observación, que puede cambiar entre la búsqueda y tu llegada.
¿Se puede sustituir null por cero?
No. null indica un valor desconocido; cero es una cantidad conocida y tiene otro significado.
¿Hay que actualizar cada pocos segundos?
Usa indicaciones de validez, límites del servicio y necesidades de tu interfaz. Una frecuencia arbitraria no garantiza una fuente más fresca.