Reële tijd beschikbaarheid van fietsen: hoe weergeven in een applicatie?

Om de realtime beschikbaarheid van fietsen in een applicatie weer te geven, koppel het geretourneerde aantal aan de actualiteit en de afnammogelijkheden van het voertuig. Een waarneming beschrijft wat de bron op een moment wist; het garandeert niet dat een fiets bij aankomst nog beschikbaar is.

Het ROOTE mobiliteitscontract onderscheidt stations, individuele voertuigen en hun statussen. De interface moet deze verschillen vertalen zonder een onbekende waarde, een leeg station of tijdelijk onbeschikbare bron te verwarren.

Een station onderscheiden van een individueel voertuig

Een station kan tellers voor fietsen en terugbrengplaatsen tonen. Een individueel voertuig heeft een beschikbaarheidsstatus en mogelijke verdere info. Vermijd stations als fiets te tellen of tellers op te tellen die dezelfde voorraad vertegenwoordigen.

In het ROOTE mobiliteits-DTO kunnen availability.bikes en availability.docks onbekend zijn. Velden voor aandrijving of batterij mogen alleen worden getoond als ze bestaan en worden geïnterpreteerd volgens het contract.

ROOTE OpenAPI contract

Actualiteit en tijdstempels lezen

Het tijdstip van uw oproep is niet automatisch dat van de waarneming. Een resultaat ontvangen om 10 uur kan een bron bevatten die om 9:45 is bijgewerkt. Toon niet 'nu bijgewerkt' alleen op basis van ontvangsttijd in uw interface.

Voorzie verschillende weergavestatussen

Classificeer unknown of static niet als vers. Stationinfo kan statisch zijn terwijl teller snel verandert. Bewaar ook waarschuwingen en toewijzingen vereist door antwoord.

Een voorbeeld van normalisatie voorafgaand aan weergave

De volgende functie produceert een weergavestatus uit een station gevalideerd tegen het ROOTE-schema. Het is geen volledige antwoordvalidator. Zichtbare labels moeten uit vertalingssleutels van uw interface komen.

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

Zelfs met een observed status verander pickupState=unknown niet in bevestigd afnemen. De teller blijft een waarneming. Toon afnamecontext als uw product gebruikers helpt een station te kiezen.

Ververs zonder onnodige meervoudige oproepen

Stem verversing af op gepubliceerde vervaldatum, servicecondities en gebruikersgedrag. Groepeer identieke verzoeken, voorkom achtergrondoproepen op inactieve pagina's en annuleer vervangende zoekopdrachten.

Een lokale cachevertraging bewijst geen bronactualiteit. Na een fout kunt u een laatste gedateerde waarneming bewaren als uw interface deze expliciet als oud toont. Wis deze onderscheiding niet na een eerste succesvolle herhaling als bron stale blijft.

Begrijp de relatie met GBFS

GBFS beschrijft gedeelde mobiliteitsdiensten en hun gepubliceerde statussen. Directe integratie moet bestanden, versie en tijdstempels van de feed interpreteren. Gebruik bij een genormaliseerde API het API-contract; voeg geen GBFS-veld toe dat vermoedelijk afwezig is.

Kiezen tussen GTFS, GTFS Realtime en GBFS

Test situaties die gebruikers kunnen misleiden

Test echte nul, onbekende waarde, verlopen vervaldatum, uitgeschakelde afname en fout na een valide resultaat. Controleer ook tijdzones van weergave. Een positieve teller mag nooit 'fiets gereserveerd' tonen en onbeschikbaarheid nooit een verzonnen nul.

Omgaan met lege antwoorden en fouten

Deze regels toepassen in een AI-assistent

Gebruikershandleiding voor het vinden van een fiets

Veelgestelde vragen

Garandeert een positieve hoeveelheid een fiets bij aankomst?

Nee. Het beschrijft een waarneming die kan veranderen tussen zoeken en aankomst.

Mag null vervangen worden door nul?

Nee. null geeft een onbekende waarde aan; nul is een bekende hoeveelheid met een andere betekenis.

Moet ik elke paar seconden verversen?

Gebruik geldigheidsindicaties, servicebeperkingen en interfacebehoeften. Een willekeurige frequentie garandeert geen frissere bron.