NAV Navbar

Introduction

Welcome to the departureboard.io API. This project was inspired after successfully launching departureboard.io, a site designed to allow commuters to quickly and easily get information on their next trains. While developing departureboard.io for commuters, I quickly became frustrated with the headache caused by the SOAP based official National Rail API.

The departureboard.io API is a high performance API, written in Golang, that provides two main functions:

  1. A REST API interface to the legacy National Rail SOAP API: Gives developers the ability to pull live information on departures, arrivals, and services from National Rail, without having to use the legacy SOAP API. Free to use, and information is still pulled directly from National Rail, providing the same level of real-time data without the additional complexity of having to interact with SOAP.

  2. A REST API interface for additional National Rail information: Gives developers the ability to pull a range of information about the Rail Network, via a REST API interface. This is not an offering that National Rail currently provide, and is custom developed. Data is sourced from periodically updated XML documents, parsed, and provided for consumption via the departureboard.io API.

FAQ

This section contains some answers to frequently asked questions. Please feel free to get in touch if you have any additional queries.

Where can I keep up-to-date with departureboard.io API developments?

All news, information, and updates for the departureboard.io API will be announced via my blog.

How up to date is the information provided by this API?

The departureboard.io API is powered by the official National Rail Darwin API, providing a RESTful interface on top of the legacy SOAP API. Consequently, the information provided by the departureboard.io API is as up to date as the official National Rail feeds are. The National Rail API is used by the in-station departure boards, so typically the information provided is very accurate.

For API Endpoints that are custom developed by departureboard.io (such as getStationBasicInfo and getStationDetailsByCRS), information is still sourced via National Rail. This information is made available by National Rail in the form of lengthy XML documents containing hundreds of thousands of lines. departureboard.io downloads, and parses these documents each night at 00:30 UK time, transforming and storing them in a high-performance, redundant database backend. Consequently this information is also always up to date.

Is it slower to use this API vs. the National Rail SOAP API?

In short, often yes. But only marginally so.

The departureboard.io API is incredibly high performance, written in Golang, typically only adding a few milliseconds to a request. There are certain scenarios where you may find it quicker to consume the departureboard.io API than the National Rail API, for example:

Each API request that interfaces with National Rail returns a nationalRailResponseTimeMilliseconds property, detailing how long the request to National Rail took in milliseconds. This can be used to determine how much time the departureboard.io API added to the request. For custom developed endpoints (such as getStationBasicInfo and getStationDetailsByCRS), National Rail does not provide this information via their SOAP API.

How do I get a National Rail API Key?

It is quick and easy to get a National Rail OpenLDBWS API Key. Just visit the registration page, and sign up.

What can I make with this API?

The possibilities are almost endless, but some initial ideas:

How much does it cost?

Nothing, the departureboard.io API is free to use. You may be invoiced directly by National Rail if you exceed their free quota of 5 million API calls per 28-day railway period. See the National Rail Charging Document for more information.

Custom developed endpoints (such as getStationBasicInfo and getStationDetailsByCRS) do not require a National Rail API key and are also free of charge.

Can I make high-volume usage of this API?

Reasonably so. The aim of this API is to make it simple for developers to consume National Rail information.

In order to provide a reliable and speedy service for everyone, at a reasonable cost, the following rate limits are in place:

Type Included API Endpoints Rate Limit
National Rail Backed API Calls getDeparturesByCRS
getArrivalsByCRS
getArrivalsAndDeparturesByCRS
getServiceDetailsByID
200/req Minute
Tier 1 departureboard.io API Calls getStationBasicInfo 50,000/req Minute
Tier 2 departureboard.io API Calls getStationDetailsByCRS 50/req Minute

After exceeding these limits, you may start to see a 429 HTTP Response. For higher volume usage please get in touch to arrange a higher limit.

Is Cross-Origin Resource Sharing (CORS) enabled?

Yes, the departureboard.io allows CORS. However, be careful about exposing your National Rail API Key if calling this API client side. For example, via AJAX or JavaScript. It is possible to have a custom API FQDN configured that does not require your API Key to be specified as a Query Parameter, with a custom CORS configuration. Get in touch to discuss setting this up.

Is this a reliable service?

The departureboard.io API is provided without any official SLA.

However, the core application components run in Google Cloud Platform on Kubernetes across 3 Availability Zones in Europe-West2. The backend database used to support the custom developed API Endpoints is replicated across 6 regions.

The service will automatically scale in response to demand, and a strict route-to-live process is followed to minimise bugs in production. You can confidently make use of this service.

Departures and Arrivals

The following set of API Endpoints allow you to get departure and arrival information for train stations across the UK.

Get Departures by CRS

curl -X GET "https://api.departureboard.io/api/v1.0/getDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=1" -H "accept: */*"

The above command returns JSON structured like this:

{
  "generatedAt": "2019-06-16T15:29:08.3735002+01:00",
  "nationalRailResponseTimeMilliseconds": 168,
  "locationName": "London Kings Cross",
  "filterLocationName": null,
  "filtercrs": null,
  "filterType": null,
  "crs": "KGX",
  "nrccMessages": [
    {
      "message": "Additional trains to Great Northern destinations also operate from London St Pancras International (STP) which is a short walk from London Kings Cross."
    }
  ],
  "platformAvailable": true,
  "areServicesAvailable": null,
  "trainServices": [
    {
      "serviceID": "/AEEcjcGQWzb3dCIlOQeYQ==",
      "serviceIDUrlSafe": "_AEEcjcGQWzb3dCIlOQeYQ--",
      "serviceType": "train",
      "isCancelled": null,
      "filterLocationCancelled": null,
      "cancelReason": null,
      "delayReason": null,
      "adhocAlert": null,
      "std": "15:30",
      "etd": "On time",
      "platform": null,
      "operator": "London North Eastern Railway",
      "operatorCode": "GR",
      "isCircularRoute": null,
      "length": null,
      "detachFront": null,
      "isReverseFormation": null,
      "rsid": "GR650100",
      "origin": [
        {
          "locationName": "London Kings Cross",
          "crs": "KGX",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": null
        }
      ],
      "destination": [
        {
          "locationName": "Edinburgh",
          "crs": "EDB",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": null
        }
      ],
      "currentOrigins": null,
      "currentDestinations": null,
      "subsequentCallingPoints": [
        {
          "locationName": "Peterborough",
          "crs": "PBO",
          "st": "16:17",
          "et": "On time",
          "at": null
        },
        {
          "locationName": "Edinburgh",
          "crs": "EDB",
          "st": "20:09",
          "et": "On time",
          "at": null
        }
      ]
    }
  ],
  "busServices": null,
  "ferryServices": null
}

getDeparturesByCRS is used to get a list of services departing from a UK train station by the CRS (Computer Reservation System) code. This will typically return a list of train services, but will also return any replacement bus or ferry services that are in place.

HTTP Request

GET https://api.departureboard.io/api/v1.0/getDeparturesByCRS/{CRS}/

URL Parameters

Parameter Required Default Description
CRS true none The CRS (Computer Reservation System) for the station you wish to get departure information for, e.g. KGX for London Kings Cross.

Query Parameters

Parameter Required Default Description
apiKey true none The National Rail OpenLDBWS API Key to use for looking up service information. You must register with National Rail to obtain this key.
numServices false 10 The number of departing services to return. This is a maximum value, less may be returned if there is not a sufficient amount of services running from the selected station within the time window specified.
timeOffset false 0 The time window in minutes to offset the departure information by. For example, a value of 20 will not show services departing within the next 20 minutes.
timeWindow false 120 The time window to show services for in minutes. For example, a value of 60 will show services departing the station in the next 60 minutes.
serviceDetails false true Should the response contain information on the calling points for each service? If set to false, calling points will not be returned.
filterStation false none The CRS (Computer Reservation System) code to filter the results by. For example, performing a lookup for PAD (London Paddington) and setting filterStation to RED (Reading), will only show services departing from Paddington that stop at Reading.

Example Queries

curl -X GET "https://api.departureboard.io/api/v1.0/getDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=5" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=5&timeOffset=-20" -H "accept: */*"

Notes

When the serviceDetails query parameter is set to true for getDeparturesByCRS, only subsequent calling points will be returned. This is by design from National Rail.

To get subsequent and previous calling points in the same response, use the getArrivalsAndDeparturesByCRS or getServiceDetailsByID endpoint.

Get Arrivals by CRS

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=1" -H "accept: */*"

The above command returns JSON structured like this:

 {
  "generatedAt": "2019-06-16T15:29:36.7728705+01:00",
  "nationalRailResponseTimeMilliseconds": 176,
  "locationName": "London Kings Cross",
  "filterLocationName": null,
  "filtercrs": null,
  "filterType": null,
  "crs": "KGX",
  "nrccMessages": [
    {
      "message": "Additional trains to Great Northern destinations also operate from London St Pancras International (STP) which is a short walk from London Kings Cross."
    }
  ],
  "platformAvailable": true,
  "areServicesAvailable": null,
  "trainServices": [
    {
      "serviceID": "tFJO9xHGusvCKn5jOMKrig==",
      "serviceIDUrlSafe": "tFJO9xHGusvCKn5jOMKrig--",
      "serviceType": "train",
      "isCancelled": null,
      "filterLocationCancelled": null,
      "cancelReason": null,
      "delayReason": null,
      "adhocAlert": null,
      "sta": "15:41",
      "eta": "On time",
      "platform": null,
      "operator": "London North Eastern Railway",
      "operatorCode": "GR",
      "isCircularRoute": null,
      "length": null,
      "detachFront": null,
      "isReverseFormation": null,
      "rsid": "GR144100",
      "origin": [
        {
          "locationName": "Leeds",
          "crs": "LDS",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": null
        }
      ],
      "destination": [
        {
          "locationName": "London Kings Cross",
          "crs": "KGX",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": null
        }
      ],
      "currentOrigins": null,
      "currentDestinations": null,
      "previousCallingPoints": [
        {
          "locationName": "Leeds",
          "crs": "LDS",
          "st": "13:16",
          "et": null,
          "at": "On time"
        },
        {
          "locationName": "Stevenage",
          "crs": "SVG",
          "st": "15:19",
          "et": null,
          "at": "15:22"
        }
      ]
    }
  ],
  "busServices": null,
  "ferryServices": null
}

getArrivalsByCRS is used to get a list of services arriving to a UK train station by the CRS (Computer Reservation System) code. This will typically return a list of train services, but will also return any replacement bus or ferry services that are in place.

HTTP Request

GET https://api.departureboard.io/api/v1.0/getArrivalsByCRS/{CRS}/

URL Parameters

Parameter Required Default Description
CRS true none The CRS (Computer Reservation System) for the Station you wish to get arrival information for, e.g. KGX for London Kings Cross.

Query Parameters

Parameter Required Default Description
apiKey true none The National Rail OpenLDBWS API Key to use for looking up service information. You must register with National Rail to obtain this key.
numServices false 10 The number of arriving train services to return. This is a maximum value, less may be returned if there is not a sufficient amount of services running to this station within the time window specified.
timeOffset false 0 The time window in minutes to offset the arrival information by. For example, a value of 20 will not show services arriving within the next 20 minutes.
timeWindow false 120 The time window to show train services for in minutes. For example, a value of 60 will show services arriving to the station in the next 60 minutes.
serviceDetails false true Should the response contain information on the calling points for each service? If set to false, calling points will not be returned.
filterStation false none The CRS (Computer Reservation System) code to filter the results by. For example, performing a lookup for PAD (London Paddington) and setting filterStation to RED (Reading), will only show services arriving to Paddington that stopped at Reading.

Example Queries

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=5" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=5&timeOffset=-20" -H "accept: */*"

Notes

When the serviceDetails query parameter is set to true for getArrivalsByCRS, only previous calling points will be returned. This is by design from National Rail.

To get previous and subsequent Calling Points in the same response, use the getArrivalsAndDeparturesByCRS or getServiceDetailsByID endpoint.

Get Arrivals and Departures by CRS

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsAndDeparturesByCRS/HUN/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=1" -H "accept: */*"

The above command returns JSON structured like this:

{
  "generatedAt": "2019-06-16T15:30:52.65779+01:00",
  "nationalRailResponseTimeMilliseconds": 169,
  "locationName": "Huntingdon",
  "filterLocationName": null,
  "filtercrs": null,
  "filterType": null,
  "crs": "HUN",
  "nrccMessages": null,
  "platformAvailable": true,
  "areServicesAvailable": null,
  "trainServices": [
    {
      "serviceID": "MNWrCw3pkSSGW2auZiAMag==",
      "serviceIDUrlSafe": "MNWrCw3pkSSGW2auZiAMag--",
      "serviceType": "train",
      "isCancelled": null,
      "filterLocationCancelled": null,
      "cancelReason": null,
      "delayReason": null,
      "adhocAlert": null,
      "std": "16:01",
      "etd": "On time",
      "sta": "15:59",
      "eta": "On time",
      "platform": "2",
      "operator": "Thameslink",
      "operatorCode": "TL",
      "isCircularRoute": null,
      "length": 12,
      "detachFront": null,
      "isReverseFormation": null,
      "rsid": "TL018200",
      "origin": [
        {
          "locationName": "Peterborough",
          "crs": "PBO",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": null
        }
      ],
      "destination": [
        {
          "locationName": "London Kings Cross",
          "crs": "KGX",
          "via": null,
          "futureChangeTo": null,
          "assocIsCancelled": null
        }
      ],
      "currentOrigins": null,
      "currentDestinations": null,
      "subsequentCallingPoints": [
        {
          "locationName": "St Neots",
          "crs": "SNO",
          "st": "16:08",
          "et": "On time",
          "at": null
        },
        {
          "locationName": "London Kings Cross",
          "crs": "KGX",
          "st": "17:03",
          "et": "On time",
          "at": null
        }
      ],
      "previousCallingPoints": [
        {
          "locationName": "Peterborough",
          "crs": "PBO",
          "st": "15:45",
          "et": "On time",
          "at": null
        }
      ]
    }
  ],
  "busServices": null,
  "ferryServices": null
}

getArrivalsAndDeparturesByCRS is used to get a list of services arriving to and departing from a UK train station by the CRS (Computer Reservation System) code. This will typically return a list of train services, but will also return any replacement bus or ferry services that are in place.

HTTP Request

GET https://api.departureboard.io/api/v1.0/getArrivalsAndDeparturesByCRS/{CRS}/

URL Parameters

Parameter Required Default Description
CRS true none The CRS (Computer Reservation System) for the Station you wish to get departure and arrival information for, e.g. KGX for London Kings Cross.

Query Parameters

Parameter Required Default Description
apiKey true none The National Rail OpenLDBWS API Key to use for looking up service information. You must register with National Rail to obtain this key.
numServices false 10 The number of arriving and departing services to return. This is a maximum value, less may be returned if there is not a sufficient amount of services arriving to or departing from this station within the time window specified.
timeOffset false 0 The time window in minutes to offset the arrival and departure information by. For example, a value of 20 will not show services arriving to or departing from the station within the next 20 minutes.
timeWindow false 120 The time window in minutes to offset the arrival and departure information by. For example, a value of 20 will not show services arriving to or departing from the selected station within the next 20 minutes.
serviceDetails false true Should the response contain information on the calling points for each service? If set to false, calling points will not be returned.
filterStation false none The CRS (Computer Reservation System) code to filter the results by.

When setting this you must also set the filterType parameter.

For example, performing a lookup for PAD (London Paddington) and setting filterStation to RED (Reading) and filterType to from, will only show services arriving to London Paddington that stopped at Reading.

Setting a filter for getArrivalsAndDeparturesByCRS is similar to performing a getArrivalsByCRS or getDeparturesByCRS lookup, with the appropriate filterStation parameter. However using the getArrivalsAndDeparturesByCRS endpoint shows more details for each of the returned services.
filterType Only if filterStation is set none Determines if the filterStation parameter should be applied for services arriving to, or leaving from the selected station.

Example Queries

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsAndDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsAndDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&numServices=5" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getArrivalsAndDeparturesByCRS/RED/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&filterStation=HAY&filterType=from" -H "accept: */*"

Fastest and Next Departures

The following set of API Endpoints allow you to look up the fastest and next departures from a UK Train Station, to multiple destinations.

Get Next Departures by CRS

curl -X GET "https://api.departureboard.io/api/v1.0/getNextDeparturesByCRS/EUS/?apiKey=000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=MKC,MAN" -H "accept: */*"

The above command returns JSON structured like this:

{
  "GeneratedAt": "2019-06-16T15:32:24.6263233+01:00",
  "nationalRailResponseTimeMilliseconds": 153,
  "locationName": "London Euston",
  "crs": "EUS",
  "filterLocationName": null,
  "filtercrs": null,
  "filterType": null,
  "nrccMessages": null,
  "platformAvailable": true,
  "areServicesAvailable": null,
  "destination": [
    {
      "crs": "MKC",
      "service": {
        "serviceID": "Izj3A0zJ1O8IkEJhqgh2bQ==",
        "serviceIDUrlSafe": "Izj3A0zJ1O8IkEJhqgh2bQ--",
        "serviceType": "train",
        "isCancelled": null,
        "filterLocationCancelled": null,
        "cancelReason": "This train has been cancelled because of a shortage of train crew",
        "delayReason": null,
        "adhocAlert": null,
        "std": "15:31",
        "etd": "On time",
        "sta": null,
        "eta": null,
        "platform": null,
        "operator": "West Midlands Trains",
        "operatorCode": "LM",
        "isCircularRoute": null,
        "length": null,
        "detachFront": null,
        "isReverseFormation": null,
        "rsid": "LM206500",
        "origin": [
          {
            "locationName": "London Euston",
            "crs": "EUS",
            "via": null,
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "destination": [
          {
            "locationName": "Coventry",
            "crs": "COV",
            "via": null,
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "currentOrigins": null,
        "currentDestinations": null,
        "subsequentCallingPoints": [
          {
            "locationName": "Leighton Buzzard",
            "crs": "LBZ",
            "st": "15:58",
            "et": "On time",
            "at": null
          },
          {
            "locationName": "Birmingham New Street",
            "crs": "BHM",
            "st": "17:30",
            "et": "Cancelled",
            "at": null
          }
        ]
      }
    },
    {
      "crs": "MAN",
      "service": {
        "serviceID": "aoJ1owpBAhkQiwdbu8Q3Ag==",
        "serviceIDUrlSafe": "aoJ1owpBAhkQiwdbu8Q3Ag--",
        "serviceType": "train",
        "isCancelled": null,
        "filterLocationCancelled": null,
        "cancelReason": null,
        "delayReason": null,
        "adhocAlert": null,
        "std": "15:37",
        "etd": "On time",
        "sta": null,
        "eta": null,
        "platform": "2",
        "operator": "Virgin Trains",
        "operatorCode": "VT",
        "isCircularRoute": null,
        "length": null,
        "detachFront": null,
        "isReverseFormation": null,
        "rsid": "VT715100",
        "origin": [
          {
            "locationName": "London Euston",
            "crs": "EUS",
            "via": null,
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "destination": [
          {
            "locationName": "Manchester Piccadilly",
            "crs": "MAN",
            "via": "via Wilmslow",
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "currentOrigins": null,
        "currentDestinations": null,
        "subsequentCallingPoints": [
          {
            "locationName": "Crewe",
            "crs": "CRE",
            "st": "17:12",
            "et": "On time",
            "at": null
          },
          {
            "locationName": "Manchester Piccadilly",
            "crs": "MAN",
            "st": "17:48",
            "et": "On time",
            "at": null
          }
        ]
      }
    }
  ]
}

getNextDeparturesByCRS is used to get the next service running between two stations. Multiple destinations can be specified. This will typically return a single train service, but will also return a replacement bus or ferry service if in place.

This will return the next departures for each of the filterList stations specified. It may not return the fastest next service. To get the fastest next service use the getFastestDeparturesByCRS endpoint.

HTTP Request

GET https://api.departureboard.io/api/v1.0/getNextDeparturesByCRS/{CRS}/

URL Parameters

Parameter Required Default Description
CRS true none The CRS (Computer Reservation System) for the station you wish to get departure information for, e.g. KGX for London Kings Cross.

Query Parameters

Parameter Required Default Description
apiKey true none The National Rail OpenLDBWS API Key to use for looking up service information. You must register with National Rail to obtain this key.
filterList true none The CRS (Computer Reservation System) codes to show departing services to. Up to 20 destination stations can be specified. These should be split by a comma, for example HAY,EAL,PAD.
timeOffset false 0 The time window in minutes to offset the departure information by. For example, a value of 20 will show the next services departing after 20 minutes.
timeWindow false 120 The time window to show services for in minutes. For example, a value of 60 will show services departing the station in the next 60 minutes.
serviceDetails false true Should the response contain information on the calling points for each service? If set to false, calling points will not be returned.

Example Queries

curl -X GET "https://api.departureboard.io/api/v1.0/getNextDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=HUN,PBO,SNO" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getNextDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=HUN,PBO,SNO&timeWindow=5" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getNextDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=HUN,PBO,SNO&serviceDetails=false -H "accept: */*"

Notes

When the serviceDetails query parameter is set to true for getNextDeparturesByCRS, only subsequent calling points will be returned. This is by design from National Rail.

To get subsequent and previous Calling Points for a service, take the serviceIDUrlSafe value is provided in the response and use the getServiceDetailsByID endpoint to lookup more details.

Get Fastest Departures by CRS

curl -X GET "https://api.departureboard.io/api/v1.0/getFastestDeparturesByCRS/EUS/?apiKey=000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=MKC,MAN" -H "accept: */*"

The above command returns JSON structured like this:

{
  "GeneratedAt": "2019-06-16T15:32:24.6263233+01:00",
  "nationalRailResponseTimeMilliseconds": 153,
  "locationName": "London Euston",
  "crs": "EUS",
  "filterLocationName": null,
  "filtercrs": null,
  "filterType": null,
  "nrccMessages": null,
  "platformAvailable": true,
  "areServicesAvailable": null,
  "destination": [
    {
      "crs": "MKC",
      "service": {
        "serviceID": "Izj3A0zJ1O8IkEJhqgh2bQ==",
        "serviceIDUrlSafe": "Izj3A0zJ1O8IkEJhqgh2bQ--",
        "serviceType": "train",
        "isCancelled": null,
        "filterLocationCancelled": null,
        "cancelReason": "This train has been cancelled because of a shortage of train crew",
        "delayReason": null,
        "adhocAlert": null,
        "std": "15:31",
        "etd": "On time",
        "sta": null,
        "eta": null,
        "platform": null,
        "operator": "West Midlands Trains",
        "operatorCode": "LM",
        "isCircularRoute": null,
        "length": null,
        "detachFront": null,
        "isReverseFormation": null,
        "rsid": "LM206500",
        "origin": [
          {
            "locationName": "London Euston",
            "crs": "EUS",
            "via": null,
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "destination": [
          {
            "locationName": "Coventry",
            "crs": "COV",
            "via": null,
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "currentOrigins": null,
        "currentDestinations": null,
        "subsequentCallingPoints": [
          {
            "locationName": "Leighton Buzzard",
            "crs": "LBZ",
            "st": "15:58",
            "et": "On time",
            "at": null
          },
          {
            "locationName": "Birmingham New Street",
            "crs": "BHM",
            "st": "17:30",
            "et": "Cancelled",
            "at": null
          }
        ]
      }
    },
    {
      "crs": "MAN",
      "service": {
        "serviceID": "aoJ1owpBAhkQiwdbu8Q3Ag==",
        "serviceIDUrlSafe": "aoJ1owpBAhkQiwdbu8Q3Ag--",
        "serviceType": "train",
        "isCancelled": null,
        "filterLocationCancelled": null,
        "cancelReason": null,
        "delayReason": null,
        "adhocAlert": null,
        "std": "15:37",
        "etd": "On time",
        "sta": null,
        "eta": null,
        "platform": "2",
        "operator": "Virgin Trains",
        "operatorCode": "VT",
        "isCircularRoute": null,
        "length": null,
        "detachFront": null,
        "isReverseFormation": null,
        "rsid": "VT715100",
        "origin": [
          {
            "locationName": "London Euston",
            "crs": "EUS",
            "via": null,
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "destination": [
          {
            "locationName": "Manchester Piccadilly",
            "crs": "MAN",
            "via": "via Wilmslow",
            "futureChangeTo": null,
            "assocIsCancelled": null
          }
        ],
        "currentOrigins": null,
        "currentDestinations": null,
        "subsequentCallingPoints": [
          {
            "locationName": "Crewe",
            "crs": "CRE",
            "st": "17:12",
            "et": "On time",
            "at": null
          },
          {
            "locationName": "Manchester Piccadilly",
            "crs": "MAN",
            "st": "17:48",
            "et": "On time",
            "at": null
          }
        ]
      }
    }
  ]
}

getFastestDeparturesByCRS is used to get the fastest next service running between two stations. Multiple destinations can be specified. This will typically return a single train service, but will also return a replacement bus or ferry service if in place.

HTTP Request

GET https://api.departureboard.io/api/v1.0/getFastestDeparturesByCRS/{CRS}/

URL Parameters

Parameter Required Default Description
CRS true none The CRS (Computer Reservation System) for the station you wish to get departure information for, e.g. KGX for London Kings Cross.

Query Parameters

Parameter Required Default Description
apiKey true none The National Rail OpenLDBWS API Key to use for looking up service information. You must register with National Rail to obtain this key.
filterList true none The CRS (Computer Reservation System) codes to show the fastest departing services to. Up to 20 destination stations can be specified. These should be split by a comma, for example HAY,EAL,PAD.
timeOffset false 0 The time window in minutes to offset the departure information by. For example, a value of 20 will show the fastest services departing after 20 minutes.
timeWindow false 120 The time window to show train services for in minutes. For example, a value of 60 will show the fastest services departing the station in the next 60 minutes.
serviceDetails false true Should the response contain information on the calling points for each service? If set to false, calling points will not be returned.

Example Queries

curl -X GET "https://api.departureboard.io/api/v1.0/getFastestDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=HUN,PBO,SNO" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getFastestDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=HUN,PBO,SNO&timeWindow=5" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getFastestDeparturesByCRS/KGX/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa&filterList=HUN,PBO,SNO&serviceDetails=false -H "accept: */*"

Notes

When the serviceDetails query parameter is set to true for getFastestDeparturesByCRS, only subsequent calling points will be returned. This is by design from National Rail.

To get subsequent and previous calling points for a service, take the serviceIDUrlSafe value is provided in the response and use the getServiceDetailsByID endpoint to lookup more details.

Service Information

The following set of API Endpoints allow you to get arrival and departure information for train stations across the UK.

Get Service Details by ID

curl -X GET "https://api.departureboard.io/api/v1.0/getServiceDetailsByID/ERZbOJ8wYnOnNgNyaa1Xaw--/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa" -H "accept: */*"

The above command returns JSON structured like this:

{
  "GeneratedAt": "2019-06-16T15:34:00.2645803+01:00",
  "nationalRailResponseTimeMilliseconds": 165,
  "serviceID": "vnTso7Umpw3q+40zMcDdeQ==",
  "serviceIDUrlSafe": "vnTso7Umpw3q+40zMcDdeQ--",
  "locationName": "Huntingdon",
  "serviceType": "train",
  "isCancelled": null,
  "cancelReason": null,
  "delayReason": null,
  "overdueMessage": null,
  "adhocAlert": null,
  "sta": "16:13",
  "eta": "On time",
  "ata": null,
  "std": "16:13",
  "etd": "On time",
  "atd": null,
  "length": 12,
  "detachFront": null,
  "isReverseFormation": null,
  "platform": "3",
  "operator": "Thameslink",
  "operatorCode": "TL",
  "rsid": "TL017900",
  "subsequentCallingPoints": [
    {
      "locationName": "Peterborough",
      "crs": "PBO",
      "st": "16:29",
      "et": "On time",
      "at": null
    }
  ],
  "previousCallingPoints": [
    {
      "locationName": "London Kings Cross",
      "crs": "KGX",
      "st": "15:13",
      "et": null,
      "at": "15:15"
    },
    {
      "locationName": "St Neots",
      "crs": "SNO",
      "st": "16:06",
      "et": "On time",
      "at": null
    }
  ]
}

getServiceDetailsByID is used to get information on a service, by the Service ID. This will typically return a train service, but will also return a bus and ferry services.

The Service ID must be provided in the serviceIDUrlSafe format that is provided in the response for Arrival and Departure Boards. If required, these can be manually converted replacing:

For example, a National Rail Service ID of qsec4O8LW7k8ITcOt/ir4Q== becomes qsec4O8LW7k8ITcOt_ir4Q--. However, you should be using the value provided in the Arrival and Departure Board responses.

A service ID is specific to a station, and can only be looked up for a short time after a train/bus/ferry arrives at, or departs from a station. This is a National Rail limitation.

HTTP Request

GET https://api.departureboard.io/api/v1.0/getServiceDetailsByID/{serviceID}/

URL Parameters

Parameter Required Default Description
serviceID true none The Service ID for the Train Service you wish to look up in the URL Safe format. For example, qsec4O8LW7k8ITcOt_ir4Q--.

Query Parameters

Parameter Required Default Description
apiKey true none The National Rail OpenLDBWS API Key to use for looking up service information. You must register with National Rail to obtain this key.

Example Queries

curl -X GET "http://api.departureboard.io/api/v1.0/getServiceDetailsByID/0gN6ZPyTiOC1WfjQv7iNKQ--/?apiKey=0000a0a0-00aa-00dc-0000-0a000a00a0aa" -H "accept: */*"

Station Lookups

The following set of API endpoints can be used to get information about Train Stations across the United Kingdom.

The National Rail SOAP API does not have the capability to lookup information on Train Stations. The following endpoints are custom designed and served directly from the departureboard.io API. The data is generated from static data feeds from National Rail, which are automatically parsed and updated each night by the departureboard.io API at 00:30 United Kingdom time.

You do not need to specify your National Rail API Key to use these feeds. Responses are served directly by the departureboard.io API

Get Train Station Basic Info

curl -X GET "https://api.departureboard.io/api/v1.0/getStationBasicInfo/?station=London%20W" -H "accept: */*"

The above command returns JSON structured like this:

[
  {
    "crsCode": "WAE",
    "stationName": "London Waterloo East"
  },
  {
    "crsCode": "WAT",
    "stationName": "London Waterloo"
  }
]

getStationBasicInfo is used to look up a Train Station by CRS Code, or by name.

The most common use for this endpoint is for converting between CRS Codes and Train Station names. For example, displaying friendly names like "London Paddington" instead of "PAD" in your application. You can also use this endpoint in AJAX powered search boxes, to allow your users to search for stations by name.

getTrainStationBasicDetails returns a JSON Array of Objects, containing each stations crsCode and stationName.

The optional stationCRS parameter can also be used to lookup basic information on a specific train station by its CRS Code. This changes the response of the endpoint to a single JSON Object instead of a JSON Array. This can be used in applications to quickly convert CRS Codes to station names.

HTTP Request

GET https://api.departureboard.io/api/v1.0/getStationBasicInfo/

Query Parameters

Parameter Required Default Description
station false none The string you wish to use to search for stations. This can be a CRS Code, such as PAD, a partial train station name such as Wate or a full train station name such as London Waterloo. If this query parameter is omitted, then all train stations in the UK will be returned. This parameter cannot be used alongside stationCRS. You must use one or the other.

This query parameter must be URL encoded. For example London Paddington becomes London%20Paddington, and Hayes & Harlington becomes Hayes%20%26%20Harlington.
stationCRS false none Used to lookup a specific train station by CRS Code. This parameter should not be used for searching, it must be a valid and complete CRS code. This parameter will change the response to return a single JSON object instead of an array. This parameter cannot be used alongside station. You must use one or the other.

Example Queries

curl -X GET "https://api.departureboard.io/api/v1.0/getStationBasicInfo/?station=London" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getStationBasicInfo/" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getStationBasicInfo/station=London%20Paddington" -H "accept: */*"

curl -X GET "https://api.departureboard.io/api/v1.0/getStationBasicInfo/stationCRS=KGX" -H "accept: */*"

Get Detailed Train Station Info By CRS

curl -X GET "https://api.departureboard.io/api/v1.0/getStationDetailsByCRS/KGX/" -H "accept: */*"

The above command returns a JSON response. The response contains a lot of detail so a preview of the response is not included.

getStationDetailsByCRS is a really powerful, custom designed API Endpoint that allows the retrival of extremely detailed information about a Train Station.

It returns a wealth of information, such as:

HTTP Request

GET https://api.departureboard.io/api/v1.0/getStationDetailsByCRS/{CRS}

Query Parameters

Parameter Required Default Description
CRS true none The CRS (Computer Reservation System) for the Station you wish to get detailed Train Station information for, e.g. KGX for London Kings Cross.

Example Queries

curl -X GET "https://api.departureboard.io/api/v1.0/getStationDetailsByCRS/KGX/" -H "accept: */*"

HTTP Response Codes

The departureboard.io API uses the following error codes:

Code Meaning
200 OK -- The API request was successful, and returned a response.
400 Bad Request -- Your request is invalid. See the error message for more information.
401 Unauthorized -- Your National Rail API key is wrong.
405 Method Not Allowed -- You tried to call the API endpoint with an invalid method.
429 Too Many Requests -- You have exceeded the rate limit. Get in touch to arrange an exception, or slow down.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- Indicates an error, this can occur if there are issues with the upstream National Rail SOAP API. Check the error message for more details.