Skip to main content

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.

The /snapshots endpoint returns per-station num_bikes_available and num_docks_available counts over a historical [since, until] window, downsampled to a configurable step cadence. It is the data source for the Flow Map’s pin-rewind feature: the frontend loads the full array once per page visit, then uses a binary search on every scrubber tick to update map pin colours without additional network requests. Data is sourced from the same R2 parquet archive used by /trips and is immutable once written, so the worker caches aggressively at max-age=600.

​
Endpoint

GET /api/systems/:systemId/snapshots

​
Path parameters

​
systemId
string
required
The unique system identifier matching a registered network.Example: bcycle_santabarbara

​
Query parameters

​
since
integer
required
Start of the query window as a Unix timestamp in seconds (inclusive).Example: 1747058100
​
until
integer
required
End of the query window as a Unix timestamp in seconds (inclusive). Must be greater than since. The window must not exceed 604 800 seconds (7 days).Example: 1747144500
​
step
integer
default:"120"
Downsampling cadence in seconds. The worker retains at most one snapshot per step-second bucket. Must be between 60 and 3600 seconds inclusive.
  • Default: 120 (one snapshot every 2 minutes)
  • Minimum: 60
  • Maximum: 3600 (one per hour)

​
Response

Returns { snapshots, since, until, step } with Cache-Control: max-age=600.
​
snapshots
array
required
Downsampled array of timestamped station counts, ordered by ts ascending.
​
since
number
required
Echo of the since query parameter as parsed by the worker.
​
until
number
required
Echo of the until query parameter as parsed by the worker.
​
step
number
required
Echo of the effective step value used for downsampling (the default 120 if not supplied).

​
Error responses

StatusBodyMeaning
400{ "error": "since and until must be unix-second integers" }One or both params are missing or non-numeric.
400{ "error": "until must be greater than since" }until ≤ since.
400{ "error": "window must be <= 604800 seconds (7 days)" }Window exceeds the 7-day maximum.
400{ "error": "step must be between 60 and 3600 seconds" }step is outside the valid range.
502{ "error": "failed to read snapshot archive" }R2 parquet read or parse failure.

​
Example request

# 6-hour window at 2-minute cadence (default step)
curl "https://bcycle-map-read-api.developer-95b.workers.dev/api/systems/bcycle_santabarbara/snapshots?since=1747122900&until=1747144500"

# Same window at 5-minute cadence to reduce payload size
curl "https://bcycle-map-read-api.developer-95b.workers.dev/api/systems/bcycle_santabarbara/snapshots?since=1747122900&until=1747144500&step=300"

​
Example response

{
  "since": 1747122900,
  "until": 1747144500,
  "step": 120,
  "snapshots": [
    {
      "ts": 1747123020,
      "stations": [
        {
          "station_id": "station_001",
          "num_bikes_available": 4,
          "num_docks_available": 7
        },
        {
          "station_id": "station_012",
          "num_bikes_available": 2,
          "num_docks_available": 9
        }
      ]
    },
    {
      "ts": 1747123140,
      "stations": [
        {
          "station_id": "station_001",
          "num_bikes_available": 3,
          "num_docks_available": 8
        },
        {
          "station_id": "station_012",
          "num_bikes_available": 2,
          "num_docks_available": 9
        }
      ]
    }
  ]
}
The underlying parquet reader pads the R2 query by 1 hour on each side of [since, until] to capture snapshots straddling partition boundaries. The worker clips the resulting array back to the exact requested window before downsampling, so all entries in snapshots satisfy since ≤ ts ≤ until.
The max-age=600 cache means a second page load within 10 minutes for the same parameters hits the edge cache and returns instantly. A step=120 window of 6 hours returns roughly 180 snapshot objects — small enough to keep in memory for the duration of a Flow Map session.

Build docs developers (and LLMs) love

Get started for freeTalk to us