forked from ottlngr/openbahn
-
Notifications
You must be signed in to change notification settings - Fork 4
/
README.Rmd
89 lines (59 loc) · 2.92 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
options(width = 999)
```
# openbahn
[](https://travis-ci.org/ottlngr/openbahn)[](https://codecov.io/gh/ottlngr/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`:
- `location.name` to look up train stations
- `arrivalBoard` to retrieve arrival boards
- `departureBoard` to retrieve departure boards
- `journeyDetail` 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](mailto:[email protected]) and request a key for the timetable or _Fahrplan_ API, respectively.
## Installation
You can install openbahn from github with:
```{r gh-installation, eval = FALSE}
# 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:
```{r}
library(openbahn)
```
```{r,eval=FALSE}
openbahn_auth("YOUR_API_KEY_HERE")
```
`locationNameApi()` can be used to find a train station along with an internal ID and its coordinates:
```{r}
stations <- locationNameApi("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:
```{r}
mainz_hbf <- stations$content$LocationList$StopLocation$id[1]
departures <- departureBoardApi(id = mainz_hbf, date = "2017-12-01", time = "12:00")
departures
arrivals <- arrivalBoardApi(id = mainz_hbf, date = "2017-12-01", time = "12:00")
arrivals
```
For the particular trains in the arrival or departures board one can retrieve detailed information using `journeyDetailsApi()`. Therefor, the reference url of the desired train has to be looked up in the `JourneyDetailRef` data.frame:
```{r}
reference <- departures$content$DepartureBoard$Departure$JourneyDetailRef$ref[1]
details <- journeyDetailApi(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.
# Community Guidelines
Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.