TfL API TypeScript Client

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

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-ts
export TFL_APP_KEY=your-primary-key
pnpm 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.

Pass credentials in the constructor instead

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.json
pnpm 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. 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 works
const 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'); // #E32017
const 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

Module	Common work
client.line	Status, detailed status, disruptions, routes, arrivals by line, static LINE_NAMES / STATION_SEQUENCES
client.stopPoint	Search, arrivals, normalised arrivals, stop metadata, static STATION_HUBS
client.journey	Journey planning
client.mode	Mode lists and mode arrivals
client.search / place / road / vehicle / occupancy / bikePoint / cabwise / travelTimes	Supporting APIs
client.raw	All 84 REST endpoints (pnpm exec tfl list in a clone)
client.realtime	Instant-pull polling over REST arrivals

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

Deeper docs

Resource	Purpose
CLAUDE.md / AGENTS.md	Agent quick-start: static vs live
docs/agent.md	Module reference, caching, Next.js patterns
.claude/skills/tfl-ts/SKILL.md	Usage patterns and gotchas
docs/mcp.md	Local MCP server (includes offline docs tool)
CHANGELOG.md	Release notes
docs/MIGRATION-v2.md	v1 → v2 migration
examples/	Library → UI mapping (tube + bus)
docs/design/agent-friendly-cli.md	Why tfl docs and MCP docs exist

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.git
cd tfl-ts
pnpm install
pnpm run build
pnpm 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.

npm	tfl-ts
GitHub	ghcpuman902/tfl-ts
Issues	Report bugs
Live demo	tfl.manglekuo.com