BCycle Map is an open-source, Cloudflare-native application that turns any public GBFS (General Bikeshare Feed Specification) endpoint into a live station map and historical analytics dashboard. Three Cloudflare Workers handle polling, serving, and smoke-testing; Cloudflare KV holds the latest snapshot for sub-second map loads; R2 stores compacted parquet partitions for long-range historical queries; and a React + MapLibre frontend ties it all together — all within the Cloudflare free tier.Documentation 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.
What BCycle Map Does
BCycle Map continuously polls a GBFS feed (defaulting to Santa Barbara BCycle), normalizes the raw JSON into a typed internal shape, and makes that data available through two distinct read paths. The live map route shows real-time station availability with per-station markers colored by bike count. The Explore view lets you query weeks of accumulated history directly in the browser using DuckDB-WASM reading R2 parquet — no backend database required.Live Map
MapLibre GL JS renders 85+ station markers updated every 5 minutes. Markers are colored and sized by available bikes. A staleness badge appears when the data feed is more than 3 minutes old.
Flow Map
Deck.gl ArcLayer visualizes inferred station-to-station trips derived from departure and arrival events detected across successive GBFS snapshots.
Route Check
Look up expected travel time between any two stations using a precomputed travel-time matrix stored in R2. Powered by the Google Maps Directions API run offline by a GitHub Action.
Explore View
DuckDB-WASM queries R2 parquet partitions directly over HTTP. No API call, no server-side database — the browser is the query engine for historical station data.
Trip Inference
The poller detects departure and arrival events by diffing successive snapshots, then pairs them into end-to-end trips using both a conservative single-rider heuristic and a greedy travel-time-matrix matcher.
Leaderboards
GitHub Actions compute per-station popularity rankings, typical weekday-vs-weekend availability profiles, and corridor leaderboards from the accumulated R2 parquet archive.
Tech Stack
| Layer | Tools |
|---|---|
| Frontend | React 18, TypeScript, Vite, Tailwind CSS, MapLibre GL JS, Deck.gl, DuckDB-WASM |
| Workers | Cloudflare Workers (3 scripts: poller, read-api, smoke), Wrangler 4 |
| Storage | Cloudflare KV (latest snapshot + intra-hour buffer), Cloudflare R2 (parquet partitions) |
| Compaction | GitHub Actions cron, parquet-wasm + apache-arrow in Node, @aws-sdk/client-s3 |
| Testing | Vitest, happy-dom, @testing-library/react — 51 tests total |
Who Should Use BCycle Map
BCycle Map is designed for developers who want to:- Self-host a live bike-share map and analytics dashboard for any BCycle GBFS system
- Learn how to build Cloudflare-native applications using Workers, KV, R2, and Pages together
- Extend the platform to additional systems by adding one entry to
systems.json - Analyze bike-share ridership patterns using browser-native DuckDB-WASM against columnar parquet data
enabled flag in systems.json lets you freeze a system’s polling without losing its historical data.
BCycle Map is compatible with the Cloudflare free tier for a single active GBFS system. The poller fires every 5 minutes (288 ticks/day × 2 KV puts = 576 puts/day), leaving roughly 420 puts/day as headroom for activity writes and manual workflow runs — all under the 1 000/day Workers free-tier cap.
Where to Go Next
Quickstart
Clone the repo, run the tests, and spin up the Vite dev server in under five minutes.
Architecture
Deep-dive into the three Workers, hot vs. cold data paths, KV key layout, and R2 parquet partitioning.
Map Views
Explore the Live Map, Flow Map, Route Check, and Explore view in detail.
API Reference
Full reference for every endpoint exposed by the read-api Worker.