Untuk menampilkan ketersediaan sepeda waktu nyata dalam aplikasi, kaitkan jumlah yang dikembalikan dengan kesegarannya serta kemungkinan pengambilan kendaraan. Sebuah pengamatan mendeskripsikan apa yang diketahui sumber pada suatu saat; ini tidak menjamin sepeda masih tersedia saat kedatangan.
Kontrak mobilitas ROOTE membedakan stasiun, kendaraan individual, dan statusnya. Antarmuka harus menerjemahkan perbedaan ini tanpa membingungkan nilai tidak diketahui, stasiun kosong, dan sumber yang sementara tidak tersedia.
Memisahkan stasiun dari kendaraan individual
Sebuah stasiun dapat menampilkan penghitung sepeda dan slot pengembalian. Kendaraan individual memiliki status ketersediaan dan informasi lain yang mungkin ada. Hindari menghitung stasiun sebagai sepeda atau menjumlahkan penghitung yang mewakili stok yang sama.
Dalam DTO mobilitas ROOTE, availability.bikes dan availability.docks dapat tidak diketahui. Kolom propulsi atau baterai hanya boleh ditampilkan jika ada dan diinterpretasikan sesuai kontrak.
Membaca kesegaran dan penandaan waktu
| Kolom | Interpretasi |
|---|---|
| freshness.state | Status yang diumumkan: fresh, stale, unknown, atau static |
| freshness.source_updated_at | Tanggal pembaruan sumber, jika diketahui |
| freshness.received_at | Tanggal penerimaan yang ditentukan oleh kontrak |
| freshness.expires_at | Tanggal kedaluwarsa validitas yang ditentukan, jika diketahui |
| availability.bikes | Jumlah yang diketahui atau nilai tidak diketahui |
| pickup.enabled dan pickup.state | Informasi tentang pengambilan sepeda di stasiun |
Waktu panggilan Anda tidak otomatis sama dengan waktu pengamatan. Hasil yang diterima pukul 10 dapat berisi sumber yang diperbarui pukul 9:45. Jangan tampilkan “baru diperbarui” hanya berdasarkan waktu penerimaan antarmuka Anda.
Sediakan status tampilan yang berbeda
| Data diterima | Tampilan yang harus disiapkan |
|---|---|
| Jumlah diketahui dan data segar | Jumlah yang diamati dan indikasi waktu |
| Jumlah sama dengan nol | Tidak ada sepeda yang diamati, dengan konteks waktu |
| Jumlah null | Ketersediaan tidak diketahui |
| Status stale atau kedaluwarsa | Data lama; sarankan penyegaran |
| pickup.enabled=false | Pengambilan tidak tersedia meskipun penghitung positif |
| Kesalahan pencarian | Ketersediaan sementara tidak tersedia, tanpa mengubah menjadi nol |
Jangan klasifikasikan status unknown atau static sebagai segar. Informasi stasiun mungkin stabil sementara penghitung berubah cepat. Simpan juga peringatan dan atribusi yang diperlukan oleh respons.
Contoh normalisasi sebelum penampilan
Fungsi berikut menghasilkan status tampilan dari stasiun yang sudah divalidasi terhadap skema ROOTE. Ini bukan validator respons lengkap. Label yang terlihat harus berasal dari kunci terjemahan antarmuka Anda.
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
};
}Bahkan dengan status observed, jangan ubah pickupState=unknown menjadi pengambilan yang dikonfirmasi. Penghitung tetap merupakan pengamatan. Tampilkan konteks pengambilan jika produk Anda membantu pengguna memilih stasiun.
Segarkan tanpa menggandakan panggilan secara tidak perlu
Sesuaikan penyegaran dengan kedaluwarsa yang diumumkan, kondisi layanan, dan perilaku pengguna. Gabungkan permintaan identik, hindari panggilan latar belakang pada halaman nonaktif, dan batalkan yang tergantikan oleh pencarian baru.
Penundaan cache lokal tidak membuktikan kesegaran sumber. Setelah kesalahan, Anda boleh menyimpan pengamatan terakhir yang bertanggal jika antarmuka Anda menampilkannya secara eksplisit sebagai lama. Jangan hapus perbedaan ini pada pemulihan pertama jika sumber masih stale.
Memahami hubungan dengan GBFS
GBFS mendeskripsikan layanan mobilitas bersama dan status yang dipublikasikan. Integrasi langsung harus menafsirkan file, versi, dan penandaan waktu aliran. Dengan API standar, gunakan kontrak API; jangan tambah kolom GBFS yang diasumsikan tidak ada dalam responsnya.
Memilih antara GTFS, GTFS Realtime dan GBFS
Uji situasi yang membingungkan pembaca
Uji nol yang sebenarnya, nilai tidak diketahui, kedaluwarsa, pengambilan dinonaktifkan, dan kesalahan setelah hasil valid. Periksa juga zona waktu tampilan. Penghitung positif tidak boleh menghasilkan "sepeda dipesan" dan ketidaktersediaan tidak boleh menghasilkan nol fiktif.
Kelola respons kosong dan kesalahan
Terapkan aturan ini dalam asisten AI
Panduan pengguna untuk menemukan sepeda
Pertanyaan yang sering diajukan
Apakah jumlah positif menjamin sepeda saat saya tiba?
Tidak. Ini menggambarkan pengamatan, yang bisa berubah antara pencarian dan kedatangan Anda.
Bisakah null diganti dengan nol?
Tidak. null menunjukkan nilai tidak diketahui; nol adalah jumlah yang diketahui dan memiliki arti berbeda.
Haruskah menyegarkan setiap beberapa detik?
Gunakan petunjuk validitas, batas layanan, dan kebutuhan antarmuka Anda. Frekuensi sewenang-wenang tidak menjamin sumber yang lebih segar.