-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
166 lines (119 loc) · 4.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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
---
output: github_document
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
# STATcubeR <img src="man/figures/logo.png" align="right" alt="" width="120" />
<!-- badges: start -->
[](https://travis-ci.com/statistikat/STATcubeR)
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://github.com/statistikat/STATcubeR/commits/master)
[](https://github.com/statistikat/STATcubeR)
<!-- badges: end -->
R Interface for the STATcube REST API
## Setup
See the [setup article] for instructions on how to install the package
and set your API key.
## Usecase: JSON-Request
In the following example, a table will be exported from STATcube into an
R session. This process involves four steps
* create a table with the STATcube GUI (table view)
* download an "API request" for the table (format: `*.json`).
* send the `json` file to the API using `STATcubeR`.
* convert the return value into a `data.frame`
### create a table with the STATcube GUI
Use the graphical user interface of STATcube to create a table. Visit
http:https://sdbext:8081/statistik.at/ext/statcube/home.
### Download an API request
Choose "Open Data API Abfrage (.json)" in the download options. This will
save a json file on your local file system.
<img src="man/figures/download_json.png" />
### Send the json to the API
Provide the path to the downloaded file in `sc_get_response()`.
``` r
my_response <- sc_get_response("path/to/api_request.json")
```
The object `my_response` contains the raw API response from `httr::post()`.
Printing the object will summarize the request.
```{r, include=FALSE}
pkgload::load_all(export_all = FALSE, reset = FALSE, helpers = FALSE)
conflicted::conflict_prefer("filter", "dplyr")
```
```{r, cache = TRUE}
(json_path <- sc_example("bev_seit_1982.json"))
my_response <- sc_get_response(json_path)
my_response
```
### Convert into a data frame
The return value of `sc_get_response()` can be converted into a `data.frame`
using the generic function `as.data.frame()`.
```r
as.array(my_response)
as.data.frame(my_response)
```
This will produce a tidy table, which contains a column for each field
of the table. Furthermore, two columns will be present for each measure
```{r}
as.data.frame(my_response) %>% .[c(1:4, 19:24), ]
```
The column `Fallzahl_a` contains annotations for the column
`Fallzahl`. In order to get explanations about those annotations, use the
function `sc_annotation_legend()`.
```{r}
sc_annotation_legend(my_response)
```
In this case, we see that row 21 contains a value `NA` (**N**ot **A**vailable)
because the value is not disclosed ("Verkreuzung nicht erlaubt"). However, the
zero value in row 20 can be considered a "real zero value" because no
annotations are provided.
## Usecase: Saved Table
If saved tables are present in STATcube, those can be imported without
downloading a json file. All saved tables can be shown with
`sc_saved_tables_list()`.
```{r, cache = TRUE}
sc_saved_tables_list()
```
Subsequently the `id` of a saved table can be used to import the table into R.
```{r, cache = TRUE}
tourism_ts <- sc_saved_table("str:table:eec7dd70-25c4-4e5a-a6ae-1a9cd15d3c4c")
tourism_ts
```
To make the table available for other users of `STATcubeR`, the response can
be exported into a json.
```{r}
sc_write_json(tourism_ts, "tourism_ts.json")
```
```{r, include=FALSE}
on.exit(fs::file_delete("tourism_ts.json"))
```
The generated json file contains an API request that can be used in
`sc_get_response()`.
```r
my_response <- sc_get_response("tourism_ts.json")
```
## Misc
To get the raw API response content, use `sc_content()`. This function returns
a nested list, containing data and metadata about the table.
```{r}
my_content <- sc_content(my_response)
names(my_content)
my_content$measures
```
There is experimental support for the endpoints `/info`, `/schema` and
`/rate_limit`. However, those endpoints are not exported by now.
```r
STATcubeR:::sc_get_info() %>% httr::content()
STATcubeR:::sc_get_schema() %>% httr::content()
STATcubeR:::sc_get_rate_limit() %>% httr::content()
```
STATcube uses caching for the `/table` endpoint by default. If the same
request to `sc_get_response()` is sent several times, this will not count
towards the rate-limit (100 requests per hour).
## API documentation
* `/table` endpoint: https://docs.wingarc.com.au/superstar/latest/open-data-api/open-data-api-reference/table-endpoint
* `/schema` endpoint: https://docs.wingarc.com.au/superstar/latest/open-data-api/open-data-api-reference/schema-endpoint
[setup article]: https://statistikat.github.io/STATcubeR/articles/articles/Setup.html