För att visa cyklars tillgänglighet i realtid i en app, koppla det angivna antalet till dess aktualitet och möjligheten att ta fordonet. En observation beskriver vad källan visste vid ett givet ögonblick; den garanterar inte att en cykel fortfarande finns när du anländer.
Mobilitetsavtalet ROOTE skiljer på stationer, enskilda fordon och deras status. Gränssnittet måste översätta dessa skillnader utan att blanda ihop ett okänt värde, en tom station och en temporärt otillgänglig källa.
Särskilj en station från ett enskilt fordon
En station kan visa räknare för cyklar och återlämningsplatser. Ett enskilt fordon har en tillgänglighetsstatus och eventuell annan information. Undvik att räkna en station som en cykel eller att summera räknare som representerar samma lager.
I ROOTE:s DTO för mobilitet kan availability.bikes och availability.docks vara okända. Fälten för drivning eller batteri ska bara visas om de finns och tolkas enligt avtalet.
Läs aktualitet och tidsstämplar
| Fält | Tolkning |
|---|---|
| freshness.state | Angett tillstånd: fresh, stale, unknown eller static |
| freshness.source_updated_at | Datum för uppdatering från källan, om känt |
| freshness.received_at | Mottagningsdatum enligt avtalet |
| freshness.expires_at | Angiven giltighetstid, om känd |
| availability.bikes | Känt antal eller okänt värde |
| pickup.enabled och pickup.state | Information om att ta en cykel vid stationen |
Tidpunkten för din förfrågan är inte automatiskt tidpunkten för observationen. Ett resultat mottaget kl. 10 kan innehålla en källa uppdaterad kl. 9:45. Visa inte "uppdaterad nu" baserat enbart på mottagningstiden för ditt gränssnitt.
Förutse olika visningslägen
| Mottagen data | Förväntad visning |
|---|---|
| Känt antal och färsk data | Observerad mängd med tidsangivelse |
| Mängd lika med noll | Ingen cykel observerad, med tidskontext |
| Mängd null | Tillgänglighet okänd |
| Tillstånd stale eller passerat giltighetsdatum | Gammal data; föreslå uppdatering |
| pickup.enabled=false | Upptagning otillgänglig även om räknaren är positiv |
| Sökfel | Tillgänglighet tillfälligt otillgänglig, räkna inte om till noll |
Klassificera inte ett tillstånd som unknown eller static som färskt. Stationens information kan vara stabil medan räknaren ändras snabbt. Behåll även varningar och attribut som krävs av svaret.
Ett exempel på normalisering före visning
Följande funktion skapar ett visningstillstånd utifrån en station redan validerad mot ROOTE-schema. Den är inte en fullständig validerare av svar. Synliga etiketter bör komma från dina gränssnittets översättningsnycklar.
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
};
}Även med ett observed-tillstånd, omvandla inte pickupState=unknown till bekräftad upptagning. Räknaren är fortfarande en observation. Visa upptagningskontexten om din produkt hjälper användaren att välja station.
Uppdatera utan onödiga flera anrop
Anpassa uppdateringen efter angiven utgångstid, servicens villkor och användarens beteende. Gruppera identiska förfrågningar, undvik bakgrundsanrop på inaktiva sidor och avbryt ersatta sökningar.
En lokal cachefördröjning bevisar inte källans aktualitet. Efter ett fel kan du behålla en senaste observation med datum om ditt gränssnitt uttryckligen visar den som gammal. Ta inte bort denna distinktion vid första lyckade återhämtning om källan är stale.
Förstå kopplingen till GBFS
GBFS beskriver delade mobilitetstjänster och deras publicerade status. Direkt integration måste tolka filer, version och flödestidsstämplar. Med ett standardiserat API, använd API-avtalet; lägg inte till ett antaget saknat GBFS-fält i dess svar.
Välja mellan GTFS, GTFS Realtime och GBFS
Testa situationer som kan vilseleda läsaren
Testa verkligt nollvärde, okänt värde, utgången giltighet, inaktiverad upptagning och fel efter giltigt resultat. Kontrollera också visningens tidszoner. En positiv räknare bör aldrig visa "cykel reserverad" och otillgänglighet bör aldrig visa påhittad noll.
Tillämpa dessa regler i en AI-assistent
Användarguide för att hitta en cykel
Vanliga frågor
Garanterar ett positivt antal en cykel vid mitt ankomst?
Nej. Det beskriver en observation som kan ändras mellan sökningen och din ankomst.
Kan man ersätta null med noll?
Nej. Null anger ett okänt värde; noll är ett känt antal och har annan betydelse.
Behöver man uppdatera varannan sekund?
Använd giltighetsangivelser, servicens begränsningar och ditt gränssnitts behov. En godtycklig frekvens garanterar inte färskare källa.