README.Rmd

---
title: "Statistics Denmark StatBank API connection"
output: 
  md_document:
    variant: markdown_github
---

This package connects to the [StatBank](http://www.statistikbanken.dk/statbank5a/) API from [Statistics Denmark](http://www.dst.dk).

This package is in early *BETA* and new changes will most likely not have backward compatibility.

### A short message in Danish

Denne R Statistics pakke indeholder funktioner til at give dig adgang til data gennem API'en fra Danmarks Statistik.
Funktionerne henter data fra Statistikbanken og retunerer data.frame objekter med værdierne du spørger efter i
dit funktionskald.

## Installation

You can only install the development version from github, using Hadley Wickham's [devtools](http://cran.r-project.org/web/packages/devtools/index.html) package:

```
if(!require("devtools")) install.packages("devtools")
library("devtools")
install_github("rOpenGov/dkstat")
```

## Examples

Here are a few simple examples that will go through the basics of requesting data from the StatBank
and the structure of the output.  

First, we'll load the package:

```{r, message=FALSE}
library(dkstat)
```

## Meta data

The dst_meta function retrieves meta data from the table you wan't to take a closer look at. It can be used to create the final request, but if you can figure out the structure of the query you can define it yourself.

We'll get some meta data from the [AULAAR table](http://www.statistikbanken.dk/AULAAR). The AULAAR table has net unemployment numbers.

```{r}
aulaar_meta <- dst_meta(table = "AULAAR", lang = "en")
```

The 'dst_meta' function returns a list with 4 objects:
- basics
- variables
- values 
- basic_query

### Basics

Let's see what the basics contains:

```{r}
aulaar_meta$basics
```

There's a table id, a short description, a unit description and when the table was updated.

### Variables

The variables in the list has a short description of each variable as well as the id. You might want to make sure that
you have supplied all the ID's where the elimination columns is equal to FALSE. The IDs where eliminnation is equal
FALSE are mandatory.

```{r}
aulaar_meta$variables
```

### Values

The values is a list object of all the values in each variable. You use the text column to construct your final query:

```{r}
str(aulaar_meta$values)
```


## Get data

You need to build your query based on the text column that each variable contains in the meta_data$values list.


```{r}
aulaar <- dst_get_data(table = "AULAAR", KØN = "Total", PERPCT = "Per cent of the labour force", Tid = 2013,
                       lang = "en")
str(aulaar)
```


In the request above I don't supply the meta_data to the dst_get_data function, but this is possible
as I will show below. It's a good idea to supply the meta data to the dst_get_data function if you
query the table more than once. If you don't supply the meta data the dst_get_data function will
request the meta data for the table and this will be very ineffecient.

Let's query the statbank using more than one value for each variable.

```{r}

folk1_meta <- dst_meta("folk1", lang = "da")

str(dst_get_data(table = "folk1", 
             OMRÅDE = c("Hele landet", "København", "Frederiksberg", "Odense"), 
             STATSB = "Danmark", 
             TID = "*", 
             lang = "da", 
             meta_data = folk1_meta))

```


I can also build a query beforehand and then use the query in the query parameter. This might
be a good way to split your script up into smaller pieces and make it more structured.  

You might have noticed that I use the * as a value in the TID variable. You can use the star as a alternative
to writing all the text values for the variable.  

```{r}

my_query <- list(OMRÅDE = c("Hele landet", "København", "Frederiksberg", "Odense"),
                 STATSB = "Danmark",
                 TID = "*")

str(dst_get_data(table = "folk1", query = my_query, lang = "da"))


str(dst_get_data(table = "AUP01", OMRÅDE = c("Hele landet"), TID = "*", lang = "da"))

```