TrainsRadar

Public API

TrainsRadar REST API documentation

Base URL https://trainsradar.com
  • The API sends no CORS headers: call it from a server, not from a browser on another domain. To show the map on your site, use the embed.
  • An invalid parameter (unknown country, limit out of range, non-numeric day) returns 400 with an error field.
  • If you reuse the data, the licences of its sources require attribution: Data sources and licences.
  • API v1 for businesses

API v1 for businesses

A read-only API with a key, built to plug into your service: running trains and live departures from the countries whose data licence allows commercial use and redistribution.

OpenAPI 3.1 specification

Key and quota

Send your key in the X-API-Key header with every request. The Developer plan is free, with a low quota (1,000 requests a day) for non-bulk use. The X-RateLimit-* headers tell you how many are left; the quota resets at 00:00 UTC.

curl -H "X-API-Key: $TRAINSRADAR_KEY" "https://trainsradar.com/api/v1/trains?country=FI"

To get a key, write to info@trainsradar.com and tell us what you will use it for.

Endpoints

  • GET /api/v1
  • GET /api/v1/trains
  • GET /api/v1/trains/{id}
  • GET /api/v1/stations/{id}/departures?country=XX

Licences

Only countries with a verified commercial licence are served. Every row carries its license field and every response the attributions you must show next to the data.

Countries available now

  • Errors come as {error, code}; server errors also carry a requestId so we can find them.
  • This API does allow CORS: you can call it from the browser with your key.
GET /api/trains
Probar

Trains currently running in one country (Spain unless `country` is given) or in all of them with country=ALL. Positions refresh about every 20 s.

Query Parameters

Parameter Description
country ISO country code (ES, DE, NL, FR, GB…, case-insensitive) or ALL. Defaults to ES. An unknown code is a 400.
type Only one train type (see Train.type), e.g. cercanias, ave, regional. Default: all
bounds Only trains inside north,south,east,west (decimal degrees)

Response

Train[]
GET /api/trains/:id

One running train by id (e.g. nl-2041) plus its last 10 recorded positions. 404 once the train is no longer running.

Response

{ train: Train, history: { lat, lng, recordedAt }[] }
GET /api/stations
Probar

Stations of one country, optionally filtered by name. country is required (400 without it).

Query Parameters

Parameter Description
q Case-insensitive substring of the station name (up to 64 characters; % and _ are literal)
country ISO country code (required)
limit Max results, 1–500 (default 50); anything else is a 400

Response

Station[] (with countryCode)
GET /api/stations/:id

Station details. Pass country: station ids are only unique within a country.

Query Parameters

Parameter Description
country ISO country code (recommended)

Response

Station (with countryCode)
GET /api/stations/:id/live
Probar

Next departures with real-time delay where the operator publishes it. This is what the station board and the embed widget show.

Query Parameters

Parameter Description
country ISO country code (ES, DE, NL, FR, GB…, case-insensitive) or ALL. Defaults to ES. An unknown code is a 400.
window Minutes ahead, 15–240 (default 90)
past Minutes back, 10–60 (default 10): trains that already left
arrivals 1 to also return arrivals (origin instead of destination)

Response

{ station, country, tz, generatedAt, departures: LiveDeparture[], arrivals?: LiveDeparture[], liveTrainsInCountry, nextDeparture, nextArrival? }
GET /api/stations/:id/board

Scheduled (timetable) departures for a whole service day. country is required.

Query Parameters

Parameter Description
country ISO country code (required)
day Next occurrence of a weekday (today included): 0 = Monday … 6 = Sunday, or its name (default: today in the station's time zone)

Response

{ scheduled: ScheduledDeparture[], availableLines: string[] }
GET /api/alerts
Probar

Service alerts currently in force (refreshed by the ingester in the last 2 hours). Alert ingestion is paused, so the list is normally empty.

Response

Alert[]
GET /api/stream

Server-Sent Events, same data as /api/trains. On connect, one "positions" event with the full Train[] snapshot. Then, about every 20 s, a "delta" event { u, r }: u lists trains that are new (complete Train) or changed (only id plus the fields that changed); r lists the ids of trains that left. Apply u by merging onto the train with the same id, then drop r.

Query Parameters

Parameter Description
country ISO country code (ES, DE, NL, FR, GB…, case-insensitive) or ALL. Defaults to ES. An unknown code is a 400.

Response

text/event-stream

Data Types

Train

{
  id: string,              // "<cc>-<operator id>", e.g. "nl-2041";
                           // Spain (Renfe) has no prefix: "23526"
  tripId: string | null,
  line: string | null,
  label: string | null,    // e.g. "NS 2041"
  lat: number,
  lng: number,
  status: "IN_TRANSIT_TO" | "STOPPED_AT" | "INCOMING_AT",  // GTFS-RT
  nextStopId: string | null,
  nextStopName: string | null,
  nextStopLat: number | null,
  nextStopLng: number | null,
  delay: number | null,    // seconds, null when the operator gives none
  type: string,            // e.g. "cercanias", "ave", "alvia", "regional", "intercity"
  operator: string | null,
  speedKmh: number | null,
  updatedAt: string,       // ISO 8601, when we last wrote the position
  fixAt: string | null,    // ISO 8601, when the source took the fix (null if it does not say)
  isInterpolated: boolean, // position estimated from the timetable
  countryCode: string
}

Station

{
  id: string,              // unique only within a country
  name: string,
  lat: number,
  lng: number,
  countryCode: string,
  hasCercanias: boolean,   // only set for some Spanish stations
  hasAtendo: boolean,      // Renfe assistance service, Spain only
  nucleus: null,           // legacy, never filled
  hasLd: false             // legacy, never filled
}

LiveDeparture

{
  scheduledTime: string,          // "HH:MM", station local time
  expectedTime: string,
  minutesToExpected: number,
  line: string | null,
  destination: string | null,
  operator: string | null,
  delaySeconds: number | null,
  platform: string | null,
  state: string,                  // e.g. "scheduled"
  trainId: string | null,         // matches Train.id when it is on the map
  distanceKm: number | null
}

Alert

{
  id: string,
  routes: string[],
  stops: string[],
  description: string,
  startTime: string,
  active: boolean
}