In ottlngr/openbahn: Query the Deutsche Bahn Timetable API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
options(width = 999)

openbahn

openbahn provides functions to easily interact with the Timetable API, provided by the German railroad company Deutsche Bahn (DB). At the moment, the API does only provide timetable data for the German long-distance traffic. The following API endpoints exist and are covered by openbahn:

openbahn_locations to look up train stations
openbahn_arrivals to retrieve arrival boards
openbahn_departures to retrieve departure boards
openbahn_jounreys to retrieve detailed information for specific trains

To interact with the API, an API key is required.

API Key

To get an API key, one has to email to the DB Open-Data-Team and request a key for the timetable or Fahrplan API, respectively.

Installation

You can install openbahn from github with:

# install.packages("devtools")
devtools::install_github("ottlngr/openbahn")

Usage

First, openbahn_auth() can be used to store the API key in an environment variable all further openbahn functions will access:

library(openbahn)

openbahn_auth("YOUR_API_KEY_HERE")

openbahn_locations() can be used to find a train station along with an internal ID and its coordinates:

stations <- openbahn_locations(query = "Mainz Hbf")
stations

To retrieve arrival or departure boards, an id found in stations can be used. Furthermore, date and time the arrival or departure boards shall build on have to be provided:

mainz_hbf <- stations$content$LocationList$StopLocation$id[1]

departures <- openbahn_departures(id = mainz_hbf, date = Sys.Date() + 1, time = "12:00")
departures

arrivals <- openbahn_arrivals(id = mainz_hbf, date = Sys.Date() + 1, time = "12:00")
arrivals

For the particular trains in the arrival or departures board one can retrieve detailed information using openbahn_journey(). Therefor, the reference url of the desired train has to be looked up in the JourneyDetailRef data.frame:

reference <- departures$content$DepartureBoard$Departure$JourneyDetailRef$ref[1]
details <- openbahn_journeys(reference_url = reference)
details

References

For general information on the DB Timetable API visit http://data.deutschebahn.com/dataset/api-fahrplan (German). The data behind this API is licenced unter CC BY 4.0.