iRail API Docs

API Endpoint

iRail supports digital creativity concerning mobility in Belgium. This is an attempt to make the railway time schedules in Belgium easily available for anyone.

The iRail api allows anyone to query trains, stations, liveboards and connections.

The API is available at https://api.irail.be.

TLS 1.1 or higher is required to access the API. If you’re developing an application, and SSL handshake errors occur, you need to use a newer security protocol. HTTPS is supported over TLS1.1 and higher. SSL, SSL2, SSL3 and TLS1.0 are disabled as those protocols are considered unsafe.

You can check the current status of the API at status.irail.be

Best practices when using the API

If you build an application on top of the iRail api, be sure to do at least one of the following things:

If possible, set the user-agent header string. Include the name of your application, and a way to contact you in case something would go wrong. An example user agent string format is <application name>/<application version> (<website>; <mail>), which could result in the following string: irail/1.2.0 (irail.be; hello@irail.be). The use of a user agent string like this isn’t obligated or enforced, but allows for better communication.
If you can’t set the user agent string, at least be sure to follow us on github, website or gitter.

Request limits

You can make up to 3 requests per second per source IP address. Every IP address also has 5 burst requests, meaning you can either have 8 requests in 1 second or 15 requests in 3 seconds, but you will need to drop below 3 requests per second in order for these burst requests to refill.

Exceeding the request limit will cause the server to return 429 responses.

Request limits are set so everyone can enjoy open transport data with high availability and fast response times. Please don’t use excessive polling: always optimise your application, even when you’re not reaching our request limitations (yet). We include HTTP headers to signal how long our data is valid, please refrain from making the same request again before this period has elapsed.

Are you limited by our request limits? Get in touch to see if we can work out a better request strategy together.

Always undertake action when your application receives frequent “429 Too Many Requests” responses! When your application causes too much requests, one of the following actions will happen

When the user agent is set, we will contact the developers at the provided e-mail address or website. In case of excessive requests for a long period of time (e.g. multiple 439 responses per second for more than 3 hours), your application might be blocked before we receive a response. We will still contact you to assist with resolving the issue and increasing the efficiency of your requests.
When no user agent is set, the source IP address will be blocked without prior warnings. If your IP address is blocked, please contact the iRail team to resolve this.

URIs

The iRail API uses URIs (Uniform Resource Identifications) to identify departures, stations, trains and occupancies. This way, there can be no misinterpretations. While there might be multiple meanings or interpretations possible for “Brussels South” (for example, the railway station, the airport, maybe the region south of Brussels), the URI http://irail.be/stations/NMBS/008814001 means the railway station Brussels south, and nothing else. The meaning of this URI doesn’t change on other websites, APIs, or datasets. URIs don’t change often, and don’t have to be human readable. They can change however, therefore they shouldn’t be composed by the user, but should be retrieved from a previous response.

URI’s are ids, just like numeric ids. While in this case they represent a URL, these URLs do not make part of the API! All API requests go to https://api.irail.be! Ids can be used on any domain, but if the id is the same url, you know that the objects represent the same thing, even if they are in different APIs or applications.

URIs in use by the iRail API

The following objects are identified by a URI:

Stations: every station has a URI, similar to http://irail.be/stations/NMBS/008814001, where 008814001 is based on an existing identifier used by the NMBS.
Vehicles: every vehicle has a URI, which identifies the trip at a certain time which is made by this vehicle. An example URI is http://irail.be/vehicle/IC532.
Departures: A departure is a certain train, leaving a certain station, at a certain day. The combination of these 3 fields is unique through time, which makes it perfect as an identifier. Example: http://irail.be/connections/8814001/20171002/IC532.

Caching

The API supports caching and conditional get requests. Conditional get requests allow you to tell the server which version of the data you have. If there is newer data available, the server will return an HTTP 200 status code along with the new data. If no new data is available, the server will return an HTTP 304 Not Modified status code, along with an empty body. The benefits of caching are less data transfer, and faster responses in case of a 304 response.

Supported request headers

If-None-Match

Supported response headers

Bug reports

You can report bugs in the api on the API github repository. You can report mistakes in the documentation on the documentation github repository.

Stations ¶

Retrieve a list of all stations. Alternatively, you can check out our repo at https://github.com/iRail/stations for a CSV of all stations, and nodejs scripts to convert this CSV to other formats.

Stations API ¶

GET /stations/?format=json&lang=en

RequestsJsonXML

Headers

Accept: application/json

Responses200

Headers

Content-Type: application/json
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

{
  "version": "1.1",
  "timestamp": 1489621486,
  "station": {
    "id": "BE.NMBS.008821006",
    "@id": "http://irail.be/stations/NMBS/008821006",
    "locationX": 4.421101,
    "locationY": 51.2172,
    "standardname": "Antwerpen-Centraal",
    "name": "Antwerp-Central"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "timestamp": {
      "type": "number"
    },
    "station": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The (iRail) id of the station. The NMBS id can be deducted by removing the leading 'BE.NMBS.00'"
        },
        "@id": {
          "type": "string"
        },
        "locationX": {
          "type": "number",
          "description": "The longitude of the station"
        },
        "locationY": {
          "type": "number",
          "description": "The latitude of the station"
        },
        "standardname": {
          "type": "string",
          "description": "The consistent name of this station"
        },
        "name": {
          "type": "string",
          "description": "The default name of this station"
        }
      },
      "required": [
        "id",
        "@id",
        "locationX",
        "locationY",
        "standardname",
        "name"
      ]
    }
  },
  "required": [
    "version",
    "timestamp",
    "station"
  ]
}

Headers

Accept: application/xml

Responses200

Headers

Content-Type: application/xml
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

<stations version="1.1" timestamp="1489621390">
   <station id="BE.NMBS.007015400" locationX="-0.1260606" locationY="51.5310399" URI="http://irail.be/stations/NMBS/007015400" standardname="London Saint Pancras International">London Saint Pancras International</station>
</stations>

Retrieve all stations
GET`/stations/{?format,lang}`

URI Parameters

HideShow

format

string (optional) Default: xml Example: json

The response format

Choices: xml json jsonp

lang

string (optional) Default: en Example: en

The language of any text or names in the response.

Choices: nl fr en de

Liveboard ¶

Liveboards provides real-time informations on arriving and departing trains for every Belgian station.

Liveboard API ¶

Be aware

Trying to query data way in the past, or way in the future, might result in error 500 responses. If you’re not sure what causes an error 500 response, be sure to check if your query works for the current day, or if the NMBS website has the data for the date you want to look up.

GET /liveboard/?id=BE.NMBS.008892007&station=Gent-Sint-Pieters&date=300917&time=1230&arrdep=departure&lang=en&format=json&alerts=false

RequestsJsonXML

Headers

Accept: application/json

Responses200

Headers

Content-Type: application/json
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

{
  "version": "1.1",
  "timestamp": 1489614297,
  "station": "Ghent-Sint-Pieters",
  "stationinfo": {
    "id": "BE.NMBS.008821006",
    "@id": "http://irail.be/stations/NMBS/008821006",
    "locationX": 4.421101,
    "locationY": 51.2172,
    "standardname": "Antwerpen-Centraal",
    "name": "Antwerp-Central"
  },
  "departures": {
    "number": 32,
    "departure": [
      {
        "id": 0,
        "delay": 0,
        "station": "Antwerp-Central",
        "stationinfo": {
          "id": "BE.NMBS.008821006",
          "@id": "http://irail.be/stations/NMBS/008821006",
          "locationX": 4.421101,
          "locationY": 51.2172,
          "standardname": "Antwerpen-Centraal",
          "name": "Antwerp-Central"
        },
        "time": 1489575600,
        "vehicle": "BE.NMBS.IC3033",
        "vehicleinfo": {
          "name": "BE.NMBS.IC3033",
          "shortname": "IC3033",
          "@id": "http://irail.be/vehicle/IC3033"
        },
        "platform": 4,
        "platforminfo": {
          "name": "4",
          "normal": "1"
        },
        "canceled": 0,
        "left": 0,
        "departureConnection": "http://irail.be/connections/8821006/20170316/IC1832",
        "occupancy": {
          "@id": "http://api.irail.be/terms/unknown",
          "name": "unknown"
        }
      }
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "timestamp": {
      "type": "number"
    },
    "station": {
      "type": "string"
    },
    "stationinfo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The (iRail) id of the station. The NMBS id can be deducted by removing the leading 'BE.NMBS.00'"
        },
        "@id": {
          "type": "string"
        },
        "locationX": {
          "type": "number",
          "description": "The longitude of the station"
        },
        "locationY": {
          "type": "number",
          "description": "The latitude of the station"
        },
        "standardname": {
          "type": "string",
          "description": "The consistent name of this station"
        },
        "name": {
          "type": "string",
          "description": "The default name of this station"
        }
      },
      "required": [
        "id",
        "@id",
        "locationX",
        "locationY",
        "standardname",
        "name"
      ]
    },
    "departures": {
      "type": "object",
      "properties": {
        "number": {
          "type": "number"
        },
        "departure": {
          "type": "array"
        }
      },
      "required": [
        "number"
      ]
    }
  },
  "required": [
    "version",
    "timestamp",
    "station",
    "departures"
  ]
}

Headers

Accept: application/xml

Responses200

Headers

Content-Type: application/xml
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

<liveboard version="1.1" timestamp="1489614530">
    <station id="BE.NMBS.008892007" locationX="3.710675" locationY="51.035896" URI="http://irail.be/stations/NMBS/008892007" standardname="Gent-Sint-Pieters">Ghent-Sint-Pieters</    station>
    <departures number="32">
        <departure id="0" delay="0" canceled="0" left="0">
            <station id="BE.NMBS.008892908" locationX="3.602552" locationY="50.742506" URI="http://irail.be/stations/NMBS/008892908" standardname="Ronse">Ronse</station>
            <time formatted="2017-03-15T12:00:00">1489575600</time>
            <vehicle URI="http://irail.be/vehicle/L782">BE.NMBS.L782</vehicle>
            <platform normal="1">4</platform>
            <departureConnection>http://irail.be/connections/8892007/20170315/L782</departureConnection>
            <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
        </departure>
    </departures>
</liveboard>

Retrieve a liveboard
GET`/liveboard/{?id,station,date,time,arrdep,lang,format,alerts}`

A liveboard for a specified station. This includes departures or arrivals, along with their delays, train ids, occupancy, …

URI Parameters

HideShow

station

string (required) Example: Gent-Sint-Pieters

The name of the station to query.

id

string (optional) Example: BE.NMBS.008892007

If you know the id of a station, this might be used instead of a name. Do not use an id and a name at the same time.

arrdep

string (optional) Default: departure Example: departure

Whether the results should show arrivals departures in the station.

Choices: departure arrival

alerts

boolean (optional) Example: false

Whether or not to include alerts about a train in the response. This could be railworks etc, announced on the NMBS website.

time

string (optional) Default: current time in Belgium Example: 1230

The time to query.

The time is formatted as hhmm.

date

string (optional) Default: current date in Belgium Example: 300917

The date to query.

The date is formatted as ddmmyy.

format

string (optional) Default: xml Example: json

The response format

Choices: xml json jsonp

lang

string (optional) Default: en Example: en

The language of any text or names in the response.

Choices: nl fr en de

Connections ¶

Get routes between two stations, including realtime data on delays.

Connections API ¶

As of January 20, the following data has been added:

Intermediate stops are stops where the train will stop, but where the traveller remains seated.

Alerts are available in the following ways:

connection: These are all alerts for this connection object. Each alert is unique.
departure, via departure: These are the alerts for the train which departed Even though this might duplicate data, this allows anyone to process it easily. Thanks to gzip compression this won’t affect the transferred data size.

Be aware

Handling a walking via

In some cases, there might be a walking part in a route. This happens for example when a user arrives in Haren-Zuid and has a next train in Haren, only a few hundred meters further.

For walking parts, don’t attempt to parse train ids or destinations.
Don’t exclude routes which contain walking parts by default, but feel free to give users the option to do so. For example the route Aarschot-Meiser has a small walking part, whereas avoiding that walking part will cause the user to arrive significantly earlier or later.
Walking parts won’t be the first or last part of a route. They can only occur between vias.

GET /connections/?from=Gent-Sint-Pieters&to=Mechelen&date=300917&time=1230&timesel=departure&format=json&lang=en&typeOfTransport=automatic&alerts=false&results=6

RequestsJsonXML

Headers

Accept: application/json

Responses200400404500

Headers

Content-Type: application/json
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

{
  "version": "1.1",
  "timestamp": 1489622781,
  "connection": [
    {
      "id": 0,
      "departure": {
        "delay": 0,
        "station": "Antwerp-Central",
        "stationinfo": {
          "id": "BE.NMBS.008821006",
          "@id": "http://irail.be/stations/NMBS/008821006",
          "locationX": 4.421101,
          "locationY": 51.2172,
          "standardname": "Antwerpen-Centraal",
          "name": "Antwerp-Central"
        },
        "time": 1497783600,
        "vehicle": "BE.NMBS.IC3033",
        "vehicleinfo": {
          "name": "BE.NMBS.IC3033",
          "shortname": "IC3033",
          "@id": "http://irail.be/vehicle/IC3033"
        },
        "platform": 4,
        "platforminfo": {
          "name": "4",
          "normal": "1"
        },
        "left": 0,
        "canceled": 0,
        "direction": {
          "name": "Mechelen"
        },
        "stops": {
          "number": 1,
          "stop": [
            {
              "id": 0,
              "station": "Antwerp-central",
              "stationinfo": {
                "id": "BE.NMBS.008821006",
                "@id": "http://irail.be/stations/NMBS/008821006",
                "locationX": 4.421101,
                "locationY": 51.2172,
                "standardname": "Antwerpen-Centraal",
                "name": "Antwerp-Central"
              },
              "time": 1489658760,
              "delay": 0,
              "canceled": 0,
              "departureDelay": 0,
              "departureCanceled": 0,
              "scheduledDepartureTime": 1489658760,
              "arrivalDelay": 0,
              "arrivalCanceled": 0,
              "isExtraStop": 0,
              "scheduledArrivalTime": 1489658760,
              "departureConnection": "http://irail.be/connections/8821006/20170316/IC3033"
            }
          ]
        },
        "alerts": {
          "number": 1,
          "alert": [
            {
              "id": 0,
              "header": "L 50: We are conducting work for you between Ghent and Aalst.",
              "lead": "We are conducting work for you between Ghent and Aalst",
              "link": "http%3A%2F%2Fwww.belgianrail.be%2Fjp%2Fdownload%2Fbrail_him%2F1509444366969_NL-11015.pdf",
              "startTime": 1509441420,
              "endTime": 1510527540
            }
          ]
        },
        "walking": 0,
        "departureConnection": "http://irail.be/connections/8821006/20170316/IC1832"
      },
      "arrival": {
        "delay": 0,
        "station": "Antwerp-Central",
        "stationinfo": {
          "id": "BE.NMBS.008821006",
          "@id": "http://irail.be/stations/NMBS/008821006",
          "locationX": 4.421101,
          "locationY": 51.2172,
          "standardname": "Antwerpen-Centraal",
          "name": "Antwerp-Central"
        },
        "time": 1497786840,
        "vehicle": "BE.NMBS.IC3033",
        "vehicleinfo": {
          "name": "BE.NMBS.IC3033",
          "shortname": "IC3033",
          "@id": "http://irail.be/vehicle/IC3033"
        },
        "platform": 4,
        "platforminfo": {
          "name": "4",
          "normal": "1"
        },
        "arrived": 0,
        "canceled": 0,
        "walking": 0,
        "direction": {
          "name": "Mechelen"
        }
      },
      "duration": 3240,
      "alerts": {
        "number": 1,
        "alert": [
          {
            "id": 0,
            "header": "L 50: We are conducting work for you between Ghent and Aalst.",
            "lead": "We are conducting work for you between Ghent and Aalst",
            "link": "http%3A%2F%2Fwww.belgianrail.be%2Fjp%2Fdownload%2Fbrail_him%2F1509444366969_NL-11015.pdf",
            "startTime": 1509441420,
            "endTime": 1510527540
          }
        ]
      },
      "vias": {
        "number": 1,
        "via": [
          {
            "id": "Hello, world!",
            "arrival": {
              "time": 1497783600,
              "platform": 4,
              "platforminfo": {
                "name": "4",
                "normal": "1"
              },
              "arrived": 0,
              "delay": 0,
              "canceled": 0,
              "vehicle": "BE.NMBS.IC3033",
              "walking": 0,
              "direction": {
                "name": "Mechelen"
              }
            },
            "departure": {
              "time": 1497783600,
              "platform": 4,
              "platforminfo": {
                "name": "4",
                "normal": "1"
              },
              "left": 0,
              "delay": 0,
              "canceled": 0,
              "departureConnection": "http://irail.be/connections/8821006/20170316/IC1832",
              "vehicle": "BE.NMBS.IC3033",
              "walking": 0,
              "alerts": {
                "number": 1,
                "alert": [
                  {
                    "id": 0,
                    "header": "L 50: We are conducting work for you between Ghent and Aalst.",
                    "lead": "We are conducting work for you between Ghent and Aalst",
                    "link": "http%3A%2F%2Fwww.belgianrail.be%2Fjp%2Fdownload%2Fbrail_him%2F1509444366969_NL-11015.pdf",
                    "startTime": 1509441420,
                    "endTime": 1510527540
                  }
                ]
              },
              "direction": {
                "name": "Mechelen"
              },
              "stops": {
                "number": 1,
                "stop": [
                  {
                    "id": 0,
                    "station": "Antwerp-central",
                    "stationinfo": {
                      "id": "BE.NMBS.008821006",
                      "@id": "http://irail.be/stations/NMBS/008821006",
                      "locationX": 4.421101,
                      "locationY": 51.2172,
                      "standardname": "Antwerpen-Centraal",
                      "name": "Antwerp-Central"
                    },
                    "time": 1489658760,
                    "delay": 0,
                    "canceled": 0,
                    "departureDelay": 0,
                    "departureCanceled": 0,
                    "scheduledDepartureTime": 1489658760,
                    "arrivalDelay": 0,
                    "arrivalCanceled": 0,
                    "isExtraStop": 0,
                    "scheduledArrivalTime": 1489658760,
                    "departureConnection": "http://irail.be/connections/8821006/20170316/IC3033"
                  }
                ]
              }
            },
            "timeBetween": 360,
            "station": "Antwerp-Central",
            "stationinfo": {
              "id": "BE.NMBS.008821006",
              "@id": "http://irail.be/stations/NMBS/008821006",
              "locationX": 4.421101,
              "locationY": 51.2172,
              "standardname": "Antwerpen-Centraal",
              "name": "Antwerp-Central"
            },
            "vehicle": "BE.NMBS.IC3033",
            "direction": {
              "name": "Mechelen"
            }
          }
        ]
      }
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "timestamp": {
      "type": "number"
    },
    "connection": {
      "type": "array"
    }
  },
  "required": [
    "version",
    "timestamp",
    "connection"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": 400,
  "message": "to not set. Please review your request and add the right parameters"
}

Headers

Content-Type: application/json

Body

{
  "error": 404,
  "message": "Could not match 'query' with a station id in iRail. Please report this issue at https://github.com/irail/stations/issues/new if you think we should support your query."
}

Headers

Content-Type: application/json

Body

{
  "error": 500,
  "message": "Could not get data. Please report this issue at https://github.com/irail/irail/issues/new"
}

Headers

Accept: application/xml

Responses200404

Headers

Content-Type: application/xml
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

<connections version="1.1" timestamp="1581855654">
    <connection id="0">
        <departure delay="0" canceled="0" left="0" walking="0">
            <station locationX="2.925809" locationY="51.228212" id="BE.NMBS.008891702"
                     URI="http://irail.be/stations/NMBS/008891702" standardname="Oostende">Oostende
            </station>
            <time formatted="2020-02-16T14:09:00">1581858540</time>
            <vehicle>BE.NMBS.IC1814</vehicle>
            <platform normal="0">6</platform>
            <stops number="2">
                <stop id="0" arrived="0" left="0" isExtraStop="0">
                    <station locationX="3.216726" locationY="51.197226" id="BE.NMBS.008891009"
                             URI="http://irail.be/stations/NMBS/008891009" standardname="Brugge">Brugge
                    </station>
                    <scheduledArrivalTime formatted="2020-02-16T14:23:00">1581859380</scheduledArrivalTime>
                    <arrivalCanceled>0</arrivalCanceled>
                    <arrivalDelay>0</arrivalDelay>
                    <scheduledDepartureTime formatted="2020-02-16T14:25:00">1581859500</scheduledDepartureTime>
                    <departureDelay>0</departureDelay>
                    <departureCanceled>0</departureCanceled>
                    <departureConnection>http://irail.be/connections/8891009/20200216/IC1814</departureConnection>
                </stop>
            </stops>
            <departureConnection>http://irail.be/connections/8891702/20200216/IC1814</departureConnection>
            <direction>Antwerpen-Centraal</direction>
            <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
        </departure>
        <arrival delay="0" canceled="0" arrived="0" walking="0">
            <station locationX="4.937415" locationY="51.322032" id="BE.NMBS.008821907"
                     URI="http://irail.be/stations/NMBS/008821907" standardname="Turnhout">Turnhout
            </station>
            <time formatted="2020-02-16T17:47:00">1581871620</time>
            <vehicle>BE.NMBS.IC4237</vehicle>
            <platform normal="1">2</platform>
            <direction>Turnhout</direction>
        </arrival>
        <vias number="1">
            <via id="0">
                <arrival isExtraStop="0" delay="0" canceled="0" arrived="0" walking="0">
                    <time formatted="2020-02-16T15:52:00">1581864720</time>
                    <platform normal="1">10</platform>
                    <direction>Antwerpen-Centraal</direction>
                    <vehicle>BE.NMBS.IC1814</vehicle>
                    <departureConnection>http://irail.be/connections/8821121/20200216/IC1814</departureConnection>
                </arrival>
                <departure isExtraStop="0" delay="0" canceled="0" left="0" walking="0">
                    <time formatted="2020-02-16T16:39:00">1581867540</time>
                    <platform normal="1">5</platform>
                    <direction>Turnhout</direction>
                    <vehicle>BE.NMBS.IC4237</vehicle>
                    <stops number="7">
                        <stop id="0" arrived="0" left="0" isExtraStop="0">
                            <station locationX="4.448437" locationY="51.18296" id="BE.NMBS.008821147"
                                     URI="http://irail.be/stations/NMBS/008821147" standardname="Mortsel">Mortsel
                            </station>
                            <scheduledArrivalTime formatted="2020-02-16T16:42:00">1581867720</scheduledArrivalTime>
                            <arrivalCanceled>0</arrivalCanceled>
                            <arrivalDelay>0</arrivalDelay>
                            <scheduledDepartureTime formatted="2020-02-16T16:43:00">1581867780</scheduledDepartureTime>
                            <departureDelay>0</departureDelay>
                            <departureCanceled>0</departureCanceled>
                            <departureConnection>http://irail.be/connections/8821147/20200216/IC4237
                            </departureConnection>
                        </stop>
                    </stops>
                    <departureConnection>http://irail.be/connections/8821121/20200216/IC4237</departureConnection>
                    <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
                </departure>
                <timeBetween>2820</timeBetween>
                <station locationX="4.432221" locationY="51.19923" id="BE.NMBS.008821121"
                         URI="http://irail.be/stations/NMBS/008821121" standardname="Antwerpen-Berchem">
                    Antwerpen-Berchem
                </station>
                <vehicle>BE.NMBS.IC1814</vehicle>
                <direction>Antwerpen-Centraal</direction>
            </via>
        </vias>
        <duration>13080</duration>
        <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
    </connection>
</connections>

Headers

Content-Type: application/xml

Body

<error code="404">Could not match "samplestation" with a station id in iRail. Please report this issue at https://github.com/irail/stations/issues/new if you think we should support your query.</error>

Retrieve connections
GET`/connections/{?from,to,date,time,timesel,format,lang,typeOfTransport,alerts,results}`

URI Parameters

HideShow

from

string (required) Example: Gent-Sint-Pieters

The name or id of the station of departure.

to

string (required) Example: Mechelen

The name or id of the destination.

timesel

string (optional) Default: departure Example: departure

Whether the results should show arrivals departures in the station.

Choices: departure arrival

typeOfTransport

string (optional) Default: automatic Example: automatic

The types of transport to include in the search. Automatic will only allow national (normal) trains for travelling between two stations in Belgium, but will still allow international high speed trains for travel outside Belgium.

Choices: automatic trains nointernationaltrains all

alerts

boolean (optional) Example: false

(Deprecated) Whether or not to include alerts about a route in the response. This could be railworks etc, announced on the NMBS website. Note: alerts are now always included

results

number (optional) Example: 6

(Deprecated) The number of results to return. Default value is 6. This might be used as a guideline for the server, but there is no guarantee the server will return this exact amount of results!

time

string (optional) Default: current time in Belgium Example: 1230

The time to query.

The time is formatted as hhmm.

date

string (optional) Default: current date in Belgium Example: 300917

The date to query.

The date is formatted as ddmmyy.

format

string (optional) Default: xml Example: json

The response format

Choices: xml json jsonp

lang

string (optional) Default: en Example: en

The language of any text or names in the response.

Choices: nl fr en de

Vehicle ¶

Retrieve information about a vehicle.

Vehicle API ¶

As of November 2017, the following data has been added:

isExtraStop indicates that this stop was not part of the original planned route, but was added last-minute by trafic control.

Be aware

GET /vehicle/?id=BE.NMBS.IC1832&date=300917&format=json&lang=en&alerts=false

RequestsJsonXML

Headers

Accept: application/json

Responses200404

Headers

Content-Type: application/json
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

{
  "version": "1.1",
  "timestamp": 1489621902,
  "vehicle": "BE.NMBS.IC3033",
  "vehicleinfo": {
    "name": "BE.NMBS.IC3033",
    "locationX": 4.421101,
    "locationY": 51.2172,
    "shortname": "IC3033",
    "@id": "http://irail.be/vehicle/IC3033"
  },
  "stops": {
    "number": 10,
    "stop": [
      {
        "id": 0,
        "station": "Antwerp-central",
        "stationinfo": {
          "id": "BE.NMBS.008821006",
          "@id": "http://irail.be/stations/NMBS/008821006",
          "locationX": 4.421101,
          "locationY": 51.2172,
          "standardname": "Antwerpen-Centraal",
          "name": "Antwerp-Central"
        },
        "time": 1489658760,
        "delay": 0,
        "platform": 4,
        "platforminfo": {
          "name": "4",
          "normal": "1"
        },
        "canceled": 0,
        "departureDelay": 0,
        "departureCanceled": 0,
        "scheduledDepartureTime": 1489658760,
        "arrivalDelay": 0,
        "arrivalCanceled": 0,
        "isExtraStop": 0,
        "scheduledArrivalTime": 1489658760,
        "departureConnection": "http://irail.be/connections/8821006/20170316/IC3033",
        "occupancy": {
          "@id": "http://api.irail.be/terms/unknown",
          "name": "unknown"
        }
      }
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "timestamp": {
      "type": "number"
    },
    "vehicle": {
      "type": "string"
    },
    "vehicleinfo": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "locationX": {
          "type": "number"
        },
        "locationY": {
          "type": "number"
        },
        "shortname": {
          "type": "string"
        },
        "@id": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "locationX",
        "locationY",
        "shortname",
        "@id"
      ]
    },
    "stops": {
      "type": "object",
      "properties": {
        "number": {
          "type": "number"
        },
        "stop": {
          "type": "array"
        }
      },
      "required": [
        "number"
      ]
    }
  },
  "required": [
    "vehicle"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": 404,
  "message": "Route not available."
}

Headers

Accept: application/xml

Responses200404

Headers

Content-Type: application/xml
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

<vehicleinformation version="1.1" timestamp="1505995100">
    <vehicle locationX="3.216726" locationY="51.197226" shortname="IC1832" URI="http://irail.be/vehicle/IC1832">BE.NMBS.IC1832</vehicle>
    <stops number="10">
        <stop id="0" delay="240" canceled="0" left="1" isExtraStop="0">
            <station id="BE.NMBS.008821006" locationX="4.421101" locationY="51.2172" URI="http://irail.be/stations/NMBS/008821006" standardname="Antwerpen-Centraal">Antwerp-Central</station>
            <time formatted="2017-09-21T11:06:00">1505984760</time>
            <platform normal="1">1</platform>
            <departureDelay>240</departureDelay>
            <departureCanceled>0</departureCanceled>
            <scheduledDepartureTime formatted="2017-09-21T11:06:00">1505984760</scheduledDepartureTime>
            <scheduledArrivalTime formatted="2017-09-21T11:06:00">1505984760</scheduledArrivalTime>
            <arrivalDelay>0</arrivalDelay>
            <arrivalCanceled>0</arrivalCanceled>
            <departureConnection>http://irail.be/connections/8821006/20170921/IC1832</departureConnection>
            <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
        </stop>
    </stops>    
</vehicleinformation>

Headers

Content-Type: application/xml

Body

<error code="404">Route not available.</error>

Retrieve a vehicle
GET`/vehicle/{?id,date,format,lang,alerts}`

Retrieve information about a vehicle (train), including stops, occupancy, current location and delays.

URI Parameters

HideShow

id

string (required) Example: BE.NMBS.IC1832

date

string (optional) Default: current date in Belgium Example: 300917

The date to query.

The date is formatted as ddmmyy.

alerts

boolean (optional) Example: false

Whether or not to include alerts about a train in the response. This could be railworks etc, announced on the NMBS website.

format

string (optional) Default: xml Example: json

The response format

Choices: xml json jsonp

lang

string (optional) Default: en Example: en

The language of any text or names in the response.

Choices: nl fr en de

Composition ¶

Retrieve information about current disturbances.

Composition API ¶

GET /composition/?format=json&id='S51507'&data=''&lang=en

RequestsJsonXML

Headers

Accept: application/json

Responses200

Headers

Content-Type: application/json
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

{
  "version": "1.1",
  "timestamp": "1581856899",
  "composition": {
    "segments": {
      "number": "1",
      "segment": [
        {
          "id": "0",
          "origin": {
            "locationX": "4.071825",
            "locationY": "50.891925",
            "id": "BE.NMBS.008895802",
            "name": "Denderleeuw",
            "@id": "http://irail.be/stations/NMBS/008895802",
            "standardname": "Denderleeuw"
          },
          "destination": {
            "locationX": "4.071825",
            "locationY": "50.891925",
            "id": "BE.NMBS.008895802",
            "name": "Denderleeuw",
            "@id": "http://irail.be/stations/NMBS/008895802",
            "standardname": "Denderleeuw"
          },
          "composition": {
            "source": "Itris",
            "units": {
              "number": "3",
              "unit": [
                {
                  "id": "0",
                  "materialType": {
                    "parent_type": "AM08M",
                    "sub_type": "c",
                    "orientation": "LEFT"
                  },
                  "hasToilets": "1",
                  "hasTables": "1",
                  "hasSecondClassOutlets": "1",
                  "hasFirstClassOutlets": "1",
                  "hasHeating": "1",
                  "hasAirco": "1",
                  "materialNumber": "8112",
                  "tractionType": "AM/MR",
                  "canPassToNextUnit": "0",
                  "standingPlacesSecondClass": "27",
                  "standingPlacesFirstClass": "9",
                  "seatsCoupeSecondClass": "0",
                  "seatsCoupeFirstClass": "0",
                  "seatsSecondClass": "76",
                  "seatsFirstClass": "16",
                  "lengthInMeter": "27",
                  "hasSemiAutomaticInteriorDoors": "1",
                  "hasLuggageSection": "0",
                  "materialSubTypeName": "AM08M_c",
                  "tractionPosition": "1",
                  "hasPrmSection": "1",
                  "hasPriorityPlaces": "1",
                  "hasBikeSection": "1"
                },
                {
                  "id": "1",
                  "materialType": {
                    "parent_type": "AM08M",
                    "sub_type": "b",
                    "orientation": "LEFT"
                  },
                  "hasToilets": "0",
                  "hasTables": "1",
                  "hasSecondClassOutlets": "1",
                  "hasFirstClassOutlets": "1",
                  "hasHeating": "1",
                  "hasAirco": "1",
                  "materialNumber": "8112",
                  "tractionType": "AM/MR",
                  "canPassToNextUnit": "0",
                  "standingPlacesSecondClass": "40",
                  "standingPlacesFirstClass": "0",
                  "seatsCoupeSecondClass": "0",
                  "seatsCoupeFirstClass": "0",
                  "seatsSecondClass": "104",
                  "seatsFirstClass": "0",
                  "lengthInMeter": "27",
                  "hasSemiAutomaticInteriorDoors": "1",
                  "hasLuggageSection": "0",
                  "materialSubTypeName": "AM08M_b",
                  "tractionPosition": "1",
                  "hasPrmSection": "0",
                  "hasPriorityPlaces": "1",
                  "hasBikeSection": "0"
                },
                {
                  "id": "2",
                  "materialType": {
                    "parent_type": "AM08M",
                    "sub_type": "a",
                    "orientation": "RIGHT"
                  },
                  "hasToilets": "0",
                  "hasTables": "1",
                  "hasSecondClassOutlets": "1",
                  "hasFirstClassOutlets": "1",
                  "hasHeating": "1",
                  "hasAirco": "1",
                  "materialNumber": "8112",
                  "tractionType": "AM/MR",
                  "canPassToNextUnit": "0",
                  "standingPlacesSecondClass": "37",
                  "standingPlacesFirstClass": "9",
                  "seatsCoupeSecondClass": "0",
                  "seatsCoupeFirstClass": "0",
                  "seatsSecondClass": "68",
                  "seatsFirstClass": "16",
                  "lengthInMeter": "27",
                  "hasSemiAutomaticInteriorDoors": "1",
                  "hasLuggageSection": "0",
                  "materialSubTypeName": "AM08M_a",
                  "tractionPosition": "1",
                  "hasPrmSection": "0",
                  "hasPriorityPlaces": "1",
                  "hasBikeSection": "0"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Headers

Accept: application/xml

Responses200

Headers

Content-Type: application/xml
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

<composition version="1.1" timestamp="1581856816">
    <composition>
        <segments number="1">
            <segment id="0">
                <origin locationX="4.071825" locationY="50.891925" id="BE.NMBS.008895802"
                        URI="http://irail.be/stations/NMBS/008895802" standardname="Denderleeuw">Denderleeuw
                </origin>
                <destination locationX="4.071825" locationY="50.891925" id="BE.NMBS.008895802"
                             URI="http://irail.be/stations/NMBS/008895802" standardname="Denderleeuw">Denderleeuw
                </destination>
                <composition>
                    <source>Itris</source>
                    <units number="3">
                        <unit id="0">
                            <materialType>
                                <parent_type>AM08M</parent_type>
                                <sub_type>c</sub_type>
                                <orientation>LEFT</orientation>
                            </materialType>
                            <hasToilets>1</hasToilets>
                            <hasTables>1</hasTables>
                            <hasSecondClassOutlets>1</hasSecondClassOutlets>
                            <hasFirstClassOutlets>1</hasFirstClassOutlets>
                            <hasHeating>1</hasHeating>
                            <hasAirco>1</hasAirco>
                            <materialNumber>8112</materialNumber>
                            <tractionType>AM/MR</tractionType>
                            <canPassToNextUnit>0</canPassToNextUnit>
                            <standingPlacesSecondClass>27</standingPlacesSecondClass>
                            <standingPlacesFirstClass>9</standingPlacesFirstClass>
                            <seatsCoupeSecondClass>0</seatsCoupeSecondClass>
                            <seatsCoupeFirstClass>0</seatsCoupeFirstClass>
                            <seatsSecondClass>76</seatsSecondClass>
                            <seatsFirstClass>16</seatsFirstClass>
                            <lengthInMeter>27</lengthInMeter>
                            <hasSemiAutomaticInteriorDoors>1</hasSemiAutomaticInteriorDoors>
                            <hasLuggageSection>0</hasLuggageSection>
                            <materialSubTypeName>AM08M_c</materialSubTypeName>
                            <tractionPosition>1</tractionPosition>
                            <hasPrmSection>1</hasPrmSection>
                            <hasPriorityPlaces>1</hasPriorityPlaces>
                            <hasBikeSection>1</hasBikeSection>
                        </unit>
                        <unit id="1">
                            <materialType>
                                <parent_type>AM08M</parent_type>
                                <sub_type>b</sub_type>
                                <orientation>LEFT</orientation>
                            </materialType>
                            <hasToilets>0</hasToilets>
                            <hasTables>1</hasTables>
                            <hasSecondClassOutlets>1</hasSecondClassOutlets>
                            <hasFirstClassOutlets>1</hasFirstClassOutlets>
                            <hasHeating>1</hasHeating>
                            <hasAirco>1</hasAirco>
                            <materialNumber>8112</materialNumber>
                            <tractionType>AM/MR</tractionType>
                            <canPassToNextUnit>0</canPassToNextUnit>
                            <standingPlacesSecondClass>40</standingPlacesSecondClass>
                            <standingPlacesFirstClass>0</standingPlacesFirstClass>
                            <seatsCoupeSecondClass>0</seatsCoupeSecondClass>
                            <seatsCoupeFirstClass>0</seatsCoupeFirstClass>
                            <seatsSecondClass>104</seatsSecondClass>
                            <seatsFirstClass>0</seatsFirstClass>
                            <lengthInMeter>27</lengthInMeter>
                            <hasSemiAutomaticInteriorDoors>1</hasSemiAutomaticInteriorDoors>
                            <hasLuggageSection>0</hasLuggageSection>
                            <materialSubTypeName>AM08M_b</materialSubTypeName>
                            <tractionPosition>1</tractionPosition>
                            <hasPrmSection>0</hasPrmSection>
                            <hasPriorityPlaces>1</hasPriorityPlaces>
                            <hasBikeSection>0</hasBikeSection>
                        </unit>
                        <unit id="2">
                            <materialType>
                                <parent_type>AM08M</parent_type>
                                <sub_type>a</sub_type>
                                <orientation>RIGHT</orientation>
                            </materialType>
                            <hasToilets>0</hasToilets>
                            <hasTables>1</hasTables>
                            <hasSecondClassOutlets>1</hasSecondClassOutlets>
                            <hasFirstClassOutlets>1</hasFirstClassOutlets>
                            <hasHeating>1</hasHeating>
                            <hasAirco>1</hasAirco>
                            <materialNumber>8112</materialNumber>
                            <tractionType>AM/MR</tractionType>
                            <canPassToNextUnit>0</canPassToNextUnit>
                            <standingPlacesSecondClass>37</standingPlacesSecondClass>
                            <standingPlacesFirstClass>9</standingPlacesFirstClass>
                            <seatsCoupeSecondClass>0</seatsCoupeSecondClass>
                            <seatsCoupeFirstClass>0</seatsCoupeFirstClass>
                            <seatsSecondClass>68</seatsSecondClass>
                            <seatsFirstClass>16</seatsFirstClass>
                            <lengthInMeter>27</lengthInMeter>
                            <hasSemiAutomaticInteriorDoors>1</hasSemiAutomaticInteriorDoors>
                            <hasLuggageSection>0</hasLuggageSection>
                            <materialSubTypeName>AM08M_a</materialSubTypeName>
                            <tractionPosition>1</tractionPosition>
                            <hasPrmSection>0</hasPrmSection>
                            <hasPriorityPlaces>1</hasPriorityPlaces>
                            <hasBikeSection>0</hasBikeSection>
                        </unit>
                    </units>
                </composition>
            </segment>
        </segments>
    </composition>
</composition>

Retrieve the Composition for a train
GET`/composition/{?format,id,data,lang}`

This endpoint is new and hard to test as we need to compare the data with reality. Create a bug report at our Github issue tracker if you find a bug.

We are aware of an issue with the origin and destination fields. Unfortunately this is a bug in the source data which we cannot fix at this moment.

Retrieve the composition of a train. This means a list of all carriages and locomotives with their properties.

URI Parameters

HideShow

id

string (required) Example: 'S51507'

The ID of the train for which you want to fetch the composition.

format

string (optional) Default: xml Example: json

The response format

Choices: xml json jsonp

lang

string (optional) Default: en Example: en

The language of any text or names in the response.

Choices: nl fr en de

data

string (optional) Default: '' Example: ''

By default we filter a list of fields which we guarantee to be present in every response. Set this parameter to ‘all’ in order to get all raw unfiltered data as iRail fetches it from the NMBS. These extra fields allow you to use any data instead of our “curated” list of useful fields, but come without any guarantees. Let us know if you’d like to see a raw field added to the “normal” stable output.

Choices: '' all

Disturbances ¶

Retrieve information about current disturbances.

Disturbance API ¶

GET /disturbances/?format=json&lineBreakCharacter=''&lang=en

RequestsJsonXML

Headers

Accept: application/json

Responses200

Headers

Content-Type: application/json
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

{
  "version": "1.1",
  "timestamp": "1581853952",
  "disturbance": [
    {
      "id": "0",
      "title": "Brux.-Midi/Brus.-Zuid - Amsterdam CS (NL): Incident on the Dutch rail network.",
      "description": "Between Brux.-Midi/Brus.-Zuid and Amsterdam CS (NL): Delays and cancellations are possible. Between Rotterdam CS (NL) and Amsterdam CS (NL): Disrupted train traffic. Indefinite duration of the failure. Listen to the announcements, consult the automatic departure boards or plan your trip via the SNCB app or sncb.be for more information.",
      "link": "http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&messageID=41188&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&",
      "type": "disturbance",
      "timestamp": "1581853724"
    },
    {
      "id": "1",
      "title": "Soignies / Zinnik: Failure of a level crossing.",
      "description": "Delays between 5 and 15 minutes are possible in both directions. Indefinite duration of the failure. Listen to the announcements, consult the automatic departure boards or plan your trip via the SNCB app or sncb.be for more information.",
      "link": "http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&messageID=41187&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&",
      "type": "disturbance",
      "timestamp": "1581849358"
    },
    {
      "id": "2",
      "title": "Storm warning.",
      "description": "On entire network, from saturday 15/02 evening to sunday 16/02 : Delays and cancellations are possible. Listen to the announcements, consult the automatic departure boards or plan your trip via the SNCB app or sncb.be for more information.",
      "link": "http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&messageID=41174&channelFilter=timetable,custom1,twitter,rss_line_10,livemap,custom2&",
      "type": "disturbance",
      "timestamp": "1581767543"
    },
    {
      "id": "3",
      "title": "Brux.-Nord/Brus.-Noord - Schaerbeek / Schaarbeek",
      "description": "We are conducting work for you between Brux.-Nord/Brus.-Noord and Schaerbeek / Schaarbeek. Detailed information only available in French (FR) and in Dutch (NL).",
      "link": "http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=works&messageID=41159&channelFilter=rss_line_90&",
      "type": "planned",
      "timestamp": "1581691640",
      "attachment": "http://www.belgianrail.be/jp/download/brail_him/1581691545283_NL-03003S.pdf"
    },
    {
      "id": "4",
      "title": "Ostende / Oostende - Anvers-Central / Antwerpen-Centraal",
      "description": "We are conducting work for you between Ostende / Oostende and Anvers-Central / Antwerpen-Centraal. Detailed information only available in French (FR) and in Dutch (NL).",
      "link": "http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=works&messageID=40825&channelFilter=timetable,rss_line_90,custom2&",
      "type": "planned",
      "timestamp": "1581691528",
      "attachment": "http://www.belgianrail.be/jp/download/brail_him/1580998838767_NL-02045S.pdf"
    }
  ]
}

Headers

Accept: application/xml

Responses200

Headers

Content-Type: application/xml
Access-Control-Allow-Origin: "*"
cache-control: Public
etag: "e5e7c8ae25bb71cdfce80412c2b1be54"

Body

<disturbances version="1.1" timestamp="1581854029">
    <disturbance id="0">
        <title>Soignies / Zinnik: Failure of a level crossing.</title>
        <description><![CDATA[The trains are running normally again.]]></description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&messageID=41187&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&]]></link>
        <type>disturbance</type>
        <timestamp>1581853971</timestamp>
    </disturbance>
    <disturbance id="1">
        <title>Brux.-Midi/Brus.-Zuid - Amsterdam CS (NL): Incident on the Dutch rail network.</title>
        <description>
            <![CDATA[Between Brux.-Midi/Brus.-Zuid and Amsterdam CS (NL): Delays and cancellations are possible. Between Rotterdam CS (NL) and Amsterdam CS (NL): Disrupted train traffic. Indefinite duration of the failure. Listen to the announcements, consult the automatic departure boards or plan your trip via the SNCB app or sncb.be for more information.]]></description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&messageID=41188&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&]]></link>
        <type>disturbance</type>
        <timestamp>1581853724</timestamp>
    </disturbance>
    <disturbance id="2">
        <title>Storm warning.</title>
        <description>
            <![CDATA[On entire network, from saturday 15/02 evening to sunday 16/02 : Delays and cancellations are possible. Listen to the announcements, consult the automatic departure boards or plan your trip via the SNCB app or sncb.be for more information.]]></description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&messageID=41174&channelFilter=timetable,custom1,twitter,rss_line_10,livemap,custom2&]]></link>
        <type>disturbance</type>
        <timestamp>1581767543</timestamp>
    </disturbance>
    <disturbance id="3">
        <title>Brux.-Nord/Brus.-Noord - Schaerbeek / Schaarbeek</title>
        <description>
            <![CDATA[We are conducting work for you between Brux.-Nord/Brus.-Noord and Schaerbeek / Schaarbeek. Detailed information only available in French (FR) and in Dutch (NL).]]></description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=works&messageID=41159&channelFilter=rss_line_90&]]></link>
        <type>planned</type>
        <timestamp>1581691640</timestamp>
        <attachment>http://www.belgianrail.be/jp/download/brail_him/1581691545283_NL-03003S.pdf</attachment>
    </disturbance>
    <disturbance id="4">
        <title>Ostende / Oostende - Anvers-Central / Antwerpen-Centraal</title>
        <description>
            <![CDATA[We are conducting work for you between Ostende / Oostende and Anvers-Central / Antwerpen-Centraal. Detailed information only available in French (FR) and in Dutch (NL).]]></description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/nmbs-realtime/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=works&messageID=40825&channelFilter=timetable,rss_line_90,custom2&]]></link>
        <type>planned</type>
        <timestamp>1581691528</timestamp>
        <attachment>http://www.belgianrail.be/jp/download/brail_him/1580998838767_NL-02045S.pdf</attachment>
    </disturbance>
</disturbances>

Retrieve the current disturbances
GET`/disturbances/{?format,lineBreakCharacter,lang}`

As of November 2017, additional measures have been taken to improve reliability of this endpoint, even if the original NMBS RSS feed is not available. During short RSS or NMBS website outages, this endpoint should keep providing the last known status.

Retrieve information about the current disturbances on the rail network. This data is sourced from the NMBS RSS feed, cleaned up and properly formatted. If a link (to a website) or attachment (link to a file) is detected will this be returned through the link and attachment fields. You can distinguish between scheduled changes (works) and unscheduled issues (disturbances) based on the type field.

URI Parameters

HideShow

lineBreakCharacter

string (optional) Default: '' Example: ''

The character to use for line breaks. By default these are removed to create a continuous text without special characters, but you may provide a linebreak character sequence here to get line breaks which are compatible with your client. Examples are
and \n.

format

string (optional) Default: xml Example: json

The response format

Choices: xml json jsonp

lang

string (optional) Default: en Example: en

The language of any text or names in the response.

Choices: nl fr en de

Occupancy ¶

Give feedback about occupancy on a vehicle at a certain stop

Feedback API ¶

POST /feedback/occupancy

RequestsJson

Headers

Content-Type: application/json

Body

{
  "connection": "http://irail.be/connections/8871308/20160722/IC4516",
  "from": "http://irail.be/stations/NMBS/008871308",
  "date": "20160722",
  "vehicle": "http://irail.be/vehicle/IC4516",
  "occupancy": "http://api.irail.be/terms/low"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "connection": {
      "type": "string",
      "description": "The connection id for which feedback is posted. **Never** calculate or compose this id, but copy it from an API response."
    },
    "from": {
      "type": "string",
      "description": "The station id for which station feedback is posted. **It is discouraged** to calculate or compose this id, but copy it from an API response or stations.csv instead."
    },
    "date": {
      "type": "string",
      "description": "The date for which feedback is posted in yyyymmdd format"
    },
    "vehicle": {
      "type": "string",
      "description": "The connection id for which feedback is posted. **Never** calculate or compose this id, but copy it from an API response."
    },
    "occupancy": {
      "type": "string",
      "enum": [
        "http://api.irail.be/terms/low",
        "http://api.irail.be/terms/medium",
        "http://api.irail.be/terms/high"
      ],
      "description": "The occupancy term which defines the reported occupancy in this train."
    }
  },
  "required": [
    "connection",
    "from",
    "date",
    "vehicle",
    "occupancy"
  ]
}

Responses200

Headers

Content-Type: application/json
Location: "http://irail.be/vehicle/IC4516"

Post feedback to iRail
POST`/feedback/occupancy`

When posting feedback to iRail, your feedback will be instantly processed. The occupancy on a given train will be determined by the average of all feedback which is received.

The following data should be included in the POST request:

connection: The connection id for which feedback is posted.
- from: The station id for which station feedback is posted.
- date: The date for which feedback is posted in yyyymmdd format.
- vehicle: The connection id for which feedback is posted.
- occupancy: The occupancy term which defines the reported occupancy in this train. Valid values:

At this moment, there definitely is data duplication in the post parameters. However, since the connection id can change at any moment, we cannot retrieve any information out of it - it is only used as an id. Therefore all parameters are required.

Caution

Semantic ids can change at any time without warning. You should not calculate or compose semantic ids, but rather re-use ids included in previous API answers

Log endpoint ¶

The logging endpoint gives insights about the usage of api.irail.be.

Be aware

This endpoint is only meant for applications which require realtime data, for example visualisations. If you don’t need realtime data, please use our daily data dumps for logs and feedback, documented below.

Logs API ¶

GET /logs/

RequestsJson

Headers

Accept: application/json

Responses200

Headers

Content-Type: application/json
Access-Control-Allow-Origin: "*"

Body

{
    "querytype": "liveboard",
    "querytime": "2017-09-25T13:10:19+02:00",
    "query": {
        "serialization": "xml",
        "language": "EN",
        "dateTime": "2017-09-25T13:10:00+01:00",
        "departureStop": {
            "@id": "http://irail.be/stations/NMBS/008891009",
            "longitude": "3.216726",
            "latitude": "51.197226",
            "name": "Brugge",
            "query": "BE.NMBS.008891009"
        }
    },
    "user_agent": "python-requests/2.6.0 CPython/2.7.13 Linux/4.4.0-1022-aws"
},
{
    "querytype": "vehicleinformation",
    "querytime": "2017-09-25T13:10:20+02:00",
    "query": {
        "serialization": "json",
        "language": "EN",
        "vehicle": "BE.NMBS.L2583"
    },
    "user_agent": "The DataTank 1.0"
}]

Retrieve the last logs
GET`/logs/`

Retrieve the 1000 last log entries in JSON format.

Log and Feedback data ¶

Feedback about train occupancy, as well as information on which requests were made to the iRail API, are publicly available. Every night around 3:00, this information is uploaded to the following folders:

Everyone is free to scrape these folders in order to obtain data over multiple days.

Feedback

Feedback data is formatted using JSON syntax, and is created by mongoexport. You can either directly process this data or use mongoimport to import this data into your own database.

Logs

Logs are formatted using JSON syntax. While the formatting could change without prior notice, this is extremely unlikely.

Generated by aglio on 16 Feb 2020

API Endpoint

Best practices when using the API ¶

Request limits ¶

URIs ¶

URIs in use by the iRail API ¶

Caching ¶

Supported request headers ¶

Supported response headers ¶

Bug reports ¶

Stations ¶

Stations API ¶

Headers

Headers

Body

Schema

Headers

Headers

Body

Retrieve all stationsGET/stations/{?format,lang}

Liveboard ¶

Liveboard API ¶

Be aware ¶

Headers

Headers

Body

Schema

Headers

Headers

Body

Retrieve a liveboardGET/liveboard/{?id,station,date,time,arrdep,lang,format,alerts}

Connections ¶

Connections API ¶

As of January 20, the following data has been added: ¶

Be aware ¶

Handling a walking via ¶

Headers

Headers

Body

Schema

Headers

Body

Headers

Body

Headers

Body

Headers

Headers

Body

Headers

Body

Retrieve connectionsGET/connections/{?from,to,date,time,timesel,format,lang,typeOfTransport,alerts,results}

Vehicle ¶

Vehicle API ¶

As of November 2017, the following data has been added: ¶

Be aware ¶

Headers

Headers

Body

Schema

Headers

Body

Headers

Headers

Body

Headers

Body

Retrieve a vehicleGET/vehicle/{?id,date,format,lang,alerts}

Composition ¶

Composition API ¶

Headers

Headers

Body

Headers

Headers

Body

Retrieve the Composition for a trainGET/composition/{?format,id,data,lang}

Disturbances ¶

Disturbance API ¶

Headers

Headers

Best practices when using the API

Request limits

URIs

URIs in use by the iRail API

Caching

Supported request headers

Supported response headers

Bug reports

Retrieve all stations
GET`/stations/{?format,lang}`

Be aware

Retrieve a liveboard
GET`/liveboard/{?id,station,date,time,arrdep,lang,format,alerts}`

As of January 20, the following data has been added:

Be aware

Handling a walking via

Retrieve connections
GET`/connections/{?from,to,date,time,timesel,format,lang,typeOfTransport,alerts,results}`

As of November 2017, the following data has been added:

Be aware

Retrieve a vehicle
GET`/vehicle/{?id,date,format,lang,alerts}`

Retrieve the Composition for a train
GET`/composition/{?format,id,data,lang}`

Retrieve the current disturbances
GET`/disturbances/{?format,lineBreakCharacter,lang}`

Post feedback to iRail
POST`/feedback/occupancy`

Caution

Be aware

Retrieve the last logs
GET`/logs/`

Feedback

Logs