Contact Suggest changes

Introduction

Welcome to the NS M-lab API! This documentation serves as an introduction to all the available APIs that you can use. These APIs are also used by the NS journey planner apps and will provide you with the same information.

This documentation will guide you through the authentication part first, which is required for all APIs. Then some general train knowledge is explained. Some of the APIs are described using Swagger.

If you have any questions, please contact us.

Almost all APIs use a REST interface (some a websocket) with a JSON response. If you are unsure what this means, it’s good familiarize yourself first with this explanation or Wikipedia

All information in this documentation can be changed at any time without notice. No rights can be derived. Although we do our best to provide the correct information, there is no guarantee the information is correct.

A great (free!) tool for trying out API requests is Postman. Of course, you can also use the more complex cURL, jQuery for websites or any other tool.

Authentication

The API key needs to be included in all API requests to the server in the header, or a 403 response will be given.

To authorize, add an header to the request: x-api-key: abcdefg123 Make sure to replace abcdefg123 with your API key. All API calls require an x-api-key token to access the API.

Your API keys grants you access to a limit numer of requests, because this is a free service. The limit is now set to 10 requests/second and 8,000 requests per day. Please use your own caching if you need more requests.

General train knowledge

Train numbers

Most information is based on a so called ritnummer, or train number in English. All train rides have a unique number for that day, similar to flight numbers. A list of all train routes with corresponding numbers can be found on Wikipedia.

Station codes

Most APIs have station codes. The codes (abbreviations) can be found on Wikipedia.