Basic use of the nsapi package
Roel M. Hogervorst
2018-08-04
Source:vignettes/basic_use_nsapi_package.Rmd
basic_use_nsapi_package.RmdThis is a description and use of all the functions in the package.
The API returns everything in Dutch and therefore I have kept the responses in Dutch as well. The NS website does have a English translation which I will link to here: https://www.ns.nl/en/travel-information/ns-api.
First a description of how to set up your username and password and than a breakdown of all the functions.
Authentication
Before you can use any of the functions you need a username and password To get that go to: https://www.ns.nl/ews-aanvraagformulier/
You will receive a confirmation email, and finally a username and password (that can’t be changed for some reason).
You need to add the username and password to your rsession for the nsapi package to work. Why? Good question! It is not smart to type your passwords in a R session, they will end up in your history file and will be available for everyone who searches your computer. You might think that this password and account is not that important and you might be right, but let’s do the right thing anyway.
Temporary adding acountname and password to your session
A temporary way is to add them to your session with :
Sys.setenv(NSAPIACCOUNT = "probablyyouremail@email.com")
Sys.setenv(NSAPIPW = "yourpasswordgiveninplaintextoveremailwhydopeopledothisohgod")At the end of your session (if you go to a new project, if you restart R or if you crash) the keys are removed from memory. Keep in mind that this DOES put your password in the history file and is therefore NOT recommended.
Permanently adding username and password to your r session
Go to your global .Renviron file (or make one) and add the keys
The file will open and you can add two entries:
NSAPIPW = yourpasswordgiveninplaintextoveremailwhydopeopledothisohgod
NSAPIACCOUNT = probablyyouremail@email.comHow do you know if you succeeded?
Getting travel advise
If you’d like to know when your train from Amsterdam to Groningen goes, use the travel_advise function with departure and arrival station.
library(nsapi)
ams_to_groningen <- get_travel_advise(
fromStation = "Amsterdam Centraal",
toStation = "Groningen",
#dateTime = , # I don't use it because I want to leave now!
departure = TRUE # I want to depart now
)
ams_to_groningen[,1:5]
#> Melding AantalOverstappen GeplandeReisTijd ActueleReisTijd
#> 1 NA 2 2:06 2:06
#> 2 NA 1 2:06 2:06
#> 3 NA 2 2:06 2:06
#> 4 NA 1 2:06 2:06
#> 5 NA 2 2:20 2:20
#> 6 NA 2 2:06 2:06
#> 7 NA 1 2:06 2:06
#> 8 NA 2 2:20 2:20
#> VertrekVertraging
#> 1 <NA>
#> 2 <NA>
#> 3 <NA>
#> 4 <NA>
#> 5 <NA>
#> 6 <NA>
#> 7 <NA>
#> 8 <NA>The function returns a data.frame with 4 advises before and 4 after the time you selected.
ams_to_groningen[,6:8]
#> AankomstVertraging Optimaal GeplandeVertrekTijd
#> 1 <NA> FALSE 2018-08-04 08:37:00
#> 2 <NA> FALSE 2018-08-04 09:07:00
#> 3 <NA> FALSE 2018-08-04 09:37:00
#> 4 <NA> TRUE 2018-08-04 10:07:00
#> 5 <NA> FALSE 2018-08-04 10:23:00
#> 6 <NA> FALSE 2018-08-04 10:37:00
#> 7 <NA> FALSE 2018-08-04 11:07:00
#> 8 <NA> FALSE 2018-08-04 11:23:00More details about the returned dataframe.
The column Reisdeel is a nested data frame with a nested data frame called stops within.
str(ams_to_groningen[1,13])
#> List of 1
#> $ :'data.frame': 3 obs. of 5 variables:
#> ..$ Vervoerder : chr [1:3] "NS" "NS" "NS"
#> ..$ VervoerType: chr [1:3] "Intercity" "Intercity" "Intercity"
#> ..$ RitNummer : chr [1:3] "2627" "1827" "527"
#> ..$ Status : chr [1:3] "VOLGENS-PLAN" "VOLGENS-PLAN" "VOLGENS-PLAN"
#> ..$ Stops :List of 3
#> .. ..$ :'data.frame': 2 obs. of 4 variables:
#> .. .. ..$ Naam : chr [1:2] "Amsterdam Centraal" "Almere Centrum"
#> .. .. ..$ Tijd : POSIXct[1:2], format: "2018-08-04 08:37:00" ...
#> .. .. ..$ Spoor : chr [1:2] "13b" "3"
#> .. .. ..$ SpoorWijziging: chr [1:2] NA NA
#> .. ..$ :'data.frame': 3 obs. of 4 variables:
#> .. .. ..$ Naam : chr [1:3] "Almere Centrum" "Lelystad Centrum" "Zwolle"
#> .. .. ..$ Tijd : POSIXct[1:3], format: "2018-08-04 09:03:00" ...
#> .. .. ..$ Spoor : chr [1:3] "4" NA "7"
#> .. .. ..$ SpoorWijziging: chr [1:3] NA NA NA
#> .. ..$ :'data.frame': 3 obs. of 4 variables:
#> .. .. ..$ Naam : chr [1:3] "Zwolle" "Assen" "Groningen"
#> .. .. ..$ Tijd : POSIXct[1:3], format: "2018-08-04 09:45:00" ...
#> .. .. ..$ Spoor : chr [1:3] "6" NA "4b"
#> .. .. ..$ SpoorWijziging: chr [1:3] NA NA NA
#> - attr(*, "class")= chr "AsIs"The API returns a lot of nested information, and as a consequence the data.frame is nested too.
Every row is thus an advise with arrival and departure times and travelparts, if you have to switch trains there will be more than 1 row in the ReisDeel column. For instance in the first row:
ams_to_groningen$ReisDeel[[1]]
#> Vervoerder VervoerType RitNummer Status
#> 1 NS Intercity 2627 VOLGENS-PLAN
#> 2 NS Intercity 1827 VOLGENS-PLAN
#> 3 NS Intercity 527 VOLGENS-PLAN
#> Stops
#> 1 Amsterdam Centraal, Almere Centrum, 1533364620, 1533365880, 13b, 3, NA, NA
#> 2 Almere Centrum, Lelystad Centrum, Zwolle, 1533366180, 1533367020, 1533368580, 4, NA, 7, NA, NA, NA
#> 3 Zwolle, Assen, Groningen, 1533368700, 1533371160, 1533372180, 6, NA, 4b, NA, NA, NAAnd every part of the trip has stops where the train stops:
Stationlist
Another endpoint of the API is a list of stations.
stations <- get_stationlist()
head(stations)
#> Code Type Namen Land UICCode Lat
#> 1 HT knooppuntIntercitystation list("De.... NL 8400319 51.69048
#> 2 HTO stoptreinstation list("Dn.... NL 8400320 51.70055
#> 3 HDE stoptreinstation list("'t.... NL 8400388 52.40917
#> 4 AHBF knooppuntIntercitystation list("Aa.... D 8015345 50.76780
#> 5 ATN stoptreinstation list("Aa.... NL 8400045 51.92133
#> 6 AC stoptreinstation list("Ab.... NL 8400047 52.27850
#> Lon Synoniemen
#> 1 5.293620 list("He....
#> 2 5.318333 list("He....
#> 3 5.893611 list("Ha....
#> 4 6.091499 NA
#> 5 6.578627 NA
#> 6 4.977000 NA
names(stations)
#> [1] "Code" "Type" "Namen" "Land" "UICCode"
#> [6] "Lat" "Lon" "Synoniemen"This will return a data frame with all the stations in the NS API. There are not only Dutch stations, but also multiple Belgian, German, English, Austrian, French,Polish and other country stations. Every station has an international code, name, synonyms, geolocation (Lat, Lon), and type of station.
# code is not executed, I don't want to add these dependencies to the package
library(tidyverse)
library(ggrepel)
stations <-
get_stations() %>%
mutate(Naam = map_chr(Namen, ~.[["Kort"]][[1]]),
Label = ifelse(Type == "knooppuntIntercitystation", Naam,NA) ) %>%
as.tibble()
stations %>%
filter(Land == "NL") %>%
ggplot(aes(Lon, Lat, label = Label))+
geom_point(alpha = 1/3)+
geom_text_repel()+
coord_map()+
labs(
title = "Only Dutch Stations",
subtitle = "Major stations named",
caption = "Data: NS 2018 (Dutch National Railways)"
)
Plot of Dutch stations’ locations
Departures
You can see the departure times of any station at this time by calling the departures() function.
leiden_trains <- get_departures(station = "Leiden Lammenschans")
head(leiden_trains)
#> RitNummer VertrekTijd EindBestemming TreinSoort
#> 1 2018-08-04 09:57:00 Utrecht Centraal Intercity
#> 2 2018-08-04 10:02:00 Leiden Centraal Intercity
#> 3 2018-08-04 10:27:00 Utrecht Centraal Intercity
#> 4 2018-08-04 10:32:00 Leiden Centraal Intercity
#> 5 2018-08-04 10:57:00 Utrecht Centraal Intercity
#> 6 2018-08-04 11:02:00 Leiden Centraal Intercity
#> RouteTekst Vervoerder VertrekSpoor Spoorwijziging
#> 1 Alphen a/d Rijn 1
#> 2 <NA> 1
#> 3 Alphen a/d Rijn 1
#> 4 <NA> 1
#> 5 Alphen a/d Rijn 1
#> 6 <NA> 1Disruptions and maintenance
These 3 functions call out to find out about disruptions and engineering on the tracks for the current time, for the next 2 weeks or a specific station. Every call returns a dataframe with “id”, “Traject”, “Periode”, “Reden”, “Bericht”, “Advies”, and “Datum”.
Bericht is often a complete message with html markup:
<p>\n<b>Wanneer: vanaf zaterdag 26 mei </b><br/>\n<b>Oorzaak: aangepaste dienstregeling</b><br/>\n<b>Advies: U kunt gebruikmaken van de gewijzigde dienstregeling</b>\n<br/>Stoptreinen tussen Roosendaal en Antwerpen Centraal/Puurs rijden in een aangepaste dienstregeling; reizigers dienen in Essen (B) over te stappen op een andere trein\n<br/> plan uw reis in de Internationale Reisplanner\n<br/> <br/>\n <b>Extra reistijd: een kwartier tot een half uur</b><br/>\n</p>Current disruptions (=unscheduled disruptions + current engineering work)
Showing only columns Traject and Periode:
Scheduled engineering work(=scheduled engineering work)
This call returns scheduled engineering work for the next 2 weeks.
example:
sched <- get_scheduled_engineering_work()
sched[2:4,c("Traject","Periode", "Advies")]
#> Traject
#> 2 Rotterdam Centraal-Dordrecht
#> 3 Alphen a/d Rijn-Gouda
#> 4 Rotterdam Centraal/Den Haag Centraal-Woerden-Utrecht Centraal
#> Periode
#> 2 maandag 30 juli tot en met maandag 6 augustus 00.40 uur
#> 3 maandag 30 juli tot en met maandag 6 augustus
#> 4 maandag 30 juli tot en met maandag 6 augustus
#> Advies
#> 2 Raadpleeg Internet
#> 3 Raadpleeg Internet
#> 4 Raadpleeg InternetCurrent disruptions for a specific station (=unscheduled disruptions + current engineering work)
Showing only first 2 messages:
get_disruptions_station(station = "Rotterdam Centraal")$Bericht[1:2]
#> [1] "<p>\n<b>Wanneer: vanaf zaterdag 26 mei </b><br/>\n<b>Oorzaak: aangepaste dienstregeling</b><br/>\n<b>Advies: U kunt gebruikmaken van de gewijzigde dienstregeling</b>\n<br/>Stoptreinen tussen Roosendaal en Antwerpen Centraal/Puurs rijden in een aangepaste dienstregeling; reizigers dienen in Essen (B) over te stappen op een andere trein\n<br/> plan uw reis in de Internationale Reisplanner\n<br/> <br/>\n <b>Extra reistijd: een kwartier tot een half uur</b><br/>\n</p>"
#> [2] "<p>\n<b>Wanneer: maandag 30 juli tot en met maandag 6 augustus 00.40 uur </b><br/>\n<b>Oorzaak: werkzaamheden</b><br/>\n<b>Advies: U kunt gebruikmaken van de gewijzigde dienstregeling</b>\n<br/>de dienstregeling is aangepast tussen Rotterdam Centraal en Dordrecht\n<br/> <br/>\n <b>Extra reistijd: geen extra reistijd</b><br/>\n</p>"