# Destination Weather API

Weather forecasts, reports on current weather conditions, astronomical information and alerts at a specific location based on the ‘HERE Destination Weather’ API.

## Observations

In order to request information about the current weather situation points of interest (POIs) have to be provided. The POIs must be an `sf` object containing geometries of type `POINT` or a `character` vector containing place names (e.g. cities). These POIs are passed to the `weather()` function, whereby the `product` parameter is set to `"observation"`:

    observation <- weather(
      poi = poi,
      product = "observation"
    )

The return value is an `sf` object, which contains the `POINT` geometries of the provided POIs and the most recent record on the observed weather. The measurements are taken from the nearest weather observation stations with respect to the POIs. The distance of the stations to the provided POIs is an indicator for the reliabilty of the weather information at each POI. A table of the observed weather near the example POIs:

id | city | distance | daylight | description | sky_info | sky_desc | temperature | temperature_desc | comfort | high_temperature | low_temperature | humidity | dew_point | precipitation_probability | rain_fall | wind_speed | wind_direction | wind_descr | wind_descr_short | uv_index | uv_descr | barometer_pressure | barometer_trend
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
1 | Rönnimoos | 0.45 | day | Sprinkles. Partly sunny. Mild. | 14 | Partly sunny | 19.00 | Mild | 19.00 | 21.5 | 14.9 | 73 | 14.00 | 97 | 0.52 | 12.97 | 160 | South | S | 0 | Minimal | 1014.23 | Falling
1 | Alpnachstad | 11.18 | day | Sprinkles. More clouds than sun. Mild. | 13 | More clouds than sun | 18.00 | Mild | 18.00 | NA | NA | 88 | 16.00 | NA | NA | 12.97 | 190 | South | S | NA | NA | 1015.24 | Falling
1 | Stans | 11.74 | day | Light rain. Broken clouds. Mild. | 15 | Broken clouds | 18.00 | Mild | 18.00 | NA | NA | 83 | 15.00 | NA | NA | 3.71 | 0 | North | N | NA | NA | 1015.24 | Falling
2 | Lugano | 0.67 | day | Broken clouds. Mild. | 15 | Broken clouds | 21.00 | Mild | 21.00 | 21.4 | 17.5 | 94 | 20.00 | 99 | 2.69 | 7.41 | 10 | North | N | 0 | Minimal | 1015.24 | Steady
2 | Locarno-Magadino | 19.60 | day | Rain. Partly sunny. Mild. | 14 | Partly sunny | 20.00 | Mild | 20.00 | NA | NA | 94 | 19.00 | NA | NA | 5.56 | 220 | Southwest | SW | NA | NA | 1014.23 | Steady
2 | Locarno-Monti | 23.35 | day | Rain. Low clouds. Mild. | 19 | Low clouds | 18.72 | Mild | 18.72 | NA | NA | 90 | 17.11 | NA | NA | 7.41 | 280 | West | W | NA | NA | 1015.10 | Rising
2 | Milan / Malpensa | 45.13 | day | Broken clouds. Mild. | 15 | Broken clouds | 23.00 | Mild | 22.75 | NA | NA | 83 | 20.00 | NA | NA | 16.68 | 130 | Southeast | SE | NA | NA | 1014.23 | Steady
3 | Chailly | 0.34 | day | Heavy rain. Low clouds. Mild. | 19 | Low clouds | 17.11 | Mild | 17.11 | 19.8 | 16.3 | 95 | 16.28 | 99 | 2.38 | 3.71 | 120 | Southeast | SE | 0 | Minimal | 1016.20 | Rising
4 | Kleinhüningen | 0.43 | day | Rain. Overcast. Mild. | 18 | Overcast | 17.39 | Mild | 17.39 | 22.4 | 14.9 | 93 | 16.28 | 71 | 0.96 | 9.27 | 230 | Southwest | SW | 0 | Minimal | 1015.10 | Rising
5 | Kehrsatz | 0.62 | day | Light rain. More clouds than sun. Mild. | 13 | More clouds than sun | 18.00 | Mild | 18.00 | 18.7 | 13.3 | 83 | 15.00 | 76 | 0.58 | 9.27 | 180 | South | S | 0 | Minimal | 1015.24 | Rising
5 | Grenchen | 29.72 | day | Light rain. Scattered clouds. Mild. | 9 | Scattered clouds | 18.00 | Mild | 18.00 | NA | NA | 88 | 16.00 | NA | NA | 7.41 | 270 | West | W | NA | NA | 1015.24 | Steady
6 | Zürich (Kreis 6) / Oberstrass | 0.82 | day | Sprinkles. Partly sunny. Mild. | 14 | Partly sunny | 19.00 | Mild | 19.00 | 20.5 | 14.6 | 78 | 15.00 | 94 | 0.39 | 9.27 | 160 | South | S | 0 | Minimal | 1015.24 | Steady
6 | Zurich-Kloten | 11.00 | day | Scattered showers. Passing clouds. Mild. | 7 | Passing clouds | 19.00 | Mild | 19.00 | NA | NA | 78 | 15.00 | NA | NA | 16.68 | 160 | South | S | NA | NA | 1014.23 | Falling
6 | Zurich-Kloten | 11.34 | day | Rain showers. Overcast. Mild. | 18 | Overcast | 17.78 | Mild | 17.78 | NA | NA | 91 | 16.28 | NA | NA | 5.56 | 170 | South | S | NA | NA | 1014.50 | Rising
7 | Geneva | 0.49 | day | Lots of rain. Low clouds. Mild. | 19 | Low clouds | 17.11 | Mild | 17.11 | 23.0 | 12.4 | 92 | 15.78 | 99 | 2.99 | 14.83 | 90 | East | E | 0 | Minimal | 1013.70 | Rising
7 | Geneva | 4.52 | day | Rain showers. Broken clouds. Mild. | 15 | Broken clouds | 17.00 | Mild | 17.00 | NA | NA | 100 | 17.00 | NA | NA | 5.56 | 0 | North | N | NA | NA | 1016.26 | Falling
7 | Annecy-meythet | 31.32 | day | Light rain. Overcast. Cool. | 18 | Overcast | 16.61 | Cool | 16.61 | NA | NA | 91 | 15.11 | NA | NA | 12.97 | 70 | East | E | NA | NA | 1015.70 | Rising
7 | Annecy/Meythet | 32.61 | day | Light rain. Overcast. Mild. | 18 | Overcast | 17.00 | Mild | 17.00 | NA | NA | 88 | 15.00 | NA | NA | 12.97 | 70 | East | E | NA | NA | 1016.26 | Falling
8 | Vaduz | 0.94 | day | Rain. Overcast. Mild. | 18 | Overcast | 18.72 | Mild | 18.72 | 22.1 | 14.1 | 91 | 17.22 | 92 | 2.54 | 1.85 | 40 | Northeast | NE | 0 | Minimal | 1014.30 | Rising
8 | Feldkirch | 16.66 | day | Light rain. Overcast. Mild. | 18 | Overcast | 19.50 | Mild | 19.50 | NA | NA | 86 | 17.11 | NA | NA | 1.85 | 290 | West | W | NA | NA | 1013.20 | Rising
8 | Chur | 29.72 | day | Rain. Overcast. Mild. | 18 | Overcast | 17.78 | Mild | 17.78 | NA | NA | 94 | 16.78 | NA | NA | 7.41 | 20 | North | N | NA | NA | 1014.00 | Rising

Print the weather observation information on an interactive leaflet map:

    if (requireNamespace("mapview", quietly = TRUE)) {
      m <-
        mapview::mapview(observation,
          zcol = "temperature",
          cex = observation$humidity / 10,
          layer.name = "Observation",
          map.types = c("Esri.WorldTopoMap"),
          homebutton = FALSE
        ) +
        mapview::mapview(poi,
          zcol = "city",
          cex = 1,
          col.region = "black",
          legend = FALSE,
          homebutton = FALSE
        )
      m
    }

## Forecast

An hourly forecast of the predicted weather for the following seven days can be obtained by setting the `product` parameter to `"forecast_hourly"`:

    forecast <- weather(
      poi = poi,
      product = "forecast_hourly"
    )

Print the weather observation information on an interactive leaflet map with popup graphs for temperature and humidity:

1. Create a list containing the temperature and humidity graphs for every POI:

    if (requireNamespace("ggplot2", quietly = TRUE)) {
      g <- lapply(seq_len(nrow(forecast)), function(x) {
        df <- forecast$forecasts[[x]]
        ggplot2::ggplot(df, ggplot2::aes(x = time)) +
          ggplot2::geom_line(ggplot2::aes(y = temperature, color = "Temperature")) +
          ggplot2::geom_line(ggplot2::aes(y = humidity / 5, color = "Humidity")) +
          ggplot2::scale_y_continuous(sec.axis = ggplot2::sec_axis(~ . * 5, name = "Relative humidity [%]")) +
          ggplot2::scale_color_manual(values = c("blue", "red")) +
          ggplot2::labs(y = "Air temperature [°C]", x = "", colour = "") +
          ggplot2::ggtitle(forecast$city[x]) +
          ggplot2::theme_minimal() +
          ggplot2::theme(legend.position = "bottom", panel.background = ggplot2::element_rect(color = NA))
      })
    }

2. Then add list of graphs to the leaflet map using the the `popup` parameter:

    if (requireNamespace(c("ggplot2", "mapview", "leafpop"), quietly = TRUE)) {
      m <-
        mapview::mapview(forecast,
          color = "black",
          col.region = "yellow",
          layer.name = "Weather station",
          zcol = "city",
          map.types = c("Esri.WorldTopoMap"),
          homebutton = FALSE,
          legend = FALSE,
          popup = leafpop::popupGraph(g)
        ) +
        mapview::mapview(poi,
          zcol = "city",
          cex = 1,
          col.region = "black",
          layer.name = "POI",
          legend = FALSE,
          homebutton = FALSE
        )
      m
    }

## Astronomy

An astronomical forecast is requested by setting the `product` parameter to `"forecast_astronomy"`:

    astronomy <- weather(
      poi = poi,
      product = "forecast_astronomy"
    )

Print a table for the sun and moon times of the first example POI, where the nearest station is ‘Emmenbrücke’:

time | sun_rise | sun_set | moon_rise | moon_set | moon_phase | moon_phase_description
--- | --- | --- | --- | --- | --- | ---
2023-09-18 | 07:07:00 | 19:33:00 | 10:33:00 | 20:47:00 | 0.079 | Waxing crescent
2023-09-19 | 07:09:00 | 19:31:00 | 11:45:00 | 21:08:00 | 0.141 | Waxing crescent
2023-09-20 | 07:10:00 | 19:29:00 | 12:59:00 | 21:35:00 | 0.218 | Waxing crescent
2023-09-21 | 07:11:00 | 19:27:00 | 14:14:00 | 22:11:00 | 0.310 | Waxing crescent
2023-09-22 | 07:13:00 | 19:25:00 | 15:25:00 | 23:01:00 | 0.412 | First Quarter
2023-09-23 | 07:14:00 | 19:23:00 | 16:26:00 | NA | 0.521 | First Quarter
2023-09-24 | 07:15:00 | 19:21:00 | 17:16:00 | 00:05:00 | 0.631 | Waxing gibbous
2023-09-25 | 07:17:00 | 19:19:00 | 17:53:00 | 01:23:00 | 0.738 | Waxing gibbous

## Alerts

Current weather alerts, near provided POIs, are obtain by the product `alerts`:

    alerts <- weather(
      poi = poi,
      product = "alerts"
    )

This returns an `sf` object with the POIs and the attribute `"alerts"`, which contains the current weather alerts. If no alerts are recorded near a POI the attribute `"alerts"` is `NULL`.

## API Reference

- Destination Weather API