Um die Echtzeit-Fahrradverfügbarkeit in einer App anzuzeigen, verbinden Sie die ausgegebene Anzahl mit deren Aktualität und den Abholmöglichkeiten des Fahrzeugs. Eine Beobachtung beschreibt, was die Quelle zu einem Zeitpunkt wusste; sie garantiert nicht, dass ein Fahrrad bei Ankunft noch vorhanden ist.
Der Mobilitätsvertrag ROOTE unterscheidet Stationen, einzelne Fahrzeuge und deren Zustände. Die Schnittstelle muss diese Unterschiede klar darstellen, ohne einen unbekannten Wert, eine leere Station und eine vorübergehend nicht verfügbare Quelle zu verwechseln.
Trennung zwischen Station und individuellem Fahrzeug
Eine Station kann Zähler für Fahrräder und Rückgabeplätze bereitstellen. Ein einzelnes Fahrzeug hat einen Verfügbarkeitsstatus und weitere mögliche Informationen. Vermeiden Sie es, eine Station als Fahrrad zu zählen oder Zähler für denselben Bestand zu addieren.
Im ROOTE Mobilitäts-Datenobjekt können availability.bikes und availability.docks unbekannt sein. Antriebs- oder Batteriefelder dürfen nur gezeigt werden, wenn sie existieren und gemäß Vertrag interpretiert werden.
Aktualität und Zeitstempel lesen
| Feld | Interpretation |
|---|---|
| freshness.state | Angezeigter Zustand: fresh, stale, unknown oder static |
| freshness.source_updated_at | Bekanntes Aktualisierungsdatum der Quelle |
| freshness.received_at | Nach Vertrag angegebener Empfangszeitpunkt |
| freshness.expires_at | Bekanntes Ablaufdatum der Gültigkeit |
| availability.bikes | Bekannte Menge oder unbekannter Wert |
| pickup.enabled und pickup.state | Informationen zur Fahrradabholung an der Station |
Die Zeit Ihres Aufrufs ist nicht automatisch der Zeitpunkt der Beobachtung. Ein Ergebnis, das um 10 Uhr empfangen wird, kann eine Quelle enthalten, die um 9:45 Uhr aktualisiert wurde. Zeigen Sie nicht „gerade jetzt aktualisiert“ allein anhand der Empfangszeit Ihrer Schnittstelle an.
Unterschiedliche Anzeigezustände vorsehen
| Empfangene Daten | Anzuzeigende Darstellung |
|---|---|
| Bekannte Menge und frische Daten | Beobachtete Menge mit zeitlicher Anzeige |
| Menge gleich null | Kein Fahrrad beobachtet mit entsprechendem Zeitkontext |
| Menge null | Unbekannte Verfügbarkeit |
| Stale-Zustand oder abgelaufenes Ablaufdatum | Alte Daten; Aktualisierung vorschlagen |
| pickup.enabled=false | Abholung nicht möglich auch wenn Zähler positiv ist |
| Suchfehler | Vorübergehend nicht verfügbare Verfügbarkeit, ohne in Null umzuwandeln |
Behandeln Sie unknown oder static Zustände nicht als frisch. Eine Stationsinformation kann stabil sein, während der Zähler sich schnell ändert. Behalten Sie auch Warnungen und erforderliche Zusätze aus der Antwort bei.
Ein Beispiel für Normalisierung vor der Darstellung
Die folgende Funktion erzeugt einen Darstellungszustand aus einer Station, die bereits gegen das ROOTE-Schema validiert wurde. Sie ist kein vollständiger Antwort-Validator. Sichtbare Beschriftungen sollten aus den Übersetzungsschlüsseln Ihrer Schnittstelle stammen.
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
};
}Auch bei observed-Zustand wandeln Sie pickupState=unknown nicht in eine bestätigte Abholung. Der Zähler bleibt eine Beobachtung. Zeigen Sie den Abholkontext an, wenn Ihr Produkt den Nutzer bei der Wahl einer Station unterstützt.
Erneuerung ohne unnötig viele Anfragen
Passen Sie das Auffrischen an die veröffentlichte Ablaufzeit, Servicebedingungen und Nutzerverhalten an. Fassen Sie identische Anfragen zusammen, vermeiden Sie Hintergrundaufrufe auf inaktiven Seiten und brechen Sie durch neue Suche ersetzte Anfragen ab.
Ein lokaler Cache-Zeitraum beweist nicht die Aktualität der Quelle. Nach einem Fehler können Sie eine zuletzt datierte Beobachtung behalten, wenn Ihre Schnittstelle sie ausdrücklich als alt darstellt. Löschen Sie diese Unterscheidung nicht beim ersten erfolgreichen Abruf, wenn die Quelle weiterhin stale ist.
Zusammenhang mit GBFS verstehen
GBFS beschreibt geteilte Mobilitätsdienste und deren veröffentlichte Zustände. Eine direkte Integration muss Dateien, Version und Zeitstempel des Feeds interpretieren. Verwenden Sie bei standardisierter API den API-Vertrag; fügen Sie kein GBFS-Feld hinzu, das in der Antwort eigentlich fehlt.
Wahl zwischen GTFS, GTFS Realtime und GBFS
Tests bei irreführenden Situationen
Testen Sie echten Nullwert, unbekannte Werte, abgelaufene Zeit, deaktivierte Abholung und Fehler nach gültigem Ergebnis. Prüfen Sie auch Anzeigezeitzonen. Ein positiver Zähler darf niemals „Fahrrad reserviert“ erzeugen und Verfügbarkeit darf nie in erfundenes Null umgewandelt werden.
Leere Antworten und Fehler behandeln
Regeln in einem KI-Assistenten anwenden
Benutzerleitfaden zum Finden eines Fahrrads
Häufige Fragen
Garantiert eine positive Menge ein Fahrrad bei meiner Ankunft?
Nein. Sie beschreibt eine Beobachtung, die sich zwischen Suche und Ankunft ändern kann.
Kann man null durch Null ersetzen?
Nein. null zeigt einen unbekannten Wert an; Null ist eine bekannte Menge und hat eine andere Bedeutung.
Soll man alle paar Sekunden aktualisieren?
Nutzen Sie Gültigkeitsangaben, Servicebeschränkungen und Bedürfnisse Ihrer Schnittstelle. Eine willkürliche Frequenz garantiert keine frischere Quelle.