In jjongbloets/nsapi: NS API Package

require(knitr)
rm(list=ls())
knitr::opts_chunk$set(
  ##########################
  eval = FALSE, # ENABLE OR DISABLE ALL CHUNK EVALUATION
  ##########################
  echo = TRUE
)

NSAPI

R bindings to the Nederlandse Spoorwegen API (NS, Dutch railways).

Package support caching of the made requests in-memory (enabled by default).

Installation

The package is still in development and can be downloaded with devtools:

# install.packages("devtools")
devtools::install_github("jjongbloets/nsapi")

Usage

In order to use this package you need a NS API Account (Free)

The NS provides API's to different datasets:

Stations, provides information on all stations known by NS (tested)
Departures, provides information on real-time departure times (tested)
Disruptions, provides information on actual and planned disruptions (tested)
Prices, provides information on ticket prices (not implemented)
Planner, provides advice on train travelling (not implemented)

For each dataset three functions are implemented:

get.<dataset> retrieves and parses the XML
download.<dataset> downloads the XML (and returns XML)
parse.<dataset> parses XML to data.frame

Usage information and examples can be found in the unit tests and below.

Credential loading

When the package is being loaded into memory, it will look for the NS_USER and NS_PASS variables in the Global Environment. If present, these will be used and stored in the auth_cache environment. If these variables are not found a message will be displayed in the console, without credentials all requests will fail.

Credentials can be supplied by either calling the save.credentials function (see below) or by providing the ns.user and ns.pass parameters in every get or download function call.

save.credentials( "user", "pass" )

Retrieving stations information

NS provides a list of all stations that are somehow related to or used by NS. The stations dataset can be retrieved using:

# download and parse XML: yields data.frame
get.stations()
# only download XML: yields xml-document
download.stations()
# parse XML to data.frame: yields data.frame
parse.stations(xml.data)

Retrieving departures information

NS provides a list of all trains that are scheduled to leave a given station within the hour or if this yields a list of less than 10 trains, the next 10 departures times are returned.

The get and download functions for this dataset require a station name (Code, Short, Medium or Long format).

# download and parse XML: yields data.frame
get.departures(station)
# only download XML; yields xml-document
download.departures(station)
# parse XML to data.frame; yields data.frame
parse.departures(xml.data)

Retrieving Disruption information

This is a somewhat complex dataset, because it actually consists of two combined datasets; planned disruptions and unplanned disruptions. Both datasets are returned by the functions, which especally important when retrieving disruption information for a particular station.

The API uses three (essentially exclusive) flags to indicate what information is requested.

The station flag takes the name of a station and returns all planned and actual disruptions
The actual flag is a boolean and if set to true returns all currently active unplanned and planned disruptions
The planned flag (in NS API called unplanned) returns all planned disruptions

The API requires at least one flag to be set and will throw an error if none are set.

# download and parse XML: yields data.frame
get.disruptions(station=NULL, actual=NULL, planned=NULL)
# only download XML; yields xml-document
download.departures(station=NULL, actual=NULL, planned=NULL)
# parse XML to data.frame; yields data.frame
parse.departures(xml.data)

Retrieve ticket price information

TODO

Retrieve travel recommendations (planner)

TODO

Configurartion

Caching

A simple form of caching is implemented by storing the retrieved XML files in the xml_cache environment. When enabled, the obtained XML documents (identified by their request url) are stored along with a timestamp. Every time a new request is made, the url will be looked up and if present the validity of the cache entry is checked based on an expiration time.

The following options can be set with the setOption function.

nsapi.cache, Enables/Disables caching. Type: bool. Default: TRUE
nsapi.cache.expire.after, After how long the cache entry becomes invalid. Type: integer. Default: 20
nsapi.cache.expire.units, Units of the expiration time, see difftime for possible values. Type: str. Default: mins