# TransCAPI

> REST API for public transport in Great Britain (England, Scotland, Wales): stops and places, bus and rail departures and arrivals with live running, routes and services, live bus positions, disruptions, and journey planning. One API key, plain JSON, official open data.

Base URL: `https://api.transcapi.com`. Every `/v1` endpoint needs an API key, sent as the `X-Api-Key` header (or `api_key` query parameter). Keys are free at https://www.transcapi.com/signup — the free tier is 1,000 requests a day with every endpoint.

## Conventions that matter

- Every departure and arrival has `source`: `darwin` (live rail, National Rail), `avl` (a bus tracked against its timetable), `siri_vm` (a bus matched to a live position), or `gtfs_scheduled` (timetable only). Present live and timetabled times differently.
- Statuses: `on_time`, `late`, `early`, `delayed` (late, no estimate yet), `cancelled`, `departed` (bus already past the stop), `partly_cancelled` (a train with some calls cancelled).
- Missing data is `null`, never a guess: `shape: null` where no route geometry is published, `delay_seconds: null` where a bus is not tracked.
- `trip_id` links things: a departure, a live vehicle and `/v1/{bus,rail}/services/{trip_id}.json` share it.
- Stops sharing a name are told apart by `towards` (where the buses go). Show it next to the name.
- Bus stops are identified by NaPTAN `atcocode` (e.g. `370022870`); rail stations by 3-letter CRS code (e.g. `LDS` Leeds, `KGX` London Kings Cross).
- Times are ISO 8601 with offsets.
- Errors are JSON `{"error": {"code": ..., "message": ...}}`. `422 outside_coverage` means journey planning does not cover that area (not "no journeys"); `429` with `rate_limit_exceeded` or `daily_limit_exceeded` means wait `Retry-After` seconds.
- Every response carries `X-RateLimit-Limit`, `-Remaining`, `-Reset` (per minute) and `X-RateLimit-Daily-Limit`, `-Daily-Remaining`, `-Daily-Reset`.

## Endpoints

- `GET /v1/places.json?query=` — towns, villages, postcodes (full or partial, e.g. `S1`) and stops. Same-named places ranked by size. Optional `lat`/`lon` sorts by distance; `type` filters (`settlement`, `postcode`, `bus_stop`, `train_station`, `tram_stop`).
- `GET /v1/bus/stops.json?lat=&lon=&radius=` — stops near a point (or `min_lat`/`min_lon`/`max_lat`/`max_lon`), each with `towards`.
- `GET /v1/bus/stop_timetables/{atcocode}.json` — departures (`type=arrivals` or `both` for arrivals). Expected times and `delay_seconds` for tracked buses; `live=true` adds matched vehicle positions. Window: `from_offset`/`to_offset` minutes, `datetime`. Untracked departures whose bus is tracked on its previous journey (same block) get a prediction: `source: "block"`, `predicted_from`.
- `GET /v1/bus/vehicles.json?lat=&lon=&radius=` — live buses near a point (radius up to 10000 m) or in a box, linked to their `trip_id`, with `delay_seconds` where tracked. Filter `line`, `operator`.
- `GET /v1/bus/reliability.json?route_id=` (or `operator=&line=`, or `operator=` alone to list lines) — observed punctuality over `days` (default 28, ≤56): on-time/early/late/very-late %, mean delay, timing-point/first/last-stop on-time %, by hour. On time = ≤1 min early and <6 min late. Northern England and West Sussex since 4 Aug 2026, wherever operators report positions across GB since 30 Sep 2026.
- `GET /v1/bus/stop_reliability/{atcocode}.json` — each line's punctuality at a stop, with median and 90th-percentile delay (≤35 days).
- `GET /v1/bus/routes.json?q=` — find bus routes by line number or name (`q`), `operator`, or a stop served (`atcocode`).
- `GET /v1/bus/routes/{route_id}.json` — a route's directions, stops, road geometry (`shape.encoded_polyline`, precision 5) and a day's timetable.
- `GET /v1/bus/services/{trip_id}.json` — one journey's calling points and, if running, its live vehicle.
- `GET /v1/rail/stations.json?lat=&lon=&radius=` — stations near a point.
- `GET /v1/rail/station_timetables/{crs_code}.json` — departures/arrivals with live expected times, platforms, cancellations, delay reasons and station `messages` from National Rail (within two hours of now; `live=false` for timetable only).
- `GET /v1/rail/services/{trip_id}.json` — one train's calling points; for today, each call has `status`, `expected_time`, `actual_time`, `platform`.
- `GET /v1/rail/routes.json`, `/v1/rail/routes/{route_id}.json` — rail services by operator.
- `POST /v1/alerts.json` — push alerts (webhooks): `{"type": "vehicle_approaching", "atcocode", "minutes", "line"?, "url"}` or `{"type": "disruption", "filters": {...}, "url"}`; returns a `secret` once for the `X-TransCAPI-Signature` HMAC-SHA256. `GET/DELETE /v1/alerts/{id}.json`, `POST /v1/alerts/{id}/test.json`. Limits: 3/50/500 by plan.
- `GET /v1/disruptions.json` — planned works, incidents and line status: bus and tram across Great Britain, National Rail engineering works and incidents (`mode=rail`, placed by the stations named in affected routes; `atcocode` accepts a CRS code), Tube/DLR/Overground/Elizabeth line/London Trams. Filter by `mode`, `severity`, `operator`, `line`, stop (`atcocode`), point and radius, box, `planned`, or a journey's route with `path` (encoded polyline) and `path_radius` — the reliable way to ask what affects a journey, since line numbers repeat across towns.
- `GET /v1/journey/reachable.json?lat=&lon=&cutoffs=15,30,45` — the area reachable by public transport within each cutoff (≤90 min), as GeoJSON, anywhere in Great Britain, today or tomorrow (`datetime`). Walking estimated from straight-line distance.
- `POST /v1/journey/travel_times.json` — body `{"from": {"lat","lon"}, "to": [{"id","lat","lon"}, ...≤500], "datetime", "max_minutes"}`: minutes by public transport from one point to each destination, `null` if unreachable. GET form: `?from_lat=&from_lon=&to=lat,lon|lat,lon` (≤100).
- `GET /v1/journey.json?from_lat=&from_lon=&to_lat=&to_lon=` — multi-modal journeys (bus, coach, rail, Underground, metro, tram, ferry) anywhere in England, Scotland and Wales, up to two months ahead, with walking limits (`max_walk_distance`), turn-by-turn directions (`include_steps=true`), live positions, and fares where fare data exists (bus in Yorkshire and West Sussex). Bus/tram/metro legs follow the operator's route (`leg_geometry_source: "shape"`). Walking legs carry `terrain` (climb and descent in metres, steepest gradient, shape, estimated calories, from OS Terrain 50) and each itinerary a `walking` summary. Itineraries with changes carry `connections` (spare time and `chance_pct` of making each change, from how those exact buses ran on recent days) and `connection_chance_pct`. `datetime` without an offset is UK time. `max_gradient` (percent) excludes journeys whose walks are steeper; each itinerary has `accessibility.steepest_walk_gradient_pct`. Every leg and itinerary carries `carbon` (g CO2e from the UK government's 2026 conversion factors, plus `driving_alone_co2e_g` for comparison). Northern Ireland returns `422 outside_coverage`. Sundays 03:00-04:30 UK it returns `503 scheduled_maintenance` with `Retry-After` while the week's timetables load.

## Coverage and gaps

Great Britain for stops, places, journey planning, and bus and rail timetables (both refreshed daily). Live bus positions follow BODS reporting (England, some Wales, little Scotland); bus delays and punctuality cover wherever operators report positions (national since 30 Sep 2026; punctuality history in northern England and West Sussex from 4 Aug 2026). Not covered: Northern Ireland.

## Attribution

Apps displaying TransCAPI data must show the source attribution: see https://www.transcapi.com/docs/data-sources for the exact line (OGL, OS, Royal Mail, OpenStreetMap, National Rail Enquiries, TfL).

## Docs

- [Getting started](https://www.transcapi.com/docs/getting-started): one working request per area
- [Bus](https://www.transcapi.com/docs/bus): departures, tracked delays, live vehicles
- [Rail](https://www.transcapi.com/docs/rail): live boards and single trains
- [Disruptions](https://www.transcapi.com/docs/disruptions): filters and matching to a route
- [Journey planning](https://www.transcapi.com/docs/journey)
- [Push alerts](https://www.transcapi.com/docs/alerts)
- [Rate limits](https://www.transcapi.com/docs/rate-limits)

## Guides

- [UK bus times in Python](https://www.transcapi.com/guides/uk-bus-times-python): postcode to nearest stops to departures
- [Live UK train departures](https://www.transcapi.com/guides/live-train-departures-api): a Darwin-backed station board
- [Journey planning that knows about hills](https://www.transcapi.com/guides/journey-planning-walking-climb): ranking journeys by walking climb
- [Where can I get to in 30 minutes?](https://www.transcapi.com/guides/reachability-maps-travel-times): reachable areas and one-to-many travel times
- [How reliable is my bus?](https://www.transcapi.com/guides/bus-punctuality-api): measured punctuality and connection chances
- [Data sources & attribution](https://www.transcapi.com/docs/data-sources)
- [OpenAPI spec](https://api.transcapi.com/openapi.json)
- [MCP server](https://github.com/tcdataconsultants/transcapi-mcp): the API as tools for AI assistants
- [Full reference for LLMs](https://www.transcapi.com/llms-full.txt)