# Digitraffic Rail API

> Open data API for railway traffic in Finland: train timetables and real-time
> punctuality, live train GPS locations, train compositions (wagons and
> locomotives), track work and traffic restriction notifications, passenger
> information messages, and station/operator metadata. Published by Fintraffic
> on the Digitraffic platform; data comes from Fintraffic's traffic control
> and capacity management systems and the passenger
> information system. Free to use, no API key required. Data is
> licensed under CC BY 4.0 — attribute "Fintraffic / digitraffic.fi". Source
> data may contain gaps or errors — do not use for safety-critical
> applications.

Base URL: `https://rata.digitraffic.fi`

Key facts:

- All REST endpoints are HTTP GET and return JSON (GeoJSON variants where
  noted). The GraphQL endpoint accepts POST. No authentication is needed.
- Clients MUST send an `Accept-Encoding: gzip` request header (or br/zstd) —
  requests without compression support are rejected with HTTP 406.
- Set a `Digitraffic-User` request header identifying your application
  (e.g. `Digitraffic-User: my-company/my-app`). Requests with the header get
  a higher rate limit — without it you are restricted sooner (see
  https://www.digitraffic.fi/en/support/instructions/#restricting-requests).
  It also helps with support and usage statistics.
- Dates and times use ISO 8601 UTC; `departure_date` path parameters use
  `YYYY-MM-DD` (the date of the train's first departure, Finnish time).
- Incremental fetching: trains, live-trains, compositions, train-tracking and
  routesets responses carry a `version` number. Poll with `?version=<highest
  version seen>` to get only changed entities instead of full datasets.
- `GET /api/v1/last-updated` returns the last update time of each data type.
- Timetable and realization history reaches about 720 days back;
  train/composition version history is kept for 14 days.
- For continuous real-time tracking, prefer MQTT or GTFS-RT over polling.

## REST API endpoints

Trains and timetables:

- [GET /api/v1/trains/{departure_date}/{train_number}](https://rata.digitraffic.fi/swagger/): One train with timetable rows and punctuality (also `/latest/{train_number}`, all trains of a day via `/{departure_date}`)
- [GET /api/v1/trains?version=...](https://rata.digitraffic.fi/api/v1/trains): Trains changed since the given version
- [GET /api/v1/trains/history/{departure_date}/{train_number}](https://rata.digitraffic.fi/swagger/): Version history of a train (14 days)
- [GET /api/v1/live-trains/station/{station}](https://rata.digitraffic.fi/api/v1/live-trains/station/HKI?departing_trains=5): Arriving/departing trains of a station; limit by counts (`arrived_trains`, `arriving_trains`, `departed_trains`, `departing_trains`) or time windows (`minutes_before_departure` etc.); filter with `train_categories`
- [GET /api/v1/live-trains/station/{departure_station}/{arrival_station}](https://rata.digitraffic.fi/swagger/): Trains running between two stations
- [GET /api/v1/compositions/{departure_date}/{train_number}](https://rata.digitraffic.fi/swagger/): Train composition — wagons, locomotives, services (also day listing, `?version=` tracking and `/history/`)

Real-time locations and tracking:

- [GET /api/v1/train-locations.geojson/latest](https://rata.digitraffic.fi/api/v1/train-locations.geojson/latest): Latest GPS locations of all trains, GeoJSON; supports `bbox` (also plain-JSON `/train-locations/latest`, per-train `/latest/{train_number}` and history by `/{departure_date}/{train_number}`)
- [GET /api/v1/train-tracking/{departure_date}/{train_number}](https://rata.digitraffic.fi/swagger/): Train running messages (track-section level events; also by station and `?version=` tracking)
- [GET /api/v1/routesets/{departure_date}/{train_number}](https://rata.digitraffic.fi/swagger/): Route reservations (also by station and `?version=` tracking)

Notifications and messages:

- [GET /api/v1/trackwork-notifications.json](https://rata.digitraffic.fi/api/v1/trackwork-notifications.json): Track work notifications, filter by `state`, `start`, `end` (also `.geojson`, `/status`, `/{id}`, `/{id}/latest.json`)
- [GET /api/v1/trafficrestriction-notifications.json](https://rata.digitraffic.fi/api/v1/trafficrestriction-notifications.json): Traffic restriction notifications (same variants as track work)
- [GET /api/v1/passenger-information/active](https://rata.digitraffic.fi/api/v1/passenger-information/active): Active passenger information messages; filter by `station`, `train_number`, `train_departure_date`, `only_general` (also `/updated-after/{date}`)

Metadata:

- [GET /api/v1/metadata/stations](https://rata.digitraffic.fi/api/v1/metadata/stations): Stations with short codes and UIC codes (also `stations.geojson`)
- [GET /api/v1/metadata/operators](https://rata.digitraffic.fi/api/v1/metadata/operators): Railway operators
- Other metadata: `train-categories`, `train-types`, `cause-category-codes` (+ `detailed-`, `third-`), `track-sections`, `time-table-periods`, `train-running-message-rules`
- [GET /api/v1/last-updated](https://rata.digitraffic.fi/api/v1/last-updated): Last update time of each data type

Standard transit formats:

- GTFS (zip, generated daily): [gtfs-passenger.zip](https://rata.digitraffic.fi/api/v1/trains/gtfs-passenger.zip), [gtfs-passenger-stops.zip](https://rata.digitraffic.fi/api/v1/trains/gtfs-passenger-stops.zip) (use this with real-time feeds for matching stop_sequences), [gtfs-all.zip](https://rata.digitraffic.fi/api/v1/trains/gtfs-all.zip)
- GTFS-RT (protobuf, updated every 10 s): [gtfs-rt-locations](https://rata.digitraffic.fi/api/v1/trains/gtfs-rt-locations), [gtfs-rt-updates](https://rata.digitraffic.fi/api/v1/trains/gtfs-rt-updates)
- SIRI Nordic XML: [/api/v1/siri/et](https://rata.digitraffic.fi/api/v1/siri/et) (estimated timetables), `/api/v1/siri/vm` (vehicle monitoring), `/api/v1/siri/sx` (situation exchange)
- NeTEx Nordic: [/api/v1/netex/FTR-netex.zip](https://rata.digitraffic.fi/api/v1/netex/FTR-netex.zip)

Static datasets (updated daily):

- [GET /api/v1/yearly-plans/yearly-plans.json](https://rata.digitraffic.fi/api/v1/yearly-plans/yearly-plans.json): Track work yearly plans
- [GET /api/v1/project-plans/project-plans.json](https://rata.digitraffic.fi/api/v1/project-plans/project-plans.json): Track work project plans

## GraphQL API

Flexible filtering, ordering and field selection over the same data:

- Endpoint: `POST https://rata.digitraffic.fi/api/v2/graphql/graphql`
  (JSON body: `{"query": "..."}`)
- [GraphiQL browser](https://rata.digitraffic.fi/api/v2/graphql/graphiql) and
  [schema diagram](https://rata.digitraffic.fi/api/v2/graphql/schema.svg)

Example — currently running VR trains with their latest location:

```
{
  currentlyRunningTrains(where: {operator: {shortCode: {equals: "vr"}}}) {
    trainNumber
    departureDate
    trainLocations(orderBy: {timestamp: DESCENDING}, take: 1) {
      speed
      timestamp
      location
    }
  }
}
```

## API reference

- [OpenAPI specification (JSON)](https://rata.digitraffic.fi/swagger/openapi.json): Authoritative machine-readable reference — all endpoints, query parameters, and response schemas. Fetch this for complete details.
- [Interactive documentation (Swagger UI)](https://rata.digitraffic.fi/swagger/): Human-readable API browser (JavaScript app, not useful for automated crawling)
- [Infra-API](https://rata.digitraffic.fi/infra-api/): Detailed description of the Finnish railway network
- [Jeti-API](https://rata.digitraffic.fi/jeti-api/): Railway network maintenance work data

## MQTT over WebSocket (real-time streaming)

For continuous tracking, connect to `wss://rata.digitraffic.fi:443/mqtt`
(MQTT over WebSockets, SSL required; plain TCP at
`rata-mqtt.digitraffic.fi:1883`) and subscribe to topics:

- `trains/<departure_date>/<train_number>/#` — train timetable/punctuality
  updates; also `trains-by-station/<station>`
- `train-locations/<departure_date>/<train_number>` — GPS locations
- `train-tracking/<departure_date>/<train_number>/#` — running messages
- `compositions/<departure_date>/<train_number>/#` — composition changes
- `routesets/<departure_date>/<train_number>` — route reservations

Use `#` and `+` wildcards (e.g. `train-locations/#` for all trains,
`compositions/+/5/#` for train number 5). Payloads are the same JSON as the
REST responses. Include your application name in the MQTT client id and
disconnect when not actively consuming data.

## Example

Next five trains departing from Helsinki (station short code HKI):

```
curl --compressed -H "Digitraffic-User: my-company/my-app" \
  "https://rata.digitraffic.fi/api/v1/live-trains/station/HKI?departing_trains=5&departed_trains=0&arriving_trains=0&arrived_trains=0"
```

One train's timetable and punctuality for a given departure date:

```
curl --compressed -H "Digitraffic-User: my-company/my-app" \
  "https://rata.digitraffic.fi/api/v1/trains/2026-11-06/59"
```

## Optional

- [Digitraffic railway traffic documentation (English)](https://www.digitraffic.fi/en/railway-traffic/): GraphQL, GTFS and service description
- [Railway documentation (Finnish, more detailed)](https://www.digitraffic.fi/rautatieliikenne/): Full REST and MQTT reference with response type descriptions
- [Digitraffic terms of service](https://www.digitraffic.fi/en/terms-of-service/): Usage terms and CC BY 4.0 license details
- [Supported and deprecated APIs](https://www.digitraffic.fi/en/support/api-changes/): API lifecycle announcements
- [Train history tool](https://rata.digitraffic.fi/history): Inspect past states of trains and compositions
- Test environment: `https://rata-beta.digitraffic.fi` (same paths; data may be incomplete)