In ottlngr/openbahn: Query the Deutsche Bahn Timetable API

openbahn

In 2016, the German railway company Deutsche Bahn launched its Open Data portal, where a growing number of datasets are made available. Besides datasets, Deutsche Bahn also offers some APIs to access even more data in a machine readable manner.

One of these APIs is the timetable or Fahrplan API, which offers target timetables for the German long-distance rail traffic. openbahn is mainly a wrapper around this API and provides additional static datasets from Deutsche Bahn.

Using openbahn

API key

To use openbahn or the timetable API in general, one has to acquire an API key from the Deutsche Bahn Open Data team. The easiest way to get such an API key is to email the Open Data team at [e-mail] as described on the website.

To avoid having to specify the API key with every call to the API, openbahn offers the openbahn_auth() function to store your API key in an environment variable in your R session. When necessary, openbahn will look for this environment variable and will read the API key from it.

library(openbahn)

openbahn_auth("YOUR_API_KEY_HERE")

The API key is now stored in your R session in the OPENBAHN_KEY variable. Along with the API key, also a user agent is set with openbahn_auth() used to identify towards the API:

Sys.getenv("OPENBAHN_USER_AGENT")

Arrival and departure boards

The timetable API returns arrival and departure boards for a given station on a specific date and time. Each station has an internal ID, which can be obtained from locationNameApi() which takes a character as input and returns a couple of stations matching the query:

library(openbahn)

openbahn_locations(query = "Mainz Hbf")

Along with the station name and ID, openbahn_locations() also returns the coordinates of the stations, which is handy for spatial applications. For later usage, we will store the station ID of Mainz Hbf in a variable:

station_id <- "008000240"

Now having the desired station ID, openbahn_arrivals() and openbahn_departures() can be used. To look for trains leaving Mainz Hbf at 9 a.m., use openbahn_departures() as follows:

date <- Sys.Date() + 1

dep <- openbahn_departures(id = station_id, date = date, time = "09:00")
dep

Journey details

The API offers an additional endpoint, which returns details to every connection found by using openbahn_arrivals() or openbahn_departures(). Using openbahn_journeys() one can use the reference links in the arrival or departure boards to get further information such as name and order of all stops, arrival and departure times and geocoordinates of all stops.

Every arrival or departure board has a column with reference links, which can be called with openbahn_journeys():

url <- dep$content$DepartureBoard$Departure$JourneyDetailRef$ref[1]

journey <- openbahn_journeys(url)

journey

The print method hides the geocoordinates, but they are present in the data.frame:

str(journey$content$JourneyDetail$Stops$Stop)

Using them it is easy to plot the route of the train onto a map:

library(dplyr)
library(ggplot2)
library(ggmap)

germany <- get_map(c(10.140, 51.276), zoom = 6, maptype = "toner")

data <- journey$content$JourneyDetail$Stops$Stop %>%
  mutate(lat = as.numeric(lat),
         lon = as.numeric(lon))

ggmap(germany) + 
  geom_point(data = data, aes(x = lon, y = lat, group = 1)) +
  geom_path(data = data, aes(x = lon, y = lat, group = 1)) + 
  coord_map()

ottlngr/openbahn documentation built on May 7, 2019, 9 p.m.