Package Exports
- tfl-ts
- tfl-ts/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (tfl-ts) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
TfL API TypeScript Client
A fully-typed TypeScript client for the Transport for London (TfL) API with auto-generated types, real-time data support, and comprehensive coverage of all TfL endpoints. Built with modern TypeScript practices and zero dependencies.
- TypeScript-first: Full type safety and autocompletion for all endpoints and IDs.
- Batch & parallel requests: The client bundles requests for common use cases, and run them in parallel if possible.
- Universal compatibility: Zero dependencies, works in Node.js, browsers, and edge runtimes. (help us test! Feedback welcome)
- Auto-updating: API endpoints and metadata are automatically generated from TfL's OpenAPI specification. This includes all REST endpoints plus metadata that would otherwise require separate API calls. We fetch this data at build time, making it available as constants in your code. The client stays current even when TfL adds new lines or services.
- Better parameter naming: Uses specific parameter names like
lineIds
,stopPointIds
instead of genericids
for better clarity and reduced confusion. - Comprehensive error handling: Comprehensive error handling with typed error classes and automatic retry logic. All errors are instances of
TflError
or its subclasses, making it easy to handle different types of errors appropriately.
Getting Started
1. Get your API credentials from TfL
First, you'll need to register for free API credentials at the TfL API Portal. This is required to access TfL's public API.
2. Install & Setup
pnpm add tfl-ts
Create a .env
file in your project root:
TFL_APP_ID=your-app-id
TFL_APP_KEY=your-app-key
3. Start coding
Example: get arrivals for a specific tube station
make a new file called demo.ts
in your project and add the following code:
// demo.ts
import TflClient from 'tfl-ts';
const client = new TflClient(); // Automatically reads from process.env
// You can also pass credentials directly
// const client = new TflClient({
// appId: 'your-app-id',
// appKey: 'your-app-key'
// });
const main = async () => { // wrap in async function to use await
// ======== Stage 1: get stop point ID from search ========
try {
const query = "Oxford Circus";
const modes = ['tube'];
const stopPointSearchResult = await client.stopPoint.search({ query, modes }); // a fetch happens behind the scenes
const stopPointId = stopPointSearchResult.matches?.[0]?.id;
if (!stopPointId) {
throw new Error(`No stop ID found for the given query: ${query}`);
}
console.log('Stop ID found:', stopPointId); // "940GZZLUOXC"
} catch (error) {
console.error('Error:', error);
return;
// For more information on error handling, see the Error Handling Guide in the ERROR.md file
}
// ======== Stage 2: get arrivals ========
try {
// Get arrivals for Central line at Oxford Circus station
const arrivals = await client.line.getArrivals({
lineIds: ['central'],
stopPointId: '940GZZLUOXC' // from Step 1
});
// Sort arrivals by time to station (earliest first)
const sortedArrivals = arrivals.sort((a, b) =>
(a.timeToStation || 0) - (b.timeToStation || 0)
);
sortedArrivals.forEach((arrival) => {
console.log(
`${arrival.lineName || 'Unknown'} Line` +
` to ${arrival.towards || 'Unknown'}` +
` arrives in ${Math.round((arrival.timeToStation || 0) / 60)}min` +
` on ${arrival.platformName || 'Unknown'}`
);
});
/* console output:
Central Line to Ealing Broadway arrives in 1min on Westbound - Platform 1
Central Line to Hainault via Newbury Park arrives in 2min on Eastbound - Platform 2
Central Line to West Ruislip arrives in 4min on Westbound - Platform 1
Central Line to Epping arrives in 6min on Eastbound - Platform 2
Central Line to Ealing Broadway arrives in 6min on Westbound - Platform 1
Central Line to Hainault via Newbury Park arrives in 8min on Eastbound - Platform 2
*/
} catch (error) {
console.error('Error:', error);
return;
}
}
main().catch(console.error);
run the code with
pnpm dlx ts-node demo.ts
Error Handling
For comprehensive error handling information, including error types, handling strategies, best practices, and troubleshooting, see the Error Handling Guide file.
The TfL TypeScript client provides comprehensive error handling with typed error classes and automatic retry logic. All errors are instances of TflError
or its subclasses, making it easy to handle different types of errors appropriately.
Examples
see the playgorund/demo folder for complete set of examples for each endpoint.
Autocomplete
Autocomplete for line IDs, modes, etc.
VS code showing jsdoc comments
Using the client to get timetable of a specific station following a search
Get real-time tube status
See a live example with UI here: https://manglekuo.com/showcase/tfl-ts
const tubeStatus = await client.line.getStatus({ modes: ['tube'] });
// console output:
[
// ...
{
id: 'central',
name: 'Central',
modeName: 'tube',
disruptions: [],
created: '2025-06-17T14:58:36.767Z',
modified: '2025-06-17T14:58:36.767Z',
lineStatuses: [
{
id: 0,
statusSeverity: 10,
statusSeverityDescription: 'Good Service',
created: '0001-01-01T00:00:00',
validityPeriods: []
}
],
routeSections: [],
serviceTypes: [
{
name: 'Regular',
uri: '/Line/Route?ids=Central&serviceTypes=Regular'
},
{
name: 'Night',
uri: '/Line/Route?ids=Central&serviceTypes=Night'
}
],
crowding: 'Unknown'
},
// ...
]
Pre-generated constants
// Pre-generated constants
console.log(client.line.LINE_NAMES);
// console output:
{
...
100: '100'
sl8: 'SL8',
sl9: 'SL9',
suffragette: 'Suffragette',
tram: 'Tram',
victoria: 'Victoria',
'waterloo-city': 'Waterloo & City',
weaver: 'Weaver',
'west-midlands-trains': 'West Midlands Trains',
windrush: 'Windrush',
'woolwich-ferry': 'Woolwich Ferry'
...
}
Validate user input
// Validate user input
const userInput = ['central', '100', 'elizabeth', 'elizabeth-line', 'invalid-line'];
const validIds = userInput.filter(id => id in client.line.LINE_NAMES);
console.log(validIds);
if (validIds.length !== userInput.length) {
throw new Error(`Invalid line IDs: ${userInput.filter(id => !(id in client.line.LINE_NAMES)).join(', ')}`);
}
// console output:
[ 'central', '100', 'elizabeth' ]
/*
Error: Invalid line IDs: elizabeth-line, invalid-line
at main (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:12:11)
at Object.<anonymous> (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (node:internal/modules/cjs/loader:1692:14)
at Module.m._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/playground/demo.ts:16:1)
at Module._compile (/Users/manglekuo/dev/nextjs/tfl-ts/ts-node@10.9.2_@types+node@20.17.19_typescript@5.7.3/node_modules/ts-node/src/index.ts:1618:23)
at node:internal/modules/cjs/loader:1824:10
at Object.require.extensions.<computed> [as .ts] (/Users/manglekuo/dev/nextjs/tfl-ts/node_modules/.pnpm/ts-node@10.9.2_@types+node@20.17.19_typescript@5.7.3/node_modules/ts-node/src/index.ts:1621:12)
at Module.load (node:internal/modules/cjs/loader:1427:32)
at Module._load (node:internal/modules/cjs/loader:1250:10)
at TracingChannel.traceSync (node:diagnostics_channel:322:10)
at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
*/
Get bus arrivals for a stop
// search for a bus stop using 5 digit code, which can be found on Google Maps
const query = "51800"; // Aldwych / Kingsway (F)
const modes = ['bus'];
const stopPointSearchResult = await client.stopPoint.search({ query, modes });
const stopPointId = stopPointSearchResult.matches?.[0]?.id;
if (!stopPointId) {
throw new Error(`No bus stop found for the given query: ${query}`);
}
console.log('Bus stop ID found:', stopPointId);
// Get arrivals for bus stop
const arrivals = await client.stopPoint.getArrivals({
stopPointIds: [stopPointId]
});
// Sort arrivals by time to station (earliest first)
const sortedArrivals = arrivals.sort((a, b) =>
(a.timeToStation || 0) - (b.timeToStation || 0)
);
sortedArrivals.forEach((arrival) => {
console.log(
`Bus ${arrival.lineName || 'Unknown'}` +
` to ${arrival.towards || 'Unknown'}` +
` arrives in ${Math.round((arrival.timeToStation || 0) / 60)}min`
);
});
/* console output:
Bus stop ID found: 490003191F
Bus stop Aldwych / Kingsway F:
Bus 1 to Russell Square Or Tottenham Court Road arrives in 4min
Bus 188 to Russell Square Or Tottenham Court Road arrives in 6min
Bus 1 to Russell Square Or Tottenham Court Road arrives in 8min
Bus 68 to Russell Square Or Tottenham Court Road arrives in 10min
Bus 68 to Russell Square Or Tottenham Court Road arrives in 12min
Bus 91 to Russell Square Or Tottenham Court Road arrives in 14min
Bus 188 to Russell Square Or Tottenham Court Road arrives in 19min
Bus 68 to Russell Square Or Tottenham Court Road arrives in 22min
Bus 1 to Russell Square Or Tottenham Court Road arrives in 29min
Bus 188 to Russell Square Or Tottenham Court Road arrives in 29min
*/
Please see the playgorund/demo folder for complete set of examples for each endpoint.
Line Colors and Branding
Get official TfL line colors with accessibility considerations:
import { getLineColor, getLineCssProps } from 'tfl-ts';
// Get line color information
const colors = getLineColor('central');
console.log(colors);
// Output: {
// hex: '#E32017',
// text: 'text-[#E32017]',
// bg: 'bg-[#E32017]',
// poorDarkContrast: false
// }
// Get CSS custom properties for CSS-in-JS
const cssProps = getLineCssProps('central');
console.log(cssProps);
// Output: {
// '--line-color': '#E32017',
// '--line-color-rgb': '227, 32, 23',
// '--line-color-contrast': '#000000'
// }
Severity Styling and Classification
Smart severity categorization and styling helpers:
import {
getSeverityCategory,
getSeverityClasses,
getAccessibleSeverityLabel
} from 'tfl-ts';
const severityLevel = 6; // Severe Delays
const description = 'Severe Delays';
// Get severity category for conditional styling
const category = getSeverityCategory(severityLevel); // 'severe'
// Get Tailwind CSS classes with optional animations
const classes = getSeverityClasses(severityLevel, true);
console.log(classes);
// Output: {
// text: 'text-orange-700',
// animation: 'animate-[pulse_1.5s_ease-in-out_infinite]'
// }
// Get accessible label for screen readers
const accessibleLabel = getAccessibleSeverityLabel(severityLevel, description);
// Output: 'Severe Delays - Significant delays expected'
Line Status Processing
Utilities for processing and displaying line statuses:
import {
sortLinesBySeverityAndOrder,
getLineStatusSummary,
isNormalService,
hasNightService,
getLineAriaLabel
} from 'tfl-ts';
// Get line statuses from API
const lineStatuses = await client.line.getStatus({ modes: ['tube', 'elizabeth-line', 'dlr'] });
// Sort lines by severity and importance (issues first, then by passenger volume)
const sortedLines = sortLinesBySeverityAndOrder(lineStatuses);
// Process each line for display
sortedLines.forEach(line => {
const summary = getLineStatusSummary(line.lineStatuses);
const ariaLabel = getLineAriaLabel(line.name, line.lineStatuses);
const isNormal = isNormalService(line.lineStatuses);
const hasNightClosure = hasNightService(line.lineStatuses);
console.log(`${line.name}: ${summary.worstDescription} (${summary.hasIssues ? 'Has issues' : 'Good service'})`);
});
🏗️ Contributing
Prerequisites
- Node.js 18+
- pnpm (recommended)
- TfL API credentials
Setup
git clone https://github.com/ghcpuman902/tfl-ts.git
cd tfl-ts
pnpm install
touch .env # Add your TfL API credentials
pnpm run build
Build Process
- Fast Build (
pnpm run build
): Types only, no API calls - Full Build (
pnpm run build:full
): Includes fresh metadata
Scripts
pnpm run build # Fast build
pnpm run build:full # Full build with metadata
pnpm run test # Run tests
pnpm run demo # Run demo
pnpm run playground # Interactive playground
Development Pattern
Each API module maps to a generated JSDoc file without importing from it. See LLM_context.md for detailed development guidelines.
📊 Status
Feature | Status | Coverage |
---|---|---|
Core Infrastructure | ✅ Complete | 100% |
API Modules | 🔄 9/14 Complete | 64% |
Type Generation | ✅ Complete | 100% |
Test Coverage | ✅ Good | 85%+ |
Documentation | ✅ Complete | 100% |
Edge Runtime | ✅ Complete | 100% |
Module | Status | Endpoints |
---|---|---|
✅ line |
Complete | 15+ |
✅ stopPoint |
Complete | 12+ |
✅ journey |
Complete | 8+ |
⚠️ accidentStats |
Deprecated | 1 |
⚠️ airQuality |
Deprecated | 1 |
✅ bikePoint |
Complete | 6+ |
✅ cabwise |
Complete | 3+ |
✅ road |
Complete | 8+ |
✅ mode |
Complete | 2/2 |
❌ occupancy |
Planned | 0/4 |
❌ place |
Planned | 0/8 |
❌ search |
Planned | 0/3 |
❌ travelTimes |
Planned | 0/5 |
❌ vehicle |
Planned | 0/3 |
Progress: 9/14 modules complete (64%)
📚 API Reference
Core Classes
TflClient
- Main client classLineApi
- Line and route informationStopPointApi
- Stop point and arrival informationJourneyApi
- Journey planningRoadApi
- Road traffic informationModeApi
- Transport mode information
Key Methods
line.getStatus()
- Get line status and disruptionsstopPoint.getArrivals()
- Get arrivals for a stopstopPoint.search()
- Search for stopsjourney.get()
- Plan a journeymode.getArrivals()
- Get mode-specific arrivals
🐛 Troubleshooting
Issue | Solution |
---|---|
Invalid API credentials | Check TFL_APP_ID and TFL_APP_KEY in TfL portal |
Type generation failed | Verify network access and API permissions |
Playground not loading | Run pnpm run build first |
📄 License
MIT License - see LICENSE
🙏 Acknowledgments
- Transport for London for the public API
- swagger-typescript-api for type generation
- London developer community for feedback and support
📞 Support
🗂️ Repository
Package | Version | License | Size |
---|---|---|---|
tfl-ts |
1.0.0 | MIT | ~150KB |
Links | URL |
---|---|
📦 npm | tfl-ts |
🐙 GitHub | ghcpuman902/tfl-ts |
🐛 Issues | Report bugs |
💬 Discussions | Community |
Open source - Track progress via commits, see roadmap in LLM_context.md