Nederlandse Spoorwegen smart home integration, free and open source
Dutch trains (NS): real-time departures, delays, platforms and disruptions.
Published by William-De71
- Devices
- Version 0.1.0
- Requires Gladys >=5.3.0
- ★ 0
Overview
This integration brings NS, the Dutch railways, into Gladys. It gives the next trains in real time, with their delay and their platform, at the stations you choose (three in the form, up to 10 more with a button), filtered by train type and direction. It also follows the disruptions about each station: incidents (signal failure, broken-down train), engineering works and calamities (storm, strike). Each station becomes a device to show on a dashboard and to use in scenes.
The data come from the official API of NS (gateway.apiportal.ns.nl), with your own free key. Each followed station is read with one request, every minute by default (every 10 minutes while no station announces a train in the next half hour, at night). The disruptions are read every 5 minutes. The list of the stations of NS is kept by the integration and read again once a week. NS allows 300 requests per 5 minutes per key: the integration always stays below.
NS gives the expected time of each train: the delay is the gap with the planned time. Platform changes and cancelled trains are shown. Station names, messages and disruptions stay in English, as NS writes them.
This is a cloud integration: it contacts gateway.apiportal.ns.nl with your key. Nothing else leaves your network.
Requirements
- Gladys Assistant 5.3.0 or later.
- A free key of the NS API: create an account on apiportal.ns.nl, open Products, subscribe to Ns-App (free), then copy the primary key shown in your profile.
Configuration
| Field | What to type |
|---|---|
| API key | The primary key of your "Ns-App" subscription (32 characters). |
| Station 1, 2, 3 | The code of the station ("UT", "ASD", the codes of the NS boards) or its name ("Utrecht Centraal"). |
| Train types | Only these trains: "IC", "SPR", "IC | ICE". Empty: every train. |
| Direction | Only the trains going to, or calling at, these stations: "Amersfoort | Zwolle". Empty: every direction. |
| Reading of the stations | Every 30 seconds, minute, 2 minutes or 5 minutes. |
| Language of the texts | Names of the devices, summaries and outputs of the scenes. NS texts stay in English. |
The Find a station button gives the stations holding a few words, with their code ("Den Haag Centraal [GVC]"). A name works too ("Utrecht", "Den Bosch"); when two stations share it, type the full name or the code. Test the connection checks the key and reads each station right away.
The direction looks at the destination and at the stations the train calls at next: "Amersfoort" keeps the Intercity to Zwolle that stops at Amersfoort.
More stations than the three of the form (home, work, school…): Add a station takes the same three fields — station, train types, direction — and follows up to 10 more stations. List the stations shows every followed station, numbered; Remove a station takes that number (or the name). The added stations are kept in the configuration of Gladys, so they follow its backups.
Usage
Devices
In the Discover tab, create the devices you want, NS <station>:
- the next train as text ("IC 3529 → Venlo · 11 min (+8 min late) · platform 15 (changed)");
- the wait of the next train and of the one after (minutes), and the delay of the next one (minutes);
- the traffic as text ("Disrupted: Utrecht - Amersfoort: fewer trains") and the number of disruptions under way.
At night, without any train, the waits keep their last value.
Disruptions
NS publishes three kinds: disruptions (incidents), engineering works (planned) and calamities (national messages). The state of a station is the most serious one under way: normal service, engineering works, disrupted or major disruption. Works starting in the next three days are shown as coming.
Dashboard widgets
- NS departures: the departure board of a station: one row per train, with its planned time, its type, its destination, its delay ("+8") and its platform. The row turns orange when the train is 5 minutes late or more or changes platform, red when it is cancelled. The Trains shown setting sets the number of rows. Choose a followed station, or type any station (and train types) in the widget settings. With Several stations, one widget shows several station devices.
- NS disruptions: the state of your stations, then the disruptions and works under way and coming, with their period. Tap a card for the full text. With Whole network, the disruptions of the whole Dutch network.
Scenes
Triggers, once per change (the first reading is only a baseline):
- NS: train leaving soon: a train of a followed station leaves in 2, 5, 10, 15, 20 or 30 minutes, counted on its expected time.
- NS: train cancelled: a train of the next two hours at a followed station is cancelled.
- NS: train delayed: the delay of a train of the next two hours reaches 5, 10, 15 or 30 minutes (the highest mark reached). Tick 5, 10, 15 and 30 for any delay of 5 minutes or more.
- NS: platform changed: a train of the next two hours leaves from another platform.
- NS: disruption at a station: a disruption, works or a calamity about a followed station begins.
- NS: disruption over: it is over.
Each gives a ready-made sentence, {{triggerEvent.data.summary}}, and its values (train, destination, time, platform, delay, title, cause…). The actions NS: next trains and NS: disruptions of a station return the same kind of values, to put in a message or to test in a condition.
Examples:
- When the Intercity to Amersfoort leaves Utrecht Centraal in 10 minutes → turn the hall lamp green.
- When your train is cancelled, 15 minutes late or moved to another platform → send the summary to your phone.
- Every weekday at 7:30 → read the next trains of your station and have the kitchen speaker announce them.
Transport
Cloud only: the data come from the internet. Only the stations you follow are asked to the API of NS, one by one.
Troubleshooting
- "NS refuses the API key": check that you copied the primary key of the Ns-App product, and that the subscription is active on apiportal.ns.nl.
- "Unknown or ambiguous": use Find a station, then copy the exact name or the code.
- "Too many requests to NS": the key is shared with another application, or too many stations are read every 30 seconds; choose a longer reading interval.
- No train: at night the network sleeps; the station is read every 10 minutes.
- "NS cannot be reached": the integration tries again at each reading; the last trains stay on the widgets.
- To report a problem: press Diagnostic, then copy the lines starting with "NS diagnostic" from the Logs tab into a GitHub issue or a reply on the forum, with the versions of Gladys and of the integration. The key is never written there.
Configuration settings
These are the settings Nederlandse Spoorwegen asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| NS API key | section | No | The departures and the disruptions come from the official API of NS, the Dutch railways. It asks for a free personal key: create an account on the NS API portal, subscribe to the "Ns-App" product (free), then copy its primary key below. Fill in your stations, save, then press "Test the connection". |
| API key | secret | Yes | The primary key of your "Ns-App" subscription (32 characters). |
| Station 1 | section | No | A station where you take the train: its next departures are read in real time, with delay and platform. Type its code ("UT", "ASD", the codes of the NS boards) or its name ("Utrecht Centraal"): the "Find a station" button gives them. The train types keep only these trains ("IC", "SPR", "IC | ICE"). The direction keeps only the trains going to, or calling at, these stations ("Amersfoort | Zwolle"). |
| Station | string | No | |
| Train types | string | No | Empty for every train. |
| Direction | string | No | Stations the train goes to or calls at. Empty for every direction. |
| Station 2 | section | No | |
| Station | string | No | |
| Train types | string | No | Empty for every train. |
| Direction | string | No | Stations the train goes to or calls at. Empty for every direction. |
| Station 3 | section | No | |
| Station | string | No | |
| Train types | string | No | Empty for every train. |
| Direction | string | No | Stations the train goes to or calls at. Empty for every direction. |
| Options | section | No | |
| Reading of the stations | select | No | How often the departures are read: one request per followed station (NS allows 300 per 5 minutes). While no station announces a train in the next half hour (at night), every 10 minutes. The disruptions are read every 5 minutes. |
| Language of the texts | select | No | Names of the devices, summaries and outputs of the scenes. Automatic: the language of your dashboard, as soon as an NS widget has been shown. Station names, messages and disruptions stay in English, as NS writes them. |
How to install Nederlandse Spoorwegen in Gladys
- In Gladys, open Integrations: Nederlandse Spoorwegen appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/william-de71/gladys-nederlandse-spoorwegen:0.1.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/William-De71/gladys-nederlandse-spoorwegen.
Nederlandse Spoorwegen requires Gladys >=5.3.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Nederlandse Spoorwegen is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by William-De71, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation