Atlas API — the complete data reference

Every dataset and every field the Atlas API serves: what it means, which upstream source it comes from, how it is fetched, cleaned, derived and validated, how often the upstream changes, and how often we refresh it. This page is generated from the same pipeline the data ships from — if a field exists in the API, it is documented here.

Overview & conventions

The API has three groups, discoverable from the index:

The discovery index — GET /api/v1

Machine-readable self-description; everything on this page is enumerable from it.

Response & error conventions

• Versioned: breaking changes only ever arrive under a new version prefix. /api/v1 shapes are stable; fields are added, not repurposed.
• Errors are JSON: 404 unknown dataset (body lists available names), 405 non-GET, 410 permanently retired feeds (e.g. live/national-highways), 502 upstream failure, 503 history store unconfigured. Live-feed parameter errors return 400.
• Caching: current group max-age=300, s-maxage=600; live feeds 10–120 s matched to each upstream's real cadence; error responses inherit these TTLs, so a transient upstream 404/502 self-heals within minutes.
• Freshness is explicit: every dataset carries generatedAt (or equivalent), and manifest is the ledger of when each dataset last refreshed, from which source, with how many rows.

Keys & limits

Callers never need a key. Every endpoint on this page is open. Keys exist only behind the API, server-side, and never reach the browser or the responses:

Every endpoint — the complete inventory

Every URL the API answers. No other paths exist; anything else returns a JSON 404 listing what's available.

How everything joins — the key map

The single most important thing to know: three route-key conventions exist, verbatim from the upstreams. Getting these wrong is the #1 integration bug.

Vocabularies & formats — every closed value set

Worked examples

# discover everything
curl -s https://atlas.farhan.app/api/v1 | jq ".endpoints[].name"

# everything about one route (note the key conventions: name for meta/perf/crowding, id for stops/geometry)
curl -s https://atlas.farhan.app/api/v1/route-meta        | jq ".routes.W12"
curl -s https://atlas.farhan.app/api/v1/route-performance | jq ".routes.W12"
curl -s https://atlas.farhan.app/api/v1/route-stops       | jq ".routes.w12.outbound[:3]"
curl -s https://atlas.farhan.app/api/v1/tenders           | jq ".byRoute.W12[0]"

# which routes are diverted right now, and where does W12 actually go?
curl -s https://atlas.farhan.app/api/v1/route-diversions | jq ".count, (.routes | keys[:10])"
curl -s https://atlas.farhan.app/api/v1/route-diversions | jq ".routes.W12 | {status, until, geometryStatus, missed: [.missedStops[][].name]}"

# live: buses on a route · arrivals at a stop
curl -s "https://atlas.farhan.app/api/v1/live/vehicles?line=W12" | jq ".count, .data[0]"
curl -s "https://atlas.farhan.app/api/v1/live/arrivals?stop=490011979N" | jq ".data[0] | {lineName, destinationName, timeToStation}"

# history: reliability trend · what changed on a route over time
curl -s "https://atlas.farhan.app/api/v1/history/reliability-daily?route=W12&from=2026-08-01" | jq ".rows[] | {day, ewt_minutes, sample_count}"
curl -s "https://atlas.farhan.app/api/v1/history/route-snapshots?route=W12&limit=30" | jq "[.rows[] | {snapshot_date, operator, propulsion, pvr}] | unique_by(.operator, .propulsion, .pvr)"

For AI agents

• Enumerate, don't guess: GET /api/v1, /api/v1/live, /api/v1/history list every valid name; a 404 body lists available names.
• Key normalisation: to look a route up across datasets, carry both id (lowercase) and name from routes, and match route-performance keys case-insensitively (see the key map).
• Freshness: read manifest once; trust fetchedAt + status. Data changes at most daily except the live group.
• Never poll faster than the cache TTLs (they match upstream reality); batch questions against one fetched payload instead of re-fetching.
• Nulls are honest — absent knowledge, not zero. Don't impute.
• Shape stability: fields are added, never repurposed, under /api/v1; a permanently removed feed answers 410 with an alternative.
• Provenance: every dataset documents its upstream here; when citing figures, TfL's QSI (route-performance) is official — Atlas's own reliability estimate (history/reliability-daily) is experimental and must be labelled as such.

How data flows — Fetch → Clean → Validate → Store → Serve

Nothing is served straight from a scrape or a live pull. Every dataset moves through the same five-stage pipeline, run unattended every night:

03:17 UTC  atlas-refresh (VPS scheduled task) clones main and runs the pipeline:
           for each dataset: fetch upstream → clean/normalise → validate (hard gate) → write store JSON
           diversions builder runs FIRST and freezes the canonical baselines of diverted routes
           validate-atlas.js (50 checks) gates the commit — a failing dataset keeps its last-good file
           bot commits data/*.json → push → Cloudflare Pages redeploys the API + apps automatically
08:37 UTC  daily fleet sample (warehouse)         ingest pipeline, decoupled — can never block the API
09:23 UTC  warehouse refresh: CDC snapshots per route/garage + reference mirror (incl. diversions history)
every 30m  live arrival/headway sampler (service hours) → our own reliability estimates

• Last-good retention: a failed or implausible fetch never overwrites a good file. Failure is recorded in the manifest (status:"failed", lastError) while the previous data keeps serving.
• Validation is a hard gate, not a warning: row-count bands, required-field checks, coordinate bounds, totals reconciliation and dataset-specific sanity checks all run before a byte lands (see Integrity).
• Degraded-feed gates: TfL's bulk status feed intermittently reports the entire network as Good Service while per-line endpoints still carry disruptions. Status-consuming builders detect the signature (zero disruptions after a run that saw many), retry once, then keep last-good.
• Idempotent + atomic: re-runs produce the same state; files are written via temp-file + rename so a killed run never leaves a torn file.
• Decoupled warehouse: the history warehouse ingests on its own schedule and writes only to Postgres — a slow or failed ingest can never block or corrupt the static API.

Refresh cadences at a glance

Polling matches each upstream's real publication rhythm — a quarterly PDF is not fetched hourly, and a 30-second feed is not cached for a day.

routes reference daily

The route catalogue — every bus line TfL currently registers. Non-public placeholder lines (the ZZ* test/rail-replacement designations) are filtered out so counts reconcile across datasets. Sorted numerically then lexically (2 before 10, letters after).

Validation: 400–2000 rows; every row must carry id, name, type. Failure keeps last-good.

route-meta reference daily

Operational metadata per route — who runs it, from which garage, with how many buses, on what vehicle type and contract. Sourced from the long-running londonbusroutes.net reference (the community authority on garage allocations), scraped in the pipeline only — never at runtime — and joined against the TfL route list.

Coverage: every current route (676/676 at last audit). TfL-sourced values are never overwritten by scraped ones — scrape fills only what TfL doesn't publish.

route-classifications reference daily

A convenience projection of the route list keyed by lowercase line id — the lookup the map filter layer uses. Note the shape: unlike most keyed datasets there is no { routes: … } envelope — the response is the map. Fields name and type are identical to routes; same derivation, same validation, written by the same builder in the same run (they can never drift apart).

route-stops reference daily diversion-frozen

The ordered stop sequence for every route, both directions. Stops are de-duplicated by NaPTAN id across branch variants while preserving order. Canonical-baseline rule: when a route is on (or within 14 days of) an active diversion, its entry is frozen at the last pre-diversion state — TfL temporarily rewrites the sequence during diversions, and absorbing that would silently redefine the route. The temporary state is served separately in route-diversions; the freeze self-heals when the episode ends.

Validation: a full run must yield stop sequences for ≥400 routes or the write is refused (a wholesale sequence failure can't blank the file).

routes-overview reference daily diversion-frozen

Route line geometry for the whole network — one LineString feature per route per direction. Geometry is simplified (Ramer–Douglas–Peucker, tolerance 0.0005° ≈ ≤55 m) and coordinate-rounded to 4 dp (~11 m) so the entire network renders instantly; the un-simplified length is computed before simplification. The same diversion freeze as route-stops applies. An independent cross-check against TfL's iBus scheduling geometry is part of the source health sweep.

line-status snapshot every run

The most recent stored network-status snapshot. The apps read live status from TfL directly (or via /api/v1/live/status); this file is the graceful-degrade tier when live is unreachable, and the historical record's source. Two important interpretations are applied:

• Validity windows are checked by date, not by TfL's isNow flag — TfL routinely publishes in-progress works with isNow:false, which would misreport active diversions as Good Service. A status counts only if its window brackets the current time (or it has no window).
• Degraded-feed gate — a snapshot reporting zero disrupted routes after one that saw many is a known TfL bulk-feed failure mode, and is rejected (retry once, keep last-good).
• ZZ* placeholder lines are dropped; rows sort worst-severity first.

route-diversions derived every run

Active diversion episodes with real diverted geometry. TfL publishes no structured diversion data (its affectedStops/affectedRoutes arrays are empty), but for planned diversions it redraws the route's sequence — so the truth is recovered by diffing TfL's current Route/Sequence against our frozen canonical baseline. Detection uses date-window checking (TfL's isNow is unreliable) plus a diversion-language text signal; both the degraded-feed gate and per-route last-good retention apply. Three baseline tiers:

• store — the frozen canonical baseline (the normal case; the freeze also engages up to 14 days before a window opens, because TfL redraws ~10 days in advance).
• ibus:<version> — recovery tier: if a baseline was already polluted (missed stops fire but no geometry diff), the pipeline walks TfL's dated fortnightly iBus schedule drops and diffs against the first version whose line passes all the episode's missed stops — a self-validating criterion.
• unpublished — TfL hasn't redrawn (typically short-notice/emergency works): the episode still carries status, reason, window and any stop diffs; the map app supplements with a live-GPS estimated path, clearly labelled.

garages reference daily

Every London bus garage with position, operator, allocation and utilisation. Tramlink depots are excluded (their lines 1–4 would collide with bus routes 1–4). A stale-duplicate rule drops a routeless garage sitting <150 m from an active one (e.g. a depot listed under both a former and current operator's code); garages that fail to geocode are kept without coordinates so route→garage joins still work.

fleet sampled daily

The fleet actually running each route, observed live. Registrations come from TfL's arrival predictions (each prediction carries the vehicle id); DVLA's Vehicle Enquiry Service then enriches each registration with make, year and fuel. Important honesty note: this is a point-in-time sample of vehicles on the road at build time — a route's count is "seen this run", not its full roster (the warehouse accrues the roster over time). The DVLA lookup set includes every historically-rostered registration, not just today's, so new plates fill in regardless of timing.

DVLA politeness: one lookup per registration ever (hits and misses both cached persistently), ~220 ms between calls, capped per run (currently 5,000), exponential backoff on 429 with a hard stop that resumes next run. Validation: ≥400 routes present; at least one route must have live vehicles or the write is refused.

vehicles derived daily

The vehicle register: fleet turned inside-out, keyed by registration. Purely derived — zero network calls. A registration appearing on more than one route in the same snapshot is a cross-route working; day-to-day fleet moves are recovered from the warehouse's daily snapshots, not from this file.

Validation: ≥100 registrations. If the fleet dataset is missing the builder skips without writing — it can never blank the register.

tenders reference daily · incremental

The complete TfL route-tendering award history. Awards are immutable once published, so the store is append-only and incremental — a daily run fetches only award ids it hasn't seen. Multi-route awards (1/N1) are split so each route carries the award. byRoute lists are sorted newest-first; the raw byId cache is never mutated.

Validation: the award count may never shrink (append-only guarantee) — a shrunken result refuses to overwrite last-good. The derived fields (jb/vehicle/tranche) are computed identically in the warehouse ingester, kept in deliberate lockstep.

route-performance official stats daily check · ~4-weekly data

TfL's published reliability figures — the authoritative Quality of Service Indicators — extracted from TfL's own PDFs (there is no API for these). Position-aware PDF text extraction reconstructs the real table rows; a sticky table-shape detector tells high-frequency pages (EWT/SWT) from low-frequency ones (on-time %). Numbers are sanity-capped (SWT/AWT ≤ 60 min, EWT ≤ 30, percentages ≤ 100) and anything unparseable becomes null, never a guess. Covers ~738 route ids — more than the current network, because TfL publishes for some night/school variants too.

Fallbacks: QSI and MPS halves fail independently, each keeping its last-good values. Validation: 400–2000 routes. Atlas's own higher-frequency reliability estimate is a separate, clearly-labelled dataset — see history · reliability-daily.

accidents official stats monthly check · annual data

Bus/coach-involved road collisions in Greater London from the national STATS19 casualty statistics. Two CSV tables per year are streamed (never buffered — 100k+ rows/year): the vehicle table first, collecting collision ids where a bus, coach or minibus was involved (vehicle types 10/11), then the collision table filtered to those ids, to finite coordinates inside the London bounding box, and to a decodable severity. All coded attributes are decoded to human labels; an unknown code becomes null, never a wrong label (e.g. the historic junction column is preferred because the newer one uses an incompatible code set).

bridges reference monthly check · annual data

Every height-restricted structure in London — the low-bridge layer and the double-deck diversion-risk input. The workbook is discovered through the Datastore's dataset API (the landing page is JS-rendered) with a pinned TfL fallback URL, and parsed with a dependency-free xlsx reader. The safety-critical rule: published heights are bands ("Between 4.6 and 5.1"); we always normalise to the band's lower bound — the guaranteed clearance, never an optimistic one. Imperial values (9'10") are converted exactly (ft + in/12 × 0.3048).

Same three-tier fallback as accidents (live ≥50 → last-good live → labelled sample).

crowding official stats monthly check · annual data

How full each route gets, from TfL's BUSTO demand model. The newest year folder is auto-discovered on TfL's crowding bucket and the ~98 MB CSV is streamed line-by-line, reduced to one record per route: the peak V/C (load ÷ capacity) across every stop × timeband × direction, plus the per-day-type peaks. Stop names can contain commas, so the numeric columns are read right-anchored — a classic CSV trap handled explicitly. Band thresholds ship in the payload so consumers never hardcode them: comfortable <0.5 · moderate <0.65 · busy <0.8 · crowded ≥0.8.

School (6xx/9xx) routes are absent from BUSTO — coverage ~606 of ~640 routes is expected, not a defect. Fallback: last-good only (no synthetic sample for crowding).

crowding-profile official stats monthly check · annual data

The per-route detail deliberately split out of crowding so the network layer stays light — apps lazy-load this only when a route is selected. Same source, same build, same validation run.

localities reference monthly

Town and suburb labels for the map's "Place names" layer — one bounded Overpass query for place=town|suburb nodes across Greater London. Nameless nodes and names >60 chars dropped; duplicates collapsed by name within a ~1 km cell; coordinates rounded to 5 dp; alphabetically sorted.

manifest meta every run

The pipeline's own ledger — the machine-readable answer to "how fresh is this?". One entry per dataset. A failed refresh is recorded here while the previous data keeps serving, so consumers can detect staleness honestly.

The live group — /api/v1/live real-time

Live feeds proxied through our API so external callers get the same real-time view the apps do — CORS-open, keyless, edge-cached so a flood of callers collapses to a trickle of upstream pulls. Every response wraps the payload as { feed, capturedAt, data }.

What's inside the TfL passthrough payloads

The status, disruptions, arrivals and road-disruptions feeds carry TfL's payload verbatim inside data (every object also carries a TfL $type marker — ignore it). The fields consumers actually need:

Live vehicle fields (SIRI-VM, parsed)

The history group — /api/v1/history time-series

The static datasets are "today's values"; this group serves the time-series that accrues in our self-hosted warehouse (Postgres + PostgREST — the server-side key never reaches the browser; each endpoint is a strict whitelist of table + filters). Common params: limit (max 1000, default 200), order=col.asc|desc, plus the per-endpoint filters below. Responses: { dataset, table, count, limit, rows }. Returns 503 (never a fake 200) if the store is unconfigured; accidents and crowding transparently fall back to filtering the static snapshot.

History row columns — every field, per endpoint

All history rows are snake_case (the warehouse's convention — note it differs from the current group's camelCase). extracted_at on any row is the ingest write time.

The warehouse also mirrors reference data (stops, geometry, bridges, crowding profiles, localities) and accrues route_diversions — one row per episode keyed (route_id, detected_at), never deleted: a permanent diversion history. These are storage/history tables; their current values are served by the datasets above. Sidecar note: the store also ships two internal cache files (fleet-dvla-cache.json, route-mps-cache.json) and serves raw files under /data/*.json — implementation details, not part of the API contract; consume via /api/v1.

Integrity & validation — how we know the data is right

• Per-builder hard gates (documented per dataset above): row-count bands, not-all-null columns, coordinate bounds, vocabulary checks, append-only counts, totals reconciliation. Any failure throws — the dataset keeps last-good and the manifest records the error.
• validate-atlas — 50 dataset-level checks gate every nightly commit: severity splits sum to totals, V/C ≈ load÷capacity, band thresholds honoured, time curves chronological, geometry direction encoding exact, diversion coords inside London, profile peaks reconcile with summaries, and a propulsion-reconciliation regression guard.
• test-functions — 43 unit checks validate the custom maths against independent reference implementations: haversine distances (±0.5%), the diversion deviation thresholds, validity-window logic (including the real-world TfL isNow failure case), zip reading, DVLA/operator canonicalisation rules.
• check-sources — a reproducible health sweep of every upstream (TfL Unified, iBus, BODS, DVLA, londonbusroutes, postcodes.io, EPOWR, Datastore, STATS19, BUSTO, Overpass, QSI host), including a deep mode that cross-checks our stored geometry against TfL's independent iBus scheduling geometry.
• Rendered ↔ source cross-checks — headless-browser verification drives the map apps, reads back what they render, and asserts it equals what the API serves (the front-end pages are kept precisely because they make every dataset visually inspectable).
• Politeness & resilience: 30 s timeouts and up to 4 retries with jittered exponential backoff honouring Retry-After; conditional requests (ETag/Last-Modified) wherever upstreams support them; bounded concurrency everywhere; per-source rate caps (e.g. 4 req/s on TfL's PDF host, ~4.5 req/s on DVLA with a hard-stop-and-resume).

Licensing & attribution

Respect the upstream licences when reusing this API. Data is provided as-is; the manifest tells you exactly how fresh each dataset is.