BCycle Map is a Cloudflare-native application that polls BCycle GBFS feeds every 5 minutes, accumulates historical snapshots in R2 parquet, and serves a real-time map and analytics dashboard built with React and MapLibre GL. You deploy it once, configure it inDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/samgutentag/bcycle-map/llms.txt
Use this file to discover all available pages before exploring further.
systems.json, and it runs indefinitely — entirely on the Cloudflare free tier.
Quickstart
Clone the repo, install dependencies, and have the map running locally in minutes.
Architecture
Understand the poller, read API, KV hot path, and R2 parquet cold path.
Map Views
Explore the Live Map, Flow Map, Route Check, Explore, and Station Details views.
API Reference
Full reference for every HTTP endpoint served by the read API Worker.
What BCycle Map gives you
BCycle Map bridges the gap between GBFS’s “current state only” data model and the historical and analytical views that make bike-share data useful. The system has two asymmetric data paths:- Hot path — The live map fetches the latest station snapshot from Cloudflare KV via the read API Worker. Requests are served from the edge with a 60-second cache, so load is absorbed without hitting the underlying KV store.
- Cold path — Historical queries go directly from the browser to R2 parquet using DuckDB-WASM. No API call, no backend database — the browser is the database.
Configure Systems
Add or disable BCycle networks by editing a single
systems.json file.Deploy Workers
Deploy the three Cloudflare Workers — poller, read API, and smoke test.
GitHub Actions
Set up hourly parquet compaction and automatic worker deploys on push.
Local Development
Run the full stack locally with Miniflare, including seeding test data.
How it works
GBFS polling
A scheduled Cloudflare Worker fires every 5 minutes, fetches the BCycle GBFS feed, normalises it through an anti-corruption layer, and writes the latest snapshot to KV.
Intra-hour buffering
Each snapshot is appended to an intra-hour buffer in KV. Every 3 hours a GitHub Actions cron job seals those buffers into Hive-partitioned parquet files in R2.
Live map reads
The React frontend polls
GET /api/systems/:id/current every 60 seconds. The read API Worker serves the response from KV with a 60-second edge cache.BCycle Map runs entirely on the Cloudflare free tier. The 5-minute polling cadence produces 288 KV writes per system per day, well under the 1,000 writes/day free-tier cap.