README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

api_token <- Sys.getenv("BUNDESTAG_API")
library(tidybundestag)
```

# tidybundestag

<!-- badges: start -->
<!-- badges: end -->

`tidybundestag` wraps up the official API of the German Bundestag in R. 

It can be used to retrieve data on: 

* activities (aktivität) 
* "Drucksachen" 
* Members of the Bundestag
* Plenary protocols
* Parliamentary processes (Vorgänge)

For more information on the API, please visit: [https://dip.bundestag.de/documents/informationsblatt_zur_dip_api.pdf](https://dip.bundestag.de/documents/informationsblatt_zur_dip_api.pdf)

## Installation

You can install the latest version of tidybundestag from Github with 

``` r
remotes::install_github("benjaminguinaudeau/tidybundestag")
```

## Api Key

Access to the API is controlled with an API key. To obtain this api-key please visit the Bundestag [website](https://dip.bundestag.de/%C3%BCber-dip/hilfe/api#content). 

tidybundestag functions will read the API key from the environment variable `BUNDESTAG_API`. In order to add your key to your environment file, you can use the function `edit_r_environ()` from the {{usethis}}.

This will open your .Renviron file in your text editor. Now, you can add the following line to it:

```r
BUNDESTAG_API="YOUR_API_KEY"
```

Save the file and restart R for the changes to take effect.

Alternatively, you can provide an explicit definition of your API key with each function call using the `api_token` argument.

## Example

```{r, eval = F}
library(tidybundestag)
```


Once you have an api-key, you can start accessing data:

```{r}
bt_vorgang(n_max = 100) %>%
  dplyr::glimpse()
```

## Endpoints

The API of the Bundestag proposes 8 different endpoints. 

`tidybundestag` always returns a tibble where each row represents one unit (i.e. one process, one plenary, one questions, one person, etc...). The original json-structure is embedded in the tibble as a list-column, that can be easily handled with [`tidyr`](https://tidyr.tidyverse.org/reference/nest.html).

### Activities

```{r}
bt_aktivitaet(n_max = 100) %>%
  dplyr::glimpse()
```

### Drucksache

```{r}
bt_drucksache(n_max = 100) %>%
  dplyr::glimpse()
```

### Drucksache-Text

```{r}
bt_drucksache_text(n_max = 20) %>%
  dplyr::glimpse()
```

### Person

```{r}
bt_person(n_max = 20) %>%
  dplyr::glimpse()
```


### Plenarprotokoll

```{r}
bt_plenarprotokoll(n_max = 100) %>%
  dplyr::glimpse()
```

### Text of plenarprotokoll

```{r}
bt_plenarprotokoll_text(n_max = 20) %>%
  dplyr::glimpse()
```

### Vorgang

```{r}
bt_vorgang(n_max = 100) %>%
  dplyr::glimpse()
```

### Vorgangsposition

```{r}
bt_vorgangsposition(n_max = 100) %>%
  dplyr::glimpse()
```

## Query Parameter

+ id: id of the desired unit
+ start_date: First day of the desired period (character string YYYY/MM/DD)
+ end_date: Last day of the desired period (character string YYYY/MM/DD)
+ drucksache: Drucksache number of the desired unit
+ plenarprotokoll: Id of a plenary protocol related to the desired unit
+ vorgang: Id of a process related to the desired unit 
+ zuordnung: Attribution to a given institution (one of `c('BT', 'BR', 'BV', 'EK')`)


### id (one or several)

```{r}
bt_vorgang(id = "279665")
```

```{r}
bt_drucksache_text(id = c("239894", "234517"))
```

### start_date

```{r}
bt_vorgang(n_max = 100, start_date = "2021-01-01") %>%
  dplyr::glimpse()
```

### end_date

```{r}
bt_drucksache(n_max = 100, end_date = "2020-01-01") %>%
  dplyr::glimpse()
```



### drucksache

```{r}
bt_vorgang(drucksache = 68852) %>%
  dplyr::glimpse()
```

### plenarprotokoll

```{r}
bt_vorgang(plenarprotokoll = 908) %>%
  dplyr::glimpse()
```


### zuordnung

```{r}
bt_plenarprotokoll(n_max = 100, zuordnung = "BT") %>%
  dplyr::glimpse()
```

## Unnest list-columns

```{r}
members <- bt_person(n_max = 200) %>%
  dplyr::glimpse()

roles <- members %>%
  tidyr::unnest(person_roles, names_sep = "_", keep_empty = T) %>%
  dplyr::glimpse()
```


```{r}
roles %>%
  dplyr::filter(!is.na(person_roles_funktion)) %>%
  dplyr::count(person_roles_funktion) %>%
  ggplot2::ggplot(ggplot2::aes(person_roles_funktion, n)) +
  ggplot2::geom_col() +
  ggplot2::coord_flip()
  
```