api.irail.be

Note: As of October 2017, we update our documentation. Please see https://docs.irail.be for the new API documentation. Please see https://status.irail.be for the current service status. For more information, read this.

Welcome to the iRail API! Before you start implementing this API, a lot of code has been written already! Feel free to look around on our Github page for more information on wrappers for your programming language of choice.

1. Query for station / download all stations

Request

https://irail.be/stations/NMBS?q={query}

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.

Another alternative is the deprecated https://api.irail.be/stations/ resource which takes no arguments at all.

Arguments

optional (leave empty for all stations):

?q=Brussel

Response

E.g., for Brussels: curl https://irail.be/stations/NMBS?q=Brussels
{
  "@graph": [
    {
      "@id": "http://irail.be/stations/NMBS/008811304",
      "alternative": [
        {
          "@language": "en",
          "@value": "Brussels-Luxemburg/Brussels-Luxembourg"
        },
        {
          "@language": "fr",
          "@value": "Bruxelles-Luxembourg"
        },
        {
          "@language": "nl",
          "@value": "Brussel-Luxemburg"
        }
      ],
      "name": "Brussel-Luxemburg/Bruxelles-Luxembourg",
      "latitude": "50.838943",
      "longitude": "4.373674"
    },
    ...
  ]
}

2. Querying for a route from one station to another

Request

https://api.irail.be/connections/?to={station1}&from={station2} (OPTIONAL:) &date={dmy}&time=2359&timeSel=arrive or depart

date

dmy (day of month with leading 0, number of the month with leading 0, 10 or 11 (for 2010 or 2011)) e.g., 010115 is the first of January 2015

time

Hours in 24 hour format concatenated with minutes with leading 0!

timeSel

Whether the date & time are for arrival or depart. Should be “arrive” or “depart”

Response

(with random data)

<connections>
  <connection id="0">
    <departure delay="xx"> <!--xx in seconds-->
      <station locationX="4.038586" locationY="50.943053">AALST</station>
      <time formatted="Y-m-d\TH:i:s\Z"> <!-- time in iso 8601 -->
        U <!--(= unixtime)-->
      </time>
      <vehicle>BE.NMBS.P2000</vehicle>
      <platform normal="yes">3</platform>
    </departure>
    <vias number="1">
      <via id="0">
        <arrival>
          <time formatted="Y-m-d\TH:i:s\Z">
            U<!--(= unixtime)-->
          </time>
          <platform>5</platform>
        </arrival>
        <depart>
          <time formatted="iso8601">
            U <!--(= unixtime)-->
          </time>
          <platform>6</platform>
        </depart>
        <timeBetween>xx</timeBetween>
        <station locationX="..." locationY="..." URI="...">Gent Sint Pieters</station>
        <vehicle>BE.NMBS.P2000</vehicle>
      </via>
    </vias>
    <arrival delay="xx"> <!--delay on arrival in seconds -->
      <station location="... ..." URI="...">
        Harelbeke
      </station>
      <time formatted="Y-m-d\TH:i\Z">
        U <!--(= unixtime)-->
      </time>
      <vehicle>BE.NMBS.P2000</vehicle>
      <platform normal="true">1</platform>
    </arrival>
    <duration delay="yes">seconds</duration>
  </connection>
  ...
</connections>

3. Departures and Arrivals in a certain station

Request

https://api.irail.be/liveboard/?station=STATIONNAME&fast=true
or
https://api.irail.be/liveboard/?id=BE.NMBS.008892007

fast

The direction of a train in the liveboard overview is not a station, but a general direction. The flag fast=true will omit trying to link a direction to a station. We recommend for the liveboard overview to always put fast=true.

station

Name of the station

id

id returned by a previous request

date

date of depart/arrival – dmy

time

time of depart/arrival –

arrdep

DEP or ARR for arrival or departure

Response

<liveboard version="1.0" timestamp="123456789">
 <station locationX="4.21485" locationY="...">Ghent Sint Pieters</station>
 <departures number="2">
  <departure delay="xx" id="0">
   <station locationX="..." locationY="...">STATIONNAME</station>
   <vehicle>Be.NMBS.P2000</vehicle>
   <time formatted="iso8601">U</time>
   <platform>X</platform>
  </departure>
  <departure delay="xx" id="1">
   <station locationX="..." locationY="...">STATIONNAME</station>
   <vehicle>BE.NMBS.P2001</vehicle>
   <time formatted="iso8601">U</time>
   <platform>X</platform>
  </departure>
 </departures>
</liveboard>

4. Vehicle

Request

https://api.irail.be/vehicle/?id=BE.NMBS.P1234

id

specify the vehicle id. This should be according the iRail specification

Response

 
<vehicleinformation version="1.1" timestamp="1469090808">
  <vehicle locationX="6.03711" locationY="50.635157">BE.NMBS.IC545</vehicle>
  <stops>
    <stop>
      <station id="BE.NMBS.008844628" locationX="6.03711" locationY="50.635157" 
          URI="http://irail.be/stations/NMBS/008844628" standardname="Eupen">Eupen</station>
      <platform normal="1">2</platform>
      <departureDelay>0</departureDelay>
      <departureCanceled>0</departureCanceled>
      <scheduledDepartureTime formatted="2016-07-21T22:22:00">1469132520</scheduledDepartureTime>
      <scheduledArrivalTime formatted="2016-07-21T22:22:00">1469132520</scheduledArrivalTime>
      <arrivalDelay>0</arrivalDelay>
      <arrivalCanceled>0</arrivalCanceled>
    </stop>
  ...
  </stops>
</vehicleinformation>

Error Response

When incorrect requests has been made or when an error occurs, we will provide an error message like this:

 <error version="1.0" timestamp="1289951590" code="1">
   You should ...
 </error>

at this moment code = 1 is a user error. code = 2 is a server error.

Arguments on all functions

lang

if you add &lang= NL, EN, DE or FR to a function, the given station will be interpreted in that language, and the stationnames will be outputted in that language.

format

Currently we support 2 formats: xml and json

• &format=xml will output the above examples
• &format=json will output the xml-converted json
• &format=jsonp&callback=foo will package the json string into a callback function.

Alerts

setting alerts=true will enable alert messages in the response