---
title: "Get started with climaemet 1.0.0"
author: Diego Hernangómez
description: First steps with climaemet
vignette: >
  %\VignetteIndexEntry{Get started with climaemet 1.0.0}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

<!--
climaemet.qmd is generated from climaemet.qmd.orig. Please edit that file.
-->



Since the last release, this package has been integrated into
[rOpenSpain](https://ropenspain.es/), a community of **R** enthusiasts whose
ultimate goal is to create high-quality **R** packages for working with public
Spanish open data sources.

As of version 1.0.0, the package includes improvements and breaking changes for
smoother interaction with the AEMET API.

## API key

### Get your API key

To download data from AEMET, you need a free API key, which you can get at
<https://opendata.aemet.es/centrodedescargas/altaUsuario>.

Once you have your API key, you can use any of the following methods:

#### a. Set API key with `aemet_api_key()`

This is the recommended option. Run:


``` r
aemet_api_key("YOUR_API_KEY", install = TRUE)
```

Using `install = TRUE` stores the API key on your local computer and reloads it
each time you load the package.

#### b. Use an environment variable

This is a temporary alternative. You can set your API key as an environment
variable:


``` r
Sys.setenv(AEMET_API_KEY = "YOUR_API_KEY")
```

Note that this is valid only for the current session. You need to run this
command each time you restart your **R** session.

#### c. Modify your `.Renviron` file

This stores your API key permanently on your machine. Start editing your
`.Renviron` file with:

``` r
usethis::edit_r_environ()
```

Now you can add the following line to your `.Renviron` file:

```         
AEMET_API_KEY=YOUR_API_KEY
```

## New features

### `tibble` format

From version 1.0.0 onward, **climaemet** returns its results in [**tibble**
format](https://tibble.tidyverse.org/). The functions also try to parse fields
into their correct types. For example, date and hour fields are parsed as
date-time objects and numeric fields as double values.

See how a tibble is displayed:


``` r
# See a tibble in action

aemet_last_obs("9434")
#> # A tibble: 12 × 25
#>    idema   lon fint                 prec   alt  vmax    vv    dv   lat  dmax ubi        pres    hr stdvv
#>    <chr> <dbl> <dttm>              <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <chr>     <dbl> <dbl> <dbl>
#>  1 9434  -1.00 2026-06-03 01:00:00     0   249  11.2   8.4   300  41.7   290 ZARAGOZA…  990.    55   1.1
#>  2 9434  -1.00 2026-06-03 02:00:00     0   249  12.8   8.1   305  41.7   305 ZARAGOZA…  990.    59   1.2
#>  3 9434  -1.00 2026-06-03 03:00:00     0   249  10.6   7.6   300  41.7   303 ZARAGOZA…  990.    62   1.2
#>  4 9434  -1.00 2026-06-03 04:00:00     0   249  12     7.1   317  41.7   295 ZARAGOZA…  990.    63   1.6
#>  5 9434  -1.00 2026-06-03 05:00:00     0   249  11.9   8     312  41.7   313 ZARAGOZA…  990.    63   1.1
#>  6 9434  -1.00 2026-06-03 06:00:00     0   249  12.5   7.7   308  41.7   318 ZARAGOZA…  990.    60   1.1
#>  7 9434  -1.00 2026-06-03 07:00:00     0   249  12.1   7.8   316  41.7   303 ZARAGOZA…  991.    57   1.5
#>  8 9434  -1.00 2026-06-03 08:00:00     0   249  12.4   9.9   312  41.7   303 ZARAGOZA…  990.    49   1.3
#>  9 9434  -1.00 2026-06-03 09:00:00     0   249  13.3   8.5   306  41.7   290 ZARAGOZA…  990.    42   1.5
#> 10 9434  -1.00 2026-06-03 10:00:00     0   249  12.2   7.9   310  41.7   303 ZARAGOZA…  990.    38   1.2
#> 11 9434  -1.00 2026-06-03 11:00:00     0   249  12.2   6.1   312  41.7   310 ZARAGOZA…  989.    33   1  
#> 12 9434  -1.00 2026-06-03 12:00:00     0   249  15.7   6.6   323  41.7   320 ZARAGOZA…  988.    29   1.3
#> # ℹ 11 more variables: ts <dbl>, pres_nmar <dbl>, tamin <dbl>, ta <dbl>, tamax <dbl>, tpr <dbl>,
#> #   stddv <dbl>, inso <dbl>, tss5cm <dbl>, pacutp <dbl>, tss20cm <dbl>
```

When possible, data representing dates and numbers are converted to the
appropriate type.

### Spatial objects with sf

Another major change in version 1.0.0 is the ability to return information in
spatial **sf** format using `return_sf = TRUE`. The coordinate reference system
(CRS) used is **EPSG:4326**, which corresponds to the **World Geodetic System
1984 (WGS 84)** and returns coordinates in latitude/longitude (unprojected
coordinates):


``` r
# You need to install sf if it is not already installed.
# Run install.packages("sf") to install it.

library(ggplot2)
library(dplyr)

all_stations <- aemet_daily_clim(
  start = "2021-01-08",
  end = "2021-01-08",
  return_sf = TRUE
)

ggplot(all_stations) +
  geom_sf(aes(colour = tmed), shape = 19, size = 2, alpha = 0.95) +
  labs(
    title = "Average temperature in Spain",
    subtitle = "8 Jan 2021",
    color = "Max temp.\n(celsius)",
    caption = "Source: AEMET"
  ) +
  scale_colour_gradientn(
    colours = hcl.colors(10, "RdBu", rev = TRUE),
    breaks = c(-10, -5, 0, 5, 10, 15, 20),
    guide = "legend"
  ) +
  theme_bw() +
  theme(
    panel.border = element_blank(),
    plot.title = element_text(face = "bold"),
    plot.subtitle = element_text(face = "italic")
  )
```

<div class="figure">
<img src="./spatial-1.png" alt="Example: temperature in Spain" width="100%" />
<p class="caption">Example: temperature in Spain</p>
</div>

## Further enhancements

Other enhancements included in version 1.0.0:

- Data functions are now vectorized where the AEMET API supports it.
- New function `get_metadata_aemet()`.
- New function `ggclimat_walter_lieth()`. It is now the default for
  `climatogram_*` functions
  [![Experimental](https://ropenspain.github.io/climaemet/reference/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental).
  Old behavior can be reproduced with options `ggplot2 = FALSE`.
- Plot functions gain new arguments (`verbose` and `...`). Colors can now be
  passed to the plotting functions.
- New example datasets: `climaemet::climaemet_9434_climatogram`,
  `climaemet::climaemet_9434_temp` and `climaemet::climaemet_9434_wind`.