🔗 Integration Guide

DO NOT READ

The following documentation is for internal use only and should not be shared externally at this time.

We are working towards a public launch in the future, at which point this documentation will be revised and made available.

Please contact the Trackser team for any questions regarding access or usage during this private beta phase.

---

Authentication

All API requests require an API key passed as a query parameter:

GET /live/central/line/latest.json?key=YOUR_API_KEY

Your API key is issued on a per-project basis. Keep it secure and never commit it to version control.

Rate Limiting

Rate limits are enforced per API key and vary depending on your use case:

Metric	Limit	Description
Requests per second	Varies by tier	Contact us for your specific limits
Burst allowance	Up to 10 requests	Brief traffic spikes are allowed
Response time	50-200ms typical	Depends on data complexity

If you exceed limits, requests will receive HTTP 429 (Too Many Requests) responses. Contact us if you need higher limits for your use case.

Available Endpoints

Live Data

Line IDs

Use these line identifiers in the path:

bakerloo, central, circle, district, hammersmith-city, jubilee,
metropolitan, northern, piccadilly, victoria, waterloo-city

Example Requests

JavaScript / Node.js

const API_KEY = 'your-api-key';
const LINE_ID = 'central';

// Fetch latest data
const response = await fetch(`https://trackser.app/live/${LINE_ID}/line/latest.json?key=${API_KEY}`);
const data = await response.json();

// Get train count
console.log(`${data.trains.length} trains currently tracked`);

// Find trains heading to a specific destination
const elingTrains = data.trains.filter(t => 
  t.destinationName?.toLowerCase().includes('ealing')
);
console.log(`${elingTrains.length} trains to Ealing`);

Python

import requests
import json

API_KEY = 'your-api-key'
LINE_ID = 'northern'

url = f'https://trackser.app/live/{LINE_ID}/line/latest.json?key={API_KEY}'
response = requests.get(url)
data = response.json()

# Print summary
print(f"Data as of: {data['as_of']}")
print(f"Total trains: {len(data['trains'])}")

# Find stalled trains
stalled = [t for t in data['trains'] if t.get('isMaybeStalled')]
print(f"Potentially stalled: {len(stalled)} trains")

cURL

curl "https://trackser.app/live/jubilee/line/latest.json?key=YOUR_API_KEY" | jq '.trains | length'

Response Handling

Success Response (200)

Returns a JSON object with train data. Check the as_of timestamp to verify data freshness:

{
  "as_of": "2025-12-15T22:26:58.994Z",
  "sources": { ... },
  "status": "ok",
  "stats": { ... },
  "trains": [ ... ]
}

Common Error Responses

Status Code	Meaning	Action
401	Unauthorized - Invalid or missing API key	Check your API key and request headers
404	Not found - Invalid line ID or endpoint	Verify line ID and endpoint path
429	Too many requests - Rate limit exceeded	Slow down requests or contact us for higher limits
503	Service unavailable - TfL API or system issue	Check our status page and retry

Best Practices

• Cache responses: Data doesn't change more than every 30 seconds, so cache aggressively on your end
• Handle gzip: Most HTTP clients decompress automatically, but verify if needed
• Check timestamps: Always verify the as_of field to ensure you have fresh data
• Error handling: Implement retry logic with exponential backoff for transient failures
• API key security: Use environment variables, never hardcode keys in source code
• Monitor costs: Track API usage to stay within rate limits and control expenses
• Filter data: Use stats-only endpoint if you just need line health, not full train data

Webhooks & Real-time Updates

Currently, Trackser Live provides a REST polling interface. For future expansions, we're considering:

• WebSocket support for real-time train updates
• Server-Sent Events (SSE) for streaming data
• Webhook callbacks for significant events (major delays, service changes)

If real-time streaming is important for your use case, let us know at support@trackser.co.uk.

Troubleshooting

Getting empty train arrays

This usually means the line is not currently operational or TfL data collection failed. Check the status field and verify the line is running at the current time.

Data seems old

Check the as_of timestamp. If it's more than 2 minutes old, TfL's data source may be experiencing issues. Check the system status page.

Location data looks wrong

Track codes are inferred and sometimes ambiguous. Report issues with specific trains (include timestamp and train ID) to support@trackser.co.uk.

Support

For integration questions, technical issues, or feature requests related to API access, please reach out to support@trackser.co.uk.