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.

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:

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

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&fast=false&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,fast,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

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

fast
boolean (optional) Default: false Example: false

(Deprecated) Whether or not you want stations in the result to be matched with an id and name according to iRail/Stations. By enabling the fast feature, there won’t be any matching between station names returned by the NMBS and our database. This results in responses which are a little bit faster. Note: due to server-side optimizations this performance difference is now insignificant. This means there might be differences between the station name in the response and any station name your software knows. Fast is disabled by default, to ensure all stations in the response are matched with an id and a consistent name.

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 November 2017, the following data has been added:

  • Alerts for each part of a connection

  • Left and Arrived attributes for resp. connection departures and arrivals

Alerts are now 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

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.

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&fast=false&typeOfTransport=trains&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"
        },
        "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"
              }
            },
            "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="1506352987">
    <connection id="0">
        <departure delay="0" canceled="0" walking="0" left="0">
            <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>
            <time formatted="2017-09-25T13:40:00">1506339600</time>
            <vehicle>BE.NMBS.IC1512</vehicle>
            <platform normal="1">11</platform>
            <direction>Genk</direction>
            <departureConnection>http://irail.be/connections/8892007/20170925/IC1512</departureConnection>
            <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
            <alerts number="1">
                <alert id="0">
                    <header>
                        <![CDATA[L 50: We are conducting work for you between Aalst and Aalst.]]>
                    </header>
                    <description>
                        <![CDATA[We are conducting work for you between Aalst and Aalst. Detailed information only available in French (FR) and             in Dutch (NL).]]>
                    </description>
                    <lead>We are conducting work for you between Aalst and Aalst.</lead>
                    <link>
                        <![CDATA[http%3A%2F%2Fwww.belgianrail.be%2Fjp%2Fdownload%2Fbrail_him%2F1509444366969_NL-11015.pdf]]>
                    </link>
                    <startTime formatted="2017-10-31T10:17:00">1509441420</startTime>
                    <endTime formatted="2017-11-12T23:59:00">1510527540</endTime>
                </alert>
            </alerts>
        </departure>
        <arrival delay="420" canceled="0" walking="0" arrived="0">
            <station id="BE.NMBS.008832375" locationX="5.350226" locationY="50.954841" URI="http://irail.be/stations/NMBS/008832375" standardname="Kiewit">Kiewit</station>
            <time formatted="2017-09-25T15:42:00">1506346920</time>
            <vehicle>BE.NMBS.IC1512</vehicle>
            <platform normal="1">2</platform>
            <direction>Genk</direction>
        </arrival>
        <alerts number="1">
                <alert id="0">
                    <header>
                        <![CDATA[L 50: We are conducting work for you between Aalst and Aalst.]]>
                    </header>
                    <description>
                        <![CDATA[We are conducting work for you between Aalst and Aalst. Detailed information only available in French (FR) and             in Dutch (NL).]]>
                    </description>
                    <lead>We are conducting work for you between Aalst and Aalst.</lead>
                    <link>
                        <![CDATA[http%3A%2F%2Fwww.belgianrail.be%2Fjp%2Fdownload%2Fbrail_him%2F1509444366969_NL-11015.pdf]]>
                    </link>
                    <startTime formatted="2017-10-31T10:17:00">1509441420</startTime>
                    <endTime formatted="2017-11-12T23:59:00">1510527540</endTime>
                </alert>
            </alerts>
        <duration>7320</duration>
        <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
    </connection>
    <connection id="1">
        <departure delay="60" canceled="0" walking="0" left="0">
            <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>
            <time formatted="2017-09-25T13:40:00">1506339600</time>
            <vehicle>BE.NMBS.IC2213</vehicle>
            <platform normal="1">6</platform>
            <direction>Tongeren</direction>
            <departureConnection>http://irail.be/connections/8892007/20170925/IC2213</departureConnection>
            <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
        </departure>
        <arrival delay="0" canceled="0" walking="0" arrived="0">
            <station id="BE.NMBS.008832375" locationX="5.350226" locationY="50.954841" URI="http://irail.be/stations/NMBS/008832375" standardname="Kiewit">Kiewit</station>
            <time formatted="2017-09-25T16:24:00">1506349440</time>
            <vehicle>BE.NMBS.P2366</vehicle>
            <platform normal="1">2</platform>
            <direction>Genk</direction>
        </arrival>
        <duration>9840</duration>
        <vias number="1">
            <via id="0">
                <arrival delay="120" canceled="0" walking="0" arrived="0">
                    <time formatted="2017-09-25T15:49:00">1506347340</time>
                    <platform normal="1">2</platform>
                    <direction>Tongeren</direction>
                    <vehicle>BE.NMBS.IC2213</vehicle>
                    <departureConnection>http://irail.be/connections/8831005/20170925/IC2213</departureConnection>
                </arrival>
                <departure delay="60" canceled="0" walking="0" left="0">
                    <time formatted="2017-09-25T16:16:00">1506348960</time>
                    <platform normal="1">8</platform>
                    <direction>Genk</direction>
                    <vehicle>BE.NMBS.P2366</vehicle>
                    <departureConnection>http://irail.be/connections/8831005/20170925/P2366</departureConnection>
                    <occupancy URI="http://api.irail.be/terms/unknown">unknown</occupancy>
                </departure>
                <timeBetween>1620</timeBetween>
                <station id="BE.NMBS.008831005" locationX="5.327627" locationY="50.930822" URI="http://irail.be/stations/NMBS/008831005"             standardname="Hasselt">Hasselt</station>
                <vehicle>BE.NMBS.IC2213</vehicle>
                <direction>Tongeren</direction>
            </via>
        </vias>
        <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,fast,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: trains Example: trains

The types of transport to include in the search

Choices: trains nointernationaltrains all

alerts
boolean (optional) Example: false

(Deprecated) Wether 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.

fast
boolean (optional) Default: false Example: false

(Deprecated) Whether or not you want stations in the result to be matched with an id and name according to iRail/Stations. By enabling the fast feature, there won’t be any matching between station names returned by the NMBS and our database. This results in responses which are a little bit faster. Note: due to server-side optimizations this performance difference is now insignificant. This means there might be differences between the station name in the response and any station name your software knows. Fast is disabled by default, to ensure all stations in the response are matched with an id and a consistent name.

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

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 /vehicle/?id=BE.NMBS.IC1832&date=300917&fast=false&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,fast,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

Wether 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

fast
boolean (optional) Default: false Example: false

(Deprecated) Whether or not you want stations in the result to be matched with an id and name according to iRail/Stations. By enabling the fast feature, there won’t be any matching between station names returned by the NMBS and our database. This results in responses which are a little bit faster. Note: due to server-side optimizations this performance difference is now insignificant. This means there might be differences between the station name in the response and any station name your software knows. Fast is disabled by default, to ensure all stations in the response are matched with an id and a consistent name.


Disturbances

Retrieve information about current disturbances.

Disturbance API

GET /disturbances/?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": "1509444463",
  "disturbance": [
    {
      "id": "0",
      "title": "Kalmthout: Freight train broken down.",
      "description": "Situation back to normal.",
      "link": "http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23851&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&",
      "timestamp": "1509443931"
    },
    {
      "id": "1",
      "title": "Balegem-Dorp: Intervention emergency services (112).",
      "description": "Situation back to normal.",
      "link": "http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23854&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&",
      "timestamp": "1509443873"
    },
    {
      "id": "2",
      "title": "Landen - Waremme: Signal failure.",
      "description": "Delayed train traffic. Disruption for an undetermined amount of time. Listen to the announcements in the train station.",
      "link": "http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23853&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&",
      "timestamp": "1509442854"
    },
    {
      "id": "3",
      "title": "Arlon - Luxembourg (l): Signal failure.",
      "description": "Delayed train traffic. Disruption for an undetermined amount of time. Listen to the announcements in the train station.",
      "link": "http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23852&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&",
      "timestamp": "1509442716"
    },
    {
      "id": "4",
      "title": "Louvain - Liege-Guillemins: IT problem",
      "description": "Due to an IT problem it isn't possible to get real time train information via the real time information search             engine.Please listen to the announcements made in the train or in the train station.",
      "link": "http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23798&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&",
      "timestamp": "1509439215"
    }
  ]
}
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="1509444584">
    <disturbance id="0">
        <title>Kalmthout: Freight train broken down.</title>
        <description>
            <![CDATA[Situation back to normal.]]>
        </description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23851&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&]]>
        </link>
        <timestamp>1509443931</timestamp>
    </disturbance>
    <disturbance id="1">
        <title>Balegem-Dorp: Intervention emergency services (112).</title>
        <description>
            <![CDATA[Situation back to normal.]]>
        </description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23854&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&]]>
        </link>
        <timestamp>1509443873</timestamp>
    </disturbance>
    <disturbance id="2">
        <title>Landen - Waremme: Signal failure.</title>
        <description>
            <![CDATA[Delayed train traffic. Disruption for an undetermined amount of time. Listen to the announcements in the train station.]]>
        </description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23853&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&]]>
        </link>
        <timestamp>1509442854</timestamp>
    </disturbance>
    <disturbance id="3">
        <title>Arlon - Luxembourg (l): Signal failure.</title>
        <description>
            <![CDATA[Delayed train traffic. Disruption for an undetermined amount of time. Listen to the announcements in the train station.]]>
        </description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23852&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&]]>
        </link>
        <timestamp>1509442716</timestamp>
    </disturbance>
    <disturbance id="4">
        <title>Louvain - Liege-Guillemins: IT problem</title>
        <description>
            <![CDATA[Due to an IT problem it isn't possible to get real time train information via the real time information search             engine.Please listen to the announcements made in the train or in the train station.]]>
        </description>
        <link>
            <![CDATA[http://www.belgianrail.be/jp/sncb-nmbs-routeplanner/help.exe/en?tpl=showmap_external&tplParamHimMsgInfoGroup=trouble&message            ID=23798&channelFilter=custom2,livemap,rss_line_10,twitter,custom1,timetable&]]>
        </link>
        <timestamp>1509439215</timestamp>
    </disturbance>
</disturbances>

Retrieve the current disturbances
GET/disturbances/{?format,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.

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


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:

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 10 Nov 2017