GET /api/systems/:id/current — BCycle Live Snapshot

The /current endpoint returns the most recent snapshot that the poller wrote to Cloudflare KV for the requested system. This is the primary data source for the live map’s station pins, stats card, and sparkline widget — it contains everything the frontend needs in a single request.

Endpoint

GET /api/systems/:systemId/current

Path parameters

systemId

string

required

The unique system identifier. Must match a system registered in the systems index.Example: bcycle_santabarbara

Response

On success the worker reads system:<systemId>:latest from KV and returns the raw JSON blob with Content-Type: application/json and Cache-Control: max-age=60.

Top-level fields

system

object

required

Static metadata about the system sourced from the GBFS system_information feed.

Show SystemInfo fields

system_id

string

Unique identifier for the system, e.g. bcycle_santabarbara.

name

string

Human-readable network name, e.g. Santa Barbara BCycle.

timezone

string

IANA timezone string for the system’s home city, e.g. America/Los_Angeles.

language

string

BCP-47 language code for the system’s feed, e.g. en.

snapshot_ts

number

required

Unix timestamp (seconds) of the poll tick that produced this snapshot.

stations

array

required

Array of station objects combining static info (location, name) with live counts.

Show StationSnapshot fields

station_id

string

Opaque station identifier from the GBFS feed.

name

string

Display name for the station.

lat

number

Latitude of the station dock.

lon

number

Longitude of the station dock.

address

string

Street address, if present in the GBFS feed.

num_bikes_available

number

Total rideable bikes currently docked (classic + electric + smart).

num_docks_available

number

Empty dock slots available for returns.

bikes_electric

number

Electric-assist bikes currently docked.

bikes_classic

number

Classic (non-electric) bikes currently docked.

bikes_smart

number

Smart bikes currently docked.

is_installed

boolean

Whether the station is currently installed and active.

is_renting

boolean

Whether the station is currently accepting rentals.

is_returning

boolean

Whether the station is currently accepting returns.

last_reported

number

Unix timestamp (seconds) when the GBFS feed last updated this station.

first_seen_ts

number

Unix timestamp when this station first appeared in the feed. Absent for stations that pre-date this field.

max_bikes_ever

number

Highest total sum(num_bikes_available) the poller has ever observed. A proxy for total fleet size. Grows monotonically; converges within a day or two of first polling.

recent24h

array

Rolling 24-element window of per-hour min/max bikes-available stats. Used by the sparkline widget.

Show HourBikeStats fields

hour_ts

number

Unix seconds at the top of the UTC hour.

bikes_max

number

Highest sum(num_bikes_available) observed during the hour.

bikes_min

number

Lowest sum(num_bikes_available) observed during the hour — a proxy for peak active riders.

last_total_changed_ts

number

Unix seconds when the system-wide bike count last changed. Used to render a “changed X min ago” badge.

Error responses

Status	Body	Meaning
`404`	`not found`	No KV data exists for this `systemId`. The system may not be registered or the poller has not run yet.

Example request

curl https://bcycle-map-read-api.developer-95b.workers.dev/api/systems/bcycle_santabarbara/current

Example response

{
  "system": {
    "system_id": "bcycle_santabarbara",
    "name": "Santa Barbara BCycle",
    "timezone": "America/Los_Angeles",
    "language": "en"
  },
  "snapshot_ts": 1747144500,
  "max_bikes_ever": 47,
  "last_total_changed_ts": 1747144200,
  "recent24h": [
    { "hour_ts": 1747101600, "bikes_max": 42, "bikes_min": 31 }
  ],
  "stations": [
    {
      "station_id": "station_001",
      "name": "Stearns Wharf",
      "lat": 34.4094,
      "lon": -119.6857,
      "address": "Stearns Wharf, Santa Barbara, CA",
      "num_bikes_available": 4,
      "num_docks_available": 7,
      "bikes_electric": 2,
      "bikes_classic": 2,
      "bikes_smart": 0,
      "is_installed": true,
      "is_renting": true,
      "is_returning": true,
      "last_reported": 1747144480,
      "first_seen_ts": 1700000000
    }
  ]
}

The poller writes a new KV snapshot approximately every 5 minutes. Combined with the 60-second edge cache, data you receive may be up to 65 seconds behind the most recent poll tick. For near-real-time activity (bike departures/arrivals), use the lower-latency /activity endpoint (max-age=20).

Read API Endpoints

Data Types

GET /api/systems/:id/current — BCycle Live Snapshot

Endpoint

Path parameters

Response

Top-level fields

Error responses

Example request

Example response

Build docs developers (and LLMs) love

Read API Endpoints

Data Types

Documentation Index

​Endpoint

​Path parameters

​Response

​Top-level fields

​Error responses

​Example request

​Example response

Build docs developers (and LLMs) love

Endpoint

Path parameters

Response

Top-level fields

Error responses

Example request

Example response