Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/CorrelAid/datenguideR
R wrapper for the datengui.de GraphQL API to easily access German regional statistics
https://github.com/CorrelAid/datenguideR
api-wrapper datenguide german-language graphql regional-data rstats
Last synced: 3 months ago
JSON representation
R wrapper for the datengui.de GraphQL API to easily access German regional statistics
- Host: GitHub
- URL: https://github.com/CorrelAid/datenguideR
- Owner: CorrelAid
- License: gpl-3.0
- Created: 2019-06-22T10:49:26.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-07-23T15:43:41.000Z (over 3 years ago)
- Last Synced: 2024-06-12T14:28:01.329Z (5 months ago)
- Topics: api-wrapper, datenguide, german-language, graphql, regional-data, rstats
- Language: R
- Homepage:
- Size: 3.52 MB
- Stars: 25
- Watchers: 7
- Forks: 3
- Open Issues: 13
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- jimsghstars - CorrelAid/datenguideR - R wrapper for the datengui.de GraphQL API to easily access German regional statistics (R)
README
---
output: github_document
---
# datenguideR 
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.width = 6,
fig.height = 4,
fig.path = "man/figures/README-",
out.width = "100%"
)
```
[](https://travis-ci.org/CorrelAid/datenguideR)
[](https://codecov.io/gh/CorrelAid/datenguideR?branch=master)
[](https://www.gnu.org/licenses/gpl-3.0.en.html)
[](https://github.com/ellerbrock/open-source-badges/)
Access and download German regional statistics from Datenguide . `datenguideR` provides a wrapper for their GraphQL API and also includes metadata for all available statistics and regions.
**Overview**
+ [Usage](https://github.com/CorrelAid/datenguideR#usage)
+ [Examples](https://github.com/CorrelAid/datenguideR#examples)
+ [Search meta data (`dg_search`)](https://github.com/CorrelAid/datenguideR#dg_search)
+ [Main function (`dg_call`)](https://github.com/CorrelAid/datenguideR#dg_call)
+ [Multiple regions (at once)](https://github.com/CorrelAid/datenguideR#multiple-regions-with-nuts_nr-or-lau_nr)
+ [Plot data on maps (`dg_map`)](https://github.com/CorrelAid/datenguideR#dg_map)
+ [Use Cases](https://github.com/CorrelAid/datenguideR#use-cases)
+ [Credits and Acknowledgements](https://github.com/CorrelAid/datenguideR#credits-and-acknowledgements)
+ [Code of Conduct](https://github.com/CorrelAid/datenguideR#code-of-conduct)
## Usage
First, install `datenguideR` from GitHub:
```{r, eval=F}
devtools::install_github("CorrelAid/datenguideR")
```
Load package:
```{r}
library(datenguideR)
```
## Examples
Get IDs of all available NUTS-1 regions:
```{r}
datenguideR::dg_regions %>%
dplyr::filter(level == "nuts1") %>%
knitr::kable()
```
Get all available meta data on statistics, substatistics, and parameters:
```{r}
datenguideR::dg_descriptions
```
### `dg_search`
You can also use `dg_search` to look for a variable of interest. The function will match your string with any strings in the `dg_descriptions` data frame, returning only rows with those matches.
Looking for variables where the string *"vote"* appears somewhere in the documentation:
```{r}
dg_search("vote")
```
Note: Descriptions of variables are also available in English now! Translated via the [`googleLanguageR`](https://github.com/ropensci/googleLanguageR) package.
```{r}
dg_search("vote") %>%
dplyr::select(stat_name, dplyr::contains("_en"))
```
### `dg_call`
The main function of the package is `dg_call`. It gives access to all API endpoints.
Simply pick a statistic and put it into `dg_call()` (infos can be retrieved from `dg_descriptions`).
For example:
- `stat_name`: AI0506 *(Wahlbeteiligung, Bundestagswahl)*
- `region_id`: 11 (stands for Berlin)
```{r}
dg_call(region_id = "11",
year = 2017,
stat_name = "AI0506")
```
A slightly more complex call with substatistics:
- `stat_name`: BETR08 *(Landwirtschaftliche Betriebe mit Tierhaltung)*
- `substat_name`: TIERA8 *(Landwirtschaftliche Betriebe mit Viehhaltung)*
- `parameter`:
- TIERART2 *(Rinder)*
- TIERART3 *(Schweine)*
```{r}
dg_call(region_id = "11",
year = c(2001, 2003, 2007),
stat_name = "BETR08",
substat_name = "TIERA8",
parameter = c("TIERART2", "TIERART3"))
```
If you give no parameters for a substat, it will default to return results for all of them.
```{r}
dg_call(region_id = "11",
year = c(2001, 2003, 2007),
stat_name = "BETR08",
substat_name = "TIERA8")
```
### Multiple regions with `nuts_nr` or `lau_nr`
Instead of specifying a `region_id` for individual Bundesland (state) data you can also use `nuts_nr` to receive data for *NUTS-1*, *NUTS-2* and *NUTS-3*.
Just leave `region_id` blank and provide either a `nuts_nr` (or `lau_nr`) to get data for multiple regions at once.
- `stat_name`: AI0506 *(Wahlbeteiligung, Bundestagswahl)*
```{r}
dg_call(nuts_nr = 1,
year = 2017,
stat_name = "AI0506")
```
- `stat_name`: BETR08 *(Landwirtschaftliche Betriebe mit Tierhaltung)*
- `substat_name`: TIERA8 *(Landwirtschaftliche Betriebe mit Viehhaltung)*
```{r}
dg_call(nuts_nr = 1,
year = c(2001, 2003, 2007),
stat_name = "BETR08",
substat_name = "TIERA8")
```
- `stat_name`: BAU018 *Total non-residential buildings*
- `substat_name`: BAUAHZ *Main Type of Heating*
```{r}
dg_call(nuts_nr = 1,
stat_name = "BAU018",
substat_name = "BAUAHZ",
year = 2016)
```
### `dg_map`
You can also use `dg_map` to plot retrieved data on a Germany map. This currently only supports NUTS-1 and NUTS-2. Arguments are (mostly) identical to `dg_call`.
```{r}
dg_map(nuts_nr = 1,
year = 2017,
stat_name = "AI0506")
```
The output is a ggplot object and can be manipulated further.
```{r}
dg_map(nuts_nr = 1,
year = 2017,
stat_name = "AI0506") +
ggthemes::theme_map() +
ggplot2::scale_fill_viridis_c("Voter Turnout") +
ggplot2::ggtitle("Voter Turnout in German Parliamentary Election (2017)") +
ggplot2::theme(legend.position = "right")
```
You can also return the data and use your own plotting functions with `return_data = TRUE`.
```{r}
turnout_dat <- dg_map(nuts_nr = 1,
year = 2017,
stat_name = "AI0506",
return_data = T)
turnout_dat
```
## Use Cases
Check out some use cases. For example here:
+ [Correlaid Meetup - datenguideR workshop](https://github.com/TripLLL/weRnuts3)
## Credits and Acknowledgements
datenguideR builds on the amazing work of [Datenguide](https://datengui.de/) and their [GraphQL API](https://github.com/datenguide/datenguide-api). We especially thank [Simon Jockers](https://twitter.com/sjockers), [Simon Wörpel](https://twitter.com/simonwoerpel), and [Christian Rijke](https://twitter.com/crijke) for their constructive feedback, helpful comments, and overall support while developing the package.
The data is retrieved via the Datenguide API from the German Federal Statistical Office and the statistical offices of the German states. Data being used via this package has to be credited according to the [Datenlizenz Deutschland – Namensnennung – Version 2.0](https://www.govdata.de/dl-de/by-2-0).
This package was created with [devtools](https://github.com/r-lib/devtools), [usethis](https://github.com/r-lib/usethis), and [roxygen2](https://github.com/r-lib/roxygen2). Continuous integration was done with [Travis CI](https://travis-ci.org/).
## Code of Conduct
datenguideR is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.