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 /trips endpoint re-derives inferred bike trips from the R2 parquet station-status archive for any [since, until] window up to 7 days. It mirrors the logic the live poller runs on every tick — reading the station_status partitions, detecting per-station deltas, then applying both conservative (high-confidence) and greedy travel-time–based (low-confidence) trip pairing. Use this endpoint when the rolling /activity log doesn’t cover the full window you need. For ≤ 24-hour windows where the activity log is sufficient, /activity is significantly cheaper (single R2 JSON read vs. parquet parsing).

​
Endpoint

GET /api/systems/:systemId/trips

​
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 until - since must not exceed 604 800 seconds (7 days).Example: 1747144500

​
Response

Returns { trips, since, until } with Cache-Control: max-age=60.
​
trips
array
required
Inferred trips whose departure_ts falls within [since, until]. Sorted by departure_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.

​
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.
502{ "error": "failed to read trip archive" }R2 parquet read or parse failure.

​
Example request

# Trips over the past 24 hours
curl "https://bcycle-map-read-api.developer-95b.workers.dev/api/systems/bcycle_santabarbara/trips?since=1747058100&until=1747144500"

​
Example response

{
  "since": 1747058100,
  "until": 1747144500,
  "trips": [
    {
      "departure_ts": 1747062000,
      "arrival_ts": 1747062420,
      "from_station_id": "station_012",
      "to_station_id": "station_007",
      "duration_sec": 420,
      "confidence": "high"
    },
    {
      "departure_ts": 1747065300,
      "arrival_ts": 1747065780,
      "from_station_id": "station_003",
      "to_station_id": "station_019",
      "duration_sec": 480,
      "confidence": "low"
    }
  ]
}
The worker pads the parquet read by 1 hour on each side of the requested window so that trips straddling a partition boundary are still paired correctly. The response is clipped back to exactly [since, until] before returning, so you will never receive trips outside your requested range.
Greedy ("low" confidence) inference requires a travel-time matrix stored at gbfs/{systemId}/travel-times.json in R2. If that file is absent the worker falls back to conservative-only pairing, which yields far fewer trips on busy days. The warning is logged server-side.
For windows of 24 hours or less, check GET /activity first. It reads a single pre-computed R2 JSON object (no parquet parsing) and already contains the last 50 inferred trips and 200 events.

Build docs developers (and LLMs) love

Get started for freeTalk to us