---
title: "Accessing the DMI API using {dmir}"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Accessing the DMI API using {dmir}}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(dmir)
library(ggplot2)
```

The `dmir` package provides a few helper functions to make interaction with the DMI API easier. To use the functions in `dmir` that calls the API you'll need to have at least one API key. 
To setup an API key follow the instruction [here](https://confluence.govcloud.dk/pages/viewpage.action?pageId=26476690). You'll be needing a key for each service (one for climate data, one for meteorological observation data etc.)

## Preparation
Once you have your API key store it in a safe location where you can also find it again. To use it in scripts it is recommended that you store it in your `.Renviron` file like so:

```bash
DMI_MET_API_KEY="YOUR-CODE-GOES-HERE"
```
You can use `usethis::edit_r_environ()` to open the `.Renviron` file if you use RStudio. 

Once you've defined your API key in the environment file you can access it in scripts with `Sys.getenv("NAME-OF-ENV-VAR")`.

## Getting data

There is a limit to how much data the API will allow you to get in one go and the resolution on particularly the meteorological observation data is high. So I recommend that you only get one parameter at a time and possibly also limit the time period you request. Use multiple calls to the API if you need more than that will cover. 

The DMI API is documented [here](https://confluence.govcloud.dk/display/FDAPI/Danish+Meteorological+Institute+-+Open+Data). Find the ID for the station you are interested and find the parameter ID for your parameter of interest. Information about stations and parameters are nested under the service (Climate data, Meteorological observation etc.).

### Example

To show how it works we will try to get the daily mean temperature for Daneborg which we can see [here](https://confluence.govcloud.dk/pages/viewpage.action?pageId=41717446) has station ID 04330. 

```{r get-daneborg, eval=FALSE}
daneborg <-
  dmi_get_climate(
    parameter = "mean_temp",
    time_resolution = "month",
    api_key = Sys.getenv("DMI_CLIMATE_API_KEY"),
    station_id = "04330",
    date_start = "2020-01-01",
    date_end = "2020-12-31"
  )
```

This downloads a geoJSON file with the data. The file is stored in a temporary location. It can be read using the [sf](https://r-spatial.github.io/sf/) package.

```{r read-daneborg, eval=FALSE}
daneborg <- sf::read_sf(daneborg)
```

```{r include=FALSE}
data("daneborg")
```

```{r plot-daneborg, fig.width=7, fig.retina=3}
daneborg |> 
  ggplot(aes(x = as.Date(from),
                y = value)) +
  geom_line() +
  geom_point() + 
  labs(y = "Daily mean temperature (\u00B0C)",
       x = "Date",
       title = "Temperature during 2020 at Daneborg, Greenland",
       caption = "Data downloaded from DMI via {dmir}") + 
  theme_minimal()
```

And as you figured, it is pretty cold at Daneborg!