Build with every train in Great Britain

Base URL: https://api.traini.ac. GET /v1 lists everything as JSON.

type Answer<Request, Data> =
  | { type: "ok"; request: Request; data: Data; generated_at: string } // HTTP 200
  | { type: "error"; error: ApiError };                                 // HTTP 4xx/5xx

request is what we took your arguments to mean, with defaults filled in. Check it: a name becomes one specific station (or a group), and this is where you see which.

"request": {
  "station": { "query": "London", "resolution": { "type": "group", "name": "London Terminals",
    "stations": [ { "crs": "PAD", "name": "London Paddington" }, { "crs": "KGX", "name": "London Kings Cross" }, … ] } },
  "calling_at": null, "from_time": null, "to_time": null, "limit": 15
}

data can be an empty list. Empty means "no trains". A station we couldn't work out is an error, never an empty list.

These appear all over. The full set, with every endpoint's request and data, is v1.d.ts.

type Station = { crs: string; name: string };

/** Somewhere a train is or calls. Junctions and sidings have no code. */
type Place =
  | { type: "station"; crs: string; name: string }
  | { type: "location"; name: string };

type Operator = { code: string; name: string | null }; // { "code": "GW", "name": "Great Western Railway" }

type ServiceClass = "passenger" | "bus" | "freight" | "ship" | "trip" | "empty_stock" | "unknown";

/** A timetabled time and what is known about it. */
type Time = {
  scheduled: string;
  estimate: Estimate;
  delay_minutes: number | null; // when the estimate has a time; negative is early
};

type Estimate =
  | { type: "actual"; at: string }                                      // it has happened
  | { type: "forecast"; at: string; source: "darwin" | "live_report" }  // expected then
  | { type: "delayed_no_estimate" }                                     // late, nobody can say how late
  | { type: "no_information" }                                          // nothing live yet: not "on time"
  | { type: "cancelled" };                                              // won't happen

type Platform =
  | { type: "known"; number: string; source: "actual" | "forecast" | "timetable" } // "4A" is a platform
  | { type: "withheld" }                                                           // not to be shown yet
  | { type: "unknown" };

type Train = {
  id: string | null;      // TRUST id, e.g. 671L50MK02. null until the train is activated
  uid: string | null;     // timetable uid, e.g. GW001
  headcode: string;       // e.g. 1L50. These repeat across the country
  operator: Operator | null;
};

A forecast from darwin is National Rail's prediction, the best there is before a train leaves. One from live_report is the delay the train last reported, carried forward. A timetable platform is planned only, and often wrong at big stations.

Anywhere you give a station (in a path, or as calling_at) you can use:

• a code: PAD, KGX, CDU
• a name, in any word order: London Paddington, paddington, Cam & Dursley (in a path: Cam%20%26%20Dursley)
• a group: London, Birmingham, Manchester, Glasgow, Edinburgh

Exact codes win, then exact names, then the busiest match, so Paddington means the main station rather than the Elizabeth line platforms. If a name really is ambiguous (bradford), you get a station_ambiguous error with candidates instead of a guess.

type StationArgument = { query: string; resolution: Resolution };
type Resolution =
  | { type: "station"; crs: string; name: string }
  | { type: "group"; name: string; stations: Station[] };

It's free, and the limits are the same for everyone. They count units of work, not requests, across /v1, /api and /mcp together:

• 120 units a minute per address (about 40 departure boards). Go over and you get a 429 rate_limited with Retry-After.
• 20 units running at once across everyone. If the database is busy, a request waits up to two seconds, then gets a 503 database_busy with Retry-After: 1.

Every answer tells you where you stand, in headers a browser can read too: X-Request-Units (what this cost), RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy (120;w=60).

Please honour Retry-After, cache what you can (a departure board doesn't change faster than every 30 seconds or so), and send a User-Agent that says who you are. Requests are logged (endpoint, timing, status, forwarded IP, user agent) to keep the usage dashboards honest. Nothing else is kept.

Errors are {"type": "error", "error": {…}}, and the HTTP status tells you whose problem it is. Switch on error.type; message is for logs.

type ApiError = { message: string } & (
  | { type: "station_not_found"; parameter: string; query: string; did_you_mean: Station[] } // 404
  | { type: "station_ambiguous"; parameter: string; query: string; candidates: Station[] }  // 400
  | { type: "same_station" }                                                                // 400
  | { type: "parameter_out_of_range"; parameter: string; value: number; min: number; max: number } // 400
  | { type: "invalid_parameter"; parameter: string; value: string;
      expected: "integer" | "boolean" | "time" | "date" | "headcode" }                      // 400
  | { type: "missing_parameter"; parameters: string[] }  // 400: give at least one of these
  | { type: "train_not_found" }                          // 404
  | { type: "not_found" }                                // 404: no such endpoint
  | { type: "method_not_allowed" }                       // 405
  | { type: "rate_limited"; retry_after_seconds: number } // 429
  | { type: "database_busy"; retry_after_seconds: number } // 503
  | { type: "database_unavailable" }                     // 503
  | { type: "query_failed" }                             // 503
  | { type: "status_unavailable"; retry_after_seconds: number } // 503
  | { type: "internal_error" }                           // 500: our bug
);

parameter is the name you used: station, from, to or calling_at for stations.

GET /v1/departures/bradford                  → 400
{"type":"error","error":{"type":"station_ambiguous","parameter":"station","query":"bradford",
 "candidates":[{"crs":"BDI","name":"Bradford Interchange"},{"crs":"BDQ","name":"Bradford Forster Square"}, …],
 "message":"'bradford' (station) matches more than one station. Ask again with one of the candidates' CRS codes."}}

GET /v1/departures/PAD?from_time=25:99       → 400
{"type":"error","error":{"type":"invalid_parameter","parameter":"from_time","value":"25:99","expected":"time",
 "message":"from_time must be a time, HH:MM or HHMM; got '25:99'."}}

import type { Answer } from "./v1"; // v1.d.ts from this repo

const res = await fetch(`https://api.traini.ac/v1/departures/${crs}?limit=10`);
const body = (await res.json()) as Answer<"/v1/departures/{station}">;
if (body.type === "error") throw new Error(`${body.error.type}: ${body.error.message}`);

for (const d of body.data) {
  const when =
    d.departs.estimate.type === "forecast" ? `exp ${d.departs.estimate.at.slice(11, 16)}`
    : d.departs.estimate.type === "cancelled" ? "cancelled"
    : d.departs.estimate.type === "delayed_no_estimate" ? "delayed"
    : "";
  console.log(d.departs.scheduled.slice(11, 16), d.destination.name, when);
}

Percent-encode station names in paths (encodeURIComponent, urllib.parse.quote). Three small examples you can run are in examples/:

• next-train.sh: curl and jq, the next train from A to B
• departures.ts: a departure board in your terminal (Bun), typed with v1.d.ts
• journey.py: plan a journey and warn about tight changes (Python, no dependencies)

The same data is a Model Context Protocol server at https://api.traini.ac/mcp, so assistants like Claude can answer "when's the next train to Reading?" with live data.

• Claude (web, desktop and mobile): Settings → Connectors → Add custom connector, and paste https://api.traini.ac/mcp.

• Claude Code:

  claude mcp add --transport http trainiac https://api.traini.ac/mcp

• Any other MCP client: add a remote server over Streamable HTTP at the same URL. There's no key and no sign-in.

The same endpoints were first served under /api, in the MCP tools' own JSON ({generated_at, resolved, results, result_count}). That is legacy: it still works, unchanged, but it will be removed once its last users have moved to /v1. Don't build anything new on it. MIGRATING.md maps every old field to its /v1 home.

Network Rail's open data feeds (TRUST movements, TD berth steps, VSTP, TSR, the CIF timetable and CORPUS location names) and National Rail's Darwin Push Port; station names from uk-railway-stations. Times are what those feeds said: nothing is smoothed or made up. Data © Network Rail Infrastructure Limited and Rail Delivery Group, used under their open data licences.