Frequently Asked Questions

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 the departureboard.io Medium Page. We will also reach out via email for any important updates around breaking changes or API version depreciation.

Typically, when a major new version of the API is released, the previous version will stay running for 6 months (180 days) before being retired. It is recommended you keep up to date with the departureboard.io Medium Page so you are aware of such changes.

The aim is to avoid making any major changes, but occasionally (such as when National Rail make upstream API changes) they are unavoidable.

Versioning is controlled via the URI path, for example version 2.0 of the API is accessible via https://api.departureboard.io/api/v2.0/.

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. We download, and parse these documents each night at 00:30 UK time, transforming and storing them in a high-performance, redundant database backend. Consequently this information should be no more than 24 hours behind National Rail updates.

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

For a query that is not served by the Intelligent Cache: 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:

  • The departureboard.io API may be quicker than your application at crafting the SOAP XML payload, and parsing the SOAP XML response, so you may find it quicker than using the National Rail API directly.
  • The departureboard.io API is hosted in Google Cloud Platform. Google Cloud’s network is extremely high performance. Consequently, depending on the origin of the request, you may see quicker response times vs. going to the National Rail API directly due to network optimisation.

Each API request that interfaces with National Rail returns a nationalRailResponseTimeMilliseconds field, 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 queries that are served by the Intelligent Cache: You can expect responses to be up to 5x faster than going to National Rail directly.

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. Be sure to follow the full process as defined in the registration documentation to ensure your key is whitelisted with us.

Do you log or store my API Key?

No, we never log or store your API Key. Instead we compute and store a SHA512 hash of your API Key. This hash it the only thing that we ever store (in logs, and for whitelisting and rate limiting).

What can I make with this API?

The possibilities are almost endless, but some initial ideas:

  • A Live Train departure site, such as departureboard.io
  • A physical departure screen for your house to show live departures from your home station
  • An alerting application to alert you when your regular train is delayed
  • A web-based tool to look up detailed Train Station information

How much does it cost?

Nothing, the departureboard.io API is free to use for non-commercial purposes. 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.

If your response is served by the Intelligent Cache, then a request is not made to National Rail so it will not count as usage against your API Key. For example, if you make 10 million API calls to the departureboard.io API, and 5 million of those calls are returned from the Intelligent Cache. Then National Rail will only see 5 million calls against your API Key.

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

For commercial or high-volume usage see the Commercial and High Volume Usage section of the documentation.

Can I make high-volume usage of this API?

Please see the Usage Limits section of the documentation for more information.

Is Cross-Origin Resource Sharing (CORS) enabled?

Yes, the departureboard.io public endpoints return an Access-Control-Allow-Origin: * header in all 200 OK responses, including CORS preflight requests.

However, be careful about exposing your National Rail API Key if calling this API client side. For example, via AJAX or JavaScript. If you contact us with your use case we can work with you to configure a custom API endpoint that does not require your API Key to be specified as a Query Parameter, with a custom CORS configuration.

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 in a multi-regional deployment model. The backend database used to support the custom developed API Endpoints is replicated across 6 regions.

The departureboard.io API automatically scales 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.