TrainsRadar

API publique

Documentation de l'API REST TrainsRadar

Base URL https://trainsradar.com
  • L'API n'envoie pas d'en-têtes CORS : appelez-la depuis un serveur, pas depuis un navigateur sur un autre domaine. Pour afficher la carte sur votre site, utilisez l'intégration.
  • Un paramètre invalide (pays inconnu, limite hors plage, jour non numérique) renvoie 400 avec un champ error.
  • Si vous réutilisez les données, les licences de leurs sources exigent une attribution : Sources de données et licences.
  • API v1 pour les entreprises

API v1 pour les entreprises

Une API en lecture seule, avec clé, pensée pour être intégrée à votre service : trains en circulation et départs en direct des pays dont la licence des données autorise l'usage commercial et la rediffusion.

Spécification OpenAPI 3.1

Clé et quota

Envoyez votre clé dans l'en-tête X-API-Key à chaque requête. L'offre Developer est gratuite, avec un quota bas (1 000 requêtes par jour) pour un usage non massif. Les en-têtes X-RateLimit-* indiquent combien il vous en reste ; le quota repart à zéro à 00:00 UTC.

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

Pour obtenir une clé, écrivez à info@trainsradar.com en expliquant ce que vous comptez en faire.

Endpoints

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

Licences

Seuls les pays dont la licence commerciale est vérifiée sont servis. Chaque ligne porte son champ license et chaque réponse les mentions à afficher à côté des données.

Pays disponibles aujourd'hui

  • Les erreurs arrivent sous la forme {error, code} ; celles du serveur portent aussi un requestId pour que nous puissions les retrouver.
  • Cette API accepte le CORS : vous pouvez l'appeler depuis le navigateur avec votre clé.
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
}