API Reference

Gzip-compressed JSON of all trains in the map area for the line. This is the primary endpoint used by the Trackser app map view. Send Accept-Encoding: gzip — most HTTP clients handle this automatically.

Same data, decompressed. Larger response — use when your client can't handle gzip.

Stats only — no trains array. Useful for monitoring line health without fetching full train data.

Gzip-compressed JSON of all trains on the full line, including trains at terminals and depot approaches that fall outside the map area.

Same, decompressed.

Stats only for the full-line snapshot.

Gzip-compressed JSON combining every configured line. Includes a top-level lines summary and a missing_lines array for any lines with no current snapshot.

Same, decompressed. Also triggers per-line warmups for any lines with missing snapshots.

Lists all archived snapshot keys for a given day. Returns an array of object keys you pass to /replay/get. Use flavor=map for map-variant snapshots (default is line).

Fetches and decompresses a specific archived snapshot. The objectKey comes from the list endpoint and has the form archive/{lineId}/trains/map/{YYYY-MM-DD}/{HH-MM-SS}.json.

Returns journey tracking data for all trains on the given railway day (YYYY-MM-DD). Includes position history, reformation events, and leading car sightings.

Returns journey data for a specific train on a given day.

Resolves the schedule for a specific date. Returns the timetable ID, day directory, whether it was set explicitly or auto-detected, and the R2 paths used.

{
  "lineId": "metropolitan",
  "date": "2026-03-22",
  "timetableId": "98-26",
  "dayDirectory": "sun",
  "dayDirectorySource": "auto",
  "r2KeyNorthbound": "timetables/metropolitan/98-26/sun/northbound.json",
  "r2KeySouthbound": "timetables/metropolitan/98-26/sun/southbound.json"
}

Fetch today's timetable for a direction (northbound or southbound), auto-detecting the day type from the current railway date.

List all train IDs for today, resolved through the KV schedule.

curl "${BASEURL}/timetables/metropolitan/current/trains?key=YOUR_KEY"

{
  "lineId": "metropolitan",
  "timetableId": "347",
  "dayType": "sun",
  "date": "2026-03-22",
  "trains": ["401", "402", "403"],
  "count": 145
}

Fetch a specific train's full trip from today's timetable.

List all train IDs for a specific date, resolved through the KV schedule.

Fetch a specific train's trip for a given date.

List trains using an explicit day type: m-f, sat, or sun. Supports ?date=YYYY-MM-DD to override the KV lookup date.

Fetch a train's trip for an explicit day type.

Direct access to a specific timetable version — bypasses the KV lookup entirely. Useful for comparing versions.

List all timetable IDs available in R2 for a line.

Set or overwrite the timetable schedule for a date. Body: {"timetableId": "98-26"} or with an explicit day directory: {"timetableId": "31-26", "dayDirectory": "tue"}. Response echoes back the resolved R2 paths.

Remove the schedule entry for a date. The worker reverts to the fallback timetable.

Lightweight per-line health snapshot. overall is "degraded" if any line has errors. trackerNet.status can be ok, degraded, failed, or skipped (backoff active).

{
  "overall": "ok",
  "now": "2026-03-22T09:43:00.000Z",
  "lines": [
    {
      "line": "metropolitan",
      "ok": true,
      "status": {
        "status": "ok",
        "trackerNet": {
          "status": "ok",
          "failStreak": 0,
          "expected": 42,
          "received": 42,
          "lastOkAt": 1742637780000
        },
        "errorHistory": []
      }
    }
  ]
}

Detailed health report including Durable Object metadata per line.

Trigger a manual build. Use ?all=1 for all lines, or ?line={lineId} for a specific one.

curl -X POST "${BASEURL}/admin/refresh?line=metropolitan" \
  -H "X-API-Key: YOUR_KEY"

API usage statistics. Without key, returns a summary for all keys on the date. With key, returns detailed per-endpoint counts.

List all API keys and their configuration.

Aggregated log summary for a line and date. Valid types: vehicle-id, cache-logs, invalid, reformations, trackcode, dedup, errors.

Raw log entries for a line, date, and type.

List available log files for a line.

List deduplication stat snapshots for a line and date.

Retrieve a specific deduplication snapshot.

List error history snapshots for a line.

Retrieve a specific error snapshot.

Show the current effective cleanup policy — retention days, downsampling window, cold storage thresholds.

Preview what would be cleaned for a line on a given day — returns keys to delete and keys to keep. Safe to call; does not modify anything.

Apply one chunk of cleanup. Body: {"lineId": "metropolitan", "day": "2026-03-01", "dryRun": false}.

Run the automated cleanup sweep within the configured window. Safe to call from a cron trigger.

List recent auto-clean run logs.

Copy a day's snapshots to cold storage. Body: {"lineId": "metropolitan", "day": "2026-01-15"}.

Delete a full day from hot and/or cold storage.

Batch delete archived map snapshots. Supports dryRun mode.

{
  "lineIds": ["metropolitan"],
  "before": "2026-01-01",
  "dryRun": true
}

Resolved per-line configuration — TrackerNet station codes, Unified API URLs, feature flags.

Current Durable Object metadata per line — last build time, error counts, TrackerNet state.

Timetable system debug — binding status, first 10 R2 objects, today's KV value.