R bindings to the Nederlandse Spoorwegen API (NS, Dutch railways).
Package support caching of the made requests in-memory (enabled by default).
The package is still in development and can be downloaded with devtools
:
# install.packages("devtools")
devtools::install_github("jjongbloets/nsapi")
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 XMLdownload.<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.
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" )
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)
Read more in the API definition
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)
Read more in the API definition
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)
Read more in the API definition
TODO
TODO
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, seedifftime
for possible values. Type:str
. Default:mins