tfl-ts

TfL API TypeScript Client

[npm version] [License: MIT] [TypeScript] [Node.js] [CI]

Typed TfL client: friendly wrappers, 84 raw REST endpoints, and offline station topology for 20 rail lines.

Built with tfl-ts → Board

How this compares

Counts use the 84 operations in the committed OpenAPI snapshot (ENDPOINT_COUNT in src/generated/endpoints.ts, pathCount in src/generated/openapi/spec.meta.json). Checked against each repo's source and the package.json published to npm on 16 October 2026.

tfl-ts publishes .d.ts files. Runtime dependencies: none. typescript is a peer dependency, for people compiling against the types. Station order and hubs ship in tfl-ts/meta, with no network call. tfl mcp is the local MCP server.

tfl-unified-api 2.0.2 is JavaScript, with no types field. It depends on moment, request, and request-promise-native. The Line module calls ten of the 84 paths: meta modes, severity, disruption categories, service types, route sequence, route by id, lines by mode, status by id, status over a date range, and status by mode. getRoutesByServiceType builds /Line/Route/{types}, which sits outside those 84 paths. db/lineColors.json is line colours, not stations.

tfl-journey-planner 1.1.2 is LiveScript compiled to JavaScript, with no types field. It depends on request and querystring. The module calls GET /Journey/JourneyResults/{from}/to/{to} only.

@daanrongen/tfl-mcp 1.4.3 is written in TypeScript. The published tarball is dist/main.js, package.json, and README.md, and package.json has no types field. It depends on @modelcontextprotocol/sdk, effect, and zod. Its tools call 59 of the 84 paths. They also call /Road/all/Disruption (the snapshot path is /Road/all/Disruption/{disruptionIds}), /Vehicle/EmissionSurcharge, and /Vehicle/UlezCompliance.

@pipeworx/mcp-tfl 0.1.2 sets "types": "src/index.ts", and that file is in the tarball. It depends on @modelcontextprotocol/sdk and tsx. Six tools call 8 of the 84 paths.

Station order ships with tfl-ts, in tfl-ts/meta.

Install and first call

Get a Primary key from the TfL API Portal. Subscribe to "500 Requests per min", then Profile → Show.

pnpm add tfl-tsexport TFL_APP_KEY=your-primary-keypnpm exec tfl raw line.statusByIds --ids victoria

[  {    "id": "victoria",    "name": "Victoria",    "lineStatuses": [{ "statusSeverityDescription": "Good Service" }]  }]

Line names, station order, and colours ship in the package. Status, arrivals, and journeys hit TfL at runtime.

On the portal you'll see two keys (Primary and Secondary); either works. app_id has been unused since Jan 2021.

const client = new TflClient({  appKey: 'your-primary-key',});

Quick starts

Node

import TflClient from 'tfl-ts';
const client = new TflClient(); // reads TFL_APP_KEY from process.env
const status = await client.line.getStatus({ modes: ['tube'] });
const arrivals = await client.stopPoint.getArrivals({  stopPointIds: ['940GZZLUOXC'], // Oxford Circus});
const journey = await client.journey.plan({  from: '940GZZLUOXC',  to: '940GZZLUBND',});
const { matches } = await client.stopPoint.search({  query: 'Oxford Circus',  modes: ['tube'],});
const busStops = await client.stopPoint.searchBusStops('Trafalgar Sq');

Next.js

Server Component with ISR (~60s). Boards and explorer: tfl-components · tfl.manglekuo.com/docs/explorer. Tube boards use official line colours; bus boards use route-number chips. Do not mix. See examples/README.md.

import TflClient, { sortLinesBySeverityAndOrder } from 'tfl-ts';
export const revalidate = 60;
const client = new TflClient();const tube = await client.line.getStatus({ modes: ['tube'] });const sorted = sortLinesBySeverityAndOrder(tube);

pnpm dlx shadcn@latest add https://tfl.manglekuo.com/r/tube-status-board.jsonpnpm dlx shadcn@latest add https://tfl.manglekuo.com/r/tfl-roundel.json

The roundel ships a placeholder unless NEXT_PUBLIC_ALLOW_TFL_ROUNDEL=true (you accept trademark responsibility).

Agent / MCP

Read-only MCP (npx tfl-ts mcp), cached and rate-limited. Static tools never call TfL. The npm bin is tfl (dist/cjs/bin/tfl.js); mcp is the stdio subcommand. Setup: docs/mcp.md.

{  "mcpServers": {    "tfl-ts": {      "command": "npx",      "args": ["-y", "tfl-ts@latest", "mcp"],      "env": {        "TFL_APP_KEY": "your-primary-key"      }    }  }}

Tools: get_supported_modes, resolve_line_id, docs, resolve_stop_id, get_line_status, get_arrivals, plan_journey.

No repo access, or lost your context? npx tfl-ts docs ls lists every bundled agent doc (this README, CLAUDE.md, docs/agent.md, docs/mcp.md, …). docs cat <id> prints one, and docs find <query> / docs grep <pattern> search across all of them — offline, no API key. The local MCP docs tool reads the same catalogue.

Gotchas

• Line IDs are lowercase slugs: 'central', 'victoria', 'elizabeth'. Not display names like 'Central'.
• Stop IDs look like '940GZZLUOXC'. Resolve with stopPoint.search() or place.search().
• Bus stops accept 5-digit NaPTAN-style codes in search (for example '51800').
• Prefer static constants (LINE_NAMES, STATION_SEQUENCES, mode lists) before live calls.
• Cache status for about 30 to 60s. Do not poll arrivals faster than about 10 to 15s per stop.
• accidentStats and airQuality are deprecated.
• National Rail arrivals aren't live through TfL: STATION_HUBS tracks Southeastern, South Western Railway, and similar operators for topology, but getArrivals() returns an empty array for them, not an error.
• Tube boards use official line colours; bus boards use route-number chips. Do not mix patterns.
• Roundel trademark: placeholder unless the consumer opts in.
• A line can carry several lineStatuses. Do not read [0]. Use getWorstCurrentStatus(line.lineStatuses) for the operative row.
• validityPeriods[].isNow follows disruption.category === 'RealTime'. It is not a clock check. Planned engineering can be in force today with isNow: false.
• validityPeriods[].toDate is the window end, not when trains resume. Weekend engineering often ends at 00:29Z (01:29 London, end of the traffic day). Overnight-split slices on one row are one possession; do not treat the first overlapping toDate as the next train.
• Severity 20 is scheduled closure (Waterloo & City weekends, end of traffic day), not an unplanned Closed (1). sortLinesBySeverityAndOrder ranks it after incidents.
• Circle / H&C / Met lineId flips along shared track. Use withSharedTrackIdentity. Do not rewrite raw lineId.

Before and after

getDetailedStatus() returns shorter types and renamed fields (severity, from, closureType, originName) instead of TfL's generated shapes:

const lines = await client.line.getDetailedStatus({  lineIds: ['bakerloo'],  dateRange: { startDate: '2026-08-08', endDate: '2026-08-10' },});const s = lines[0]?.statuses?.[0];s?.severity;s?.severityDescription;s?.validityPeriods?.[0]?.from;s?.disruption?.closureType;

Use getStatus({ detail: true }) or client.raw.line.* for exact TfL field names.

Station sequences

Tube, Elizabeth line, DLR, Overground, Tram, and river-bus pier topology. No credentials, no network. Identity, order, and branches only (no status or arrivals). River piers are not in STATION_HUBS — poll the NaptanFerryPort id. Live topology: client.line.getRouteSequence(). Also on the client: client.line.STATION_SEQUENCES.

import { LINE_STATION_SEQUENCES } from 'tfl-ts/meta';
const bakerloo = LINE_STATION_SEQUENCES.bakerloo;const outbound = bakerloo.orderedRoutes.find(  (route) => route.direction === 'outbound' && route.serviceType === 'Regular',);console.log(outbound?.stationIds, bakerloo.branches);

Station hubs and normalised arrivals

STATION_HUBS maps each physical station to its sibling StopPoint ids and the specific id that carries arrivals for each line — Liverpool Street's tube id (940GZZLULVT) and rail id (910GLIVST) both resolve to one HUBLST entry, with Central on the tube id and Elizabeth line on the rail id. No credentials, no network.

import { STATION_HUBS, resolveArrivalsStopId } from 'tfl-ts/meta';
const hub = STATION_HUBS['940GZZLULVT']; // any sibling id worksconst elizabethStopId = hub && resolveArrivalsStopId(hub, 'elizabeth'); // '910GLIVST'

resolveArrivalsStopId returns undefined when the hub doesn't carry that line, rather than the interchange id — polling the interchange id itself returns zero arrivals from TfL. Third-party National Rail operators (Southeastern, South Western Railway, c2c, and similar) show up in the hub's topology but never return live predictions: TfL's Arrivals API only covers tube, DLR, tram, Overground, and Elizabeth line.

client.stopPoint.getNormalizedArrivals() is getArrivals() plus a cleaned destination (falls through empty or literal "null" towards to destinationName, common on Elizabeth line, Overground, and some bus termini) and platform (compass bound, cleaned label, isUnknown for TfL's literal "Platform Unknown"):

const arrivals = await client.stopPoint.getNormalizedArrivals({  stopPointIds: ['940GZZLUOXC'],});arrivals[0]?.destination.name;arrivals[0]?.platform.label;

getArrivals() and client.raw.* are unchanged.

client.stopPoint.get and getByGeoPoint lift Direction additional properties onto the stop: towards, compassPoint, and compassBearingDegrees. smsCode is filled from the first-class field or bag SmsCode. Facility keys stay in additionalProperties as TfL strings. parseAdditionalPropertyValue turns a bag value into null / boolean / number / date / text ("yes", "null", unix ms InstallDate). client.raw.stopPoint.* is unlifted. Do not use Prediction bearing (vehicle heading) as the stop flag; a painted stopLetter of W is Stop W, not west.

const [stop] = await client.stopPoint.get({ stopPointIds: ['490013766E'] });stop.towards; // 'Aldwych'stop.compassPoint; // 'E'stop.compassBearingDegrees; // 90

On Circle / Hammersmith & City / Metropolitan shared track, TfL assigns lineId per station, not per train. The same vehicleId can be circle at Victoria and hammersmith-city at Liverpool Street. withSharedTrackIdentity(stopRows, lineIds, networkArrivals) adds sharedTrackIdentity (canonicalLineId from an exclusive-segment hit, or ambiguous + rawLineIds). It does not rewrite raw lineId. line.getArrivals({ lineIds }) with no stopPointId is the network-wide poll that evidence needs.

Colours, severity, and detailed types

import type {  DetailedLine,  DetailedLineStatus,  DetailedDisruption,  AffectedRoute,  AffectedStop,} from 'tfl-ts';import {  getLineColor,  getLineInlineStyles,  getLineCssProps,  getLineDarkReadableStyles,  sortLinesBySeverityAndOrder,  getLineStatusSummary,  getWorstCurrentStatus,  getStatusKind,} from 'tfl-ts/ui';
const { hex } = getLineColor('central'); // #E32017const styles = getLineInlineStyles('central');const cssProps = getLineCssProps('northern');
const tube = await client.line.getStatus({ modes: ['tube'] });const sorted = sortLinesBySeverityAndOrder(tube);const worst = getWorstCurrentStatus(sorted[0]?.lineStatuses);getStatusKind(worst ?? 10);

Northern defaults to outline dark contrast. Pass { darkContrastMode: 'white' } for white fill/text. See CHANGELOG.md (2.4.0). Raw escape hatch: client.raw.line.statusByIds({ ids: ['central'] }).

Realtime

Poll arrivals with the same app_key as REST. No SignalR. Details: docs/REALTIME.md.

const stop = client.realtime.pollArrivals(  {    stopPointIds: ['940GZZLUOXC'],    sortBy: 'timeToStation',    intervalMs: 30_000,  },  (arrivals, meta) => console.log(`[tick ${meta.tick}]`, arrivals.length),  (error, meta) => console.error(meta.tick, error),);stop();

Module index

Zero runtime dependencies (Node, browser, and edge with fetch).

Deeper docs

All of the above ship in the npm package and are readable offline via npx tfl-ts docs ls|cat|find|grep or the MCP docs tool — no clone required.

Playground demos under playground/demo/ are for clones, not package consumers.

Architecture

OpenAPI snapshot (committed)  → types.ts        (swagger-typescript-api, types only)  → rawClient.ts    (owned generator, uniform object-param API)  → client.raw.*    (public escape hatch)  → wrappers        (line, stopPoint, …)

pnpm run build compiles TypeScript to CJS and ESM. No network, no OpenAPI regeneration.

Contributing

git clone https://github.com/ghcpuman902/tfl-ts.gitcd tfl-tspnpm installpnpm run buildpnpm run test

Useful scripts: pnpm run generate, pnpm run check, pnpm run check -- --only=drift, pnpm exec tfl list. See LLM_context.md and .cursor/skills/tfl-ts-maintainer/SKILL.md.

License

MIT. Not affiliated with Transport for London.