Tilgængelighed af cykler i realtid: hvordan vises det i en app?

For at vise cyklers tilgængelighed i realtid i en app, forbind det returnerede antal med dets friskhed og muligheder for at tage køretøjet. En observation beskriver, hvad kilden vidste på et bestemt tidspunkt; den garanterer ikke, at en cykel stadig er til stede ved ankomst.

ROOTE mobilitetsaftalen skelner mellem stationer, individuelle køretøjer og deres tilstande. Interfacet skal afspejle disse forskelle uden at forveksle en ukendt værdi, en tom station og en midlertidigt utilgængelig kilde.

Adskil en station fra et individuelt køretøj

En station kan vise tællere for cykler og afleveringspladser. Et individuelt køretøj har en tilgængelighedstilstand og eventuelle yderligere oplysninger. Undgå at tælle en station som en cykel eller lægge tællere sammen, der repræsenterer samme lager.

I ROOTE mobilitets DTO kan availability.bikes og availability.docks være ukendte. Felter for fremdrift eller batteri må kun vises, hvis de eksisterer og fortolkes i henhold til aftalen.

ROOTE OpenAPI-kontrakt

Læs friskhed og tidsstempler

Tiden for dit kald er ikke automatisk observationens tidspunkt. Et resultat modtaget kl. 10 kan indeholde en kilde opdateret kl. 9.45. Vis ikke "opdateret nu" baseret alene på modtagelsestidspunktet i dit interface.

Planlæg forskellige visningstilstande

Klassificer ikke en unknown eller static tilstand som frisk. En stationsinformation kan være stabil, mens tælleren ændrer sig hurtigt. Bevar også de advarsler og tildelinger, som svaret kræver.

Et eksempel på normalisering før rendering

Følgende funktion producerer en fremvisningstilstand ud fra en station allerede valideret mod ROOTE-skemaet. Den er ikke en komplet svar-validator. Synlige etiketter skal komme fra oversættelsesnøgler i dit interface.

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

Selv med en observed tilstand, omdann ikke pickupState=unknown til bekræftet tagningsmulighed. Tælleren forbliver en observation. Vis tagningskonteksten, hvis dit produkt hjælper brugeren med at vælge en station.

Opdater uden at forøge unødvendige kald

Tilpas opdateringen til offentliggjort udløbstid, servicevilkår og brugeradfærd. Saml identiske forespørgsler, undgå baggrundskald på en inaktiv side og aflys udskiftede søgninger.

En lokal cache-forsinkelse beviser ikke kildens friskhed. Efter en fejl kan du beholde en sidste dateret observation, hvis dit interface eksplicit viser den som gammel. Slet ikke denne forskel ved den første succesfulde genoptagelse, hvis kilden forbliver stale.

Forstå forbindelse til GBFS

GBFS beskriver delte mobilitetstjenester og deres publicerede tilstande. En direkte integration skal fortolke filer, version og tidsstempler i feedet. Med en standardiseret API brug kontraktens API; tilføj ikke et antaget GBFS-felt, som ikke findes i svaret.

Vælg mellem GTFS, GTFS Realtime og GBFS

Test situationer, som kan villede læseren

Test et virkelig nul, en ukendt værdi, overskredet udløbstid, deaktiveret tagningsmulighed og en fejl efter et gyldigt resultat. Kontroller også visningstidzoner. En positiv tæller må aldrig vise "cykel reserveret" og utilgængelighed må aldrig angribes som opfundet nul.

Håndter tomme svar og fejl

Anvend disse regler i en AI-assistent

Brugervejledning til at finde en cykel

Ofte stillede spørgsmål

Garanti for positiv mængde, at der findes en cykel ved min ankomst?

Nej. Det beskriver en observation, som kan ændre sig mellem søgning og din ankomst.

Kan null erstattes med nul?

Nej. null angiver en ukendt værdi; nul er en kendt mængde og betyder noget andet.

Skal man opdatere hvert par sekunder?

Brug gyldighedsindikatorer, servicens begrænsninger og dit interfacets behov. En vilkårlig frekvens garanterer ikke friske kilder.