Sykkeltilgjengelighet i sanntid: hvordan vise det i en app?

For å vise sanntidssykkeltilgjengelighet i en app, knytt antallet som returneres til dets ferskhet og muligheter for å hente kjøretøyet. En observasjon beskriver hva kilden kjente på et gitt øyeblikk; den garanterer ikke at en sykkel fortsatt vil være til stede ved ankomst.

ROOTE mobilitetskontrakten skiller mellom stasjoner, individuelle kjøretøy og deres tilstander. Grensesnittet må håndtere disse forskjellene uten å forveksle en ukjent verdi, en tom stasjon og en midlertidig utilgjengelig kilde.

Skill en stasjon fra et individuelt kjøretøy

En stasjon kan vise antall sykler og ledige plasser for retur. Et individuelt kjøretøy har en tilgjengelighetstilstand og eventuelt annen informasjon. Unngå å telle en stasjon som en sykkel eller å legge sammen telleverk som representerer samme beholdning.

I ROOTE mobilitets-DTO kan availability.bikes og availability.docks være ukjente. Feltene for drivsystem eller batteri skal kun vises hvis de eksisterer og tolkes i henhold til kontrakten.

ROOTE OpenAPI-kontrakt

Les ferskhet og tidsstempler

Tidspunktet for forespørselen din er ikke automatisk tidspunktet for observasjonen. Et resultat mottatt kl. 10 kan inneholde en kilde oppdatert kl. 9:45. Vis ikke «oppdatert nå» basert kun på mottakstid for grensesnittet ditt.

Planlegg ulike visningstilstander

Ikke klassifiser en ukjent (unknown) eller statisk (static) tilstand som fersk. Stasjonsinformasjon kan være stabil mens telleverk endrer seg raskt. Behold også advarsler og påkrevde tilskrivelser i responsen.

Et eksempel på normalisering før visning

Følgende funksjon genererer en presentasjonstilstand fra en stasjon validert mot ROOTE-skjemaet. Den er ikke en fullstendig responsvalidator. Synlige etiketter bør komme fra oversettelsesnøkler i grensesnittet ditt.

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 observed-tilstand, konverter ikke pickupState=unknown til bekreftet henting. Telleverket er fortsatt en observasjon. Vis hentekonteksten hvis produktet ditt hjelper brukeren med å velge stasjon.

Oppdater uten unødvendige gjentakelser av kall

Tilpass oppdateringsfrekvens til publisert utløp, tjenestebetingelser og brukeradferd. Grupper identiske forespørsler, unngå bakgrunnskall på en inaktiv side, og avbryt søk som blir erstattet.

Lokal mellomlagringstid beviser ikke kildens ferskhet. Etter en feil kan du beholde en sist daterte observasjon hvis grensesnittet tydelig viser den som gammel. Ikke slett denne distinksjonen ved første vellykkede nyinnlasting hvis kilden fortsatt er stale.

Forstå koblingen til GBFS

GBFS beskriver delte mobilitetstjenester og deres publiserte tilstander. En direkte integrasjon må tolke filer, versjon og strøm-tidsstempler. Med et standardisert API, bruk API-kontrakten; legg ikke til GBFS-felt antatt fraværende i responsen.

Velge mellom GTFS, GTFS Realtime og GBFS

Test situasjoner som kan villede brukeren

Test ekte null, ukjent verdi, utløpt gyldighet, deaktivert henting og feil etter gyldig resultat. Sjekk også visningstidssoner. Et positivt telleverk skal aldri indikere «reservert sykkel», og utilgjengelighet må aldri fremstilles som oppdiktet null.

Håndtere tomme svar og feil

Bruke disse reglene i en AI-assistent

Brukerveiledning for å finne en sykkel

Ofte stilte spørsmål

Garanti for positiv mengde at en sykkel er tilgjengelig ved ankomst?

Nei. Den beskriver en observasjon som kan endres mellom søk og ankomst.

Kan null erstattes med 0?

Nei. null indikerer ukjent verdi; 0 er en kjent mengde og har en annen betydning.

Bør man oppdatere hvert par sekunder?

Bruk gyldighetsindikasjoner, tjenestebegrensninger og grensesnittbehov. En vilkårlig frekvens garanterer ikke ferskere kilde.