Get started with climaemet 1.0.0
Author: Diego Hernangómez
Description: First steps with climaemet

Since the last release, this package has been integrated into rOpenSpain, 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:

    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:

    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:

    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. 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:

    # 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):

    # 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")
      )

Example: temperature in Spain

## 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 . 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`.