Merge pull request #3 from tpisel/dev

.gitignore

@@ -3,3 +3,4 @@
 .Rdata
 .httr-oauth
 .DS_Store
+.Rproj

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: openmeteo
 Title: Retrieve Weather Data from the Open-Meteo API
-Version: 0.1.1
+Version: 0.2.1
 Authors@R: person("Tom", "Pisel", email = "mail@tompisel.com", role = c("aut",
     "cre","cph"))
 Description: A client for the Open-Meteo API that retrieves Open-Meteo
@@ -17,7 +17,6 @@ Imports:
     tibblify,
     dplyr,
     yaml,
-    lutz,
     testthat (>= 3.0.0)
 Suggests: 
     httptest

NAMESPACE

@@ -1,6 +1,10 @@
 # Generated by roxygen2: do not edit by hand
 
+export(air_quality)
+export(climate_forecast)
 export(geocode)
+export(marine_forecast)
+export(river_discharge)
 export(weather_forecast)
 export(weather_history)
 export(weather_now)

NEWS.md

@@ -1,3 +1,11 @@
+# openmeteo 0.2.0
+
+* Added support for additional APIs:
+  * Marine Weather
+  * Climate Forecasts
+  * Floods
+  * Air Quality
+
 # openmeteo 0.1.0
 
 * First public release.

R/air_quality.R

@@ -0,0 +1,80 @@
+#' Retrieve air quality data from the Open-Meteo API
+#'
+#' @description
+#'
+#' `air_quality()` calls the Open-Meteo Air Quality API to obtain pollutant,
+#' pollen, and particulate data. Historical and forecasted data is available.
+#'
+#' Refer to the API documentation at:
+#' <https://open-meteo.com/en/docs/air-quality-api>
+#'
+#' @details
+#'
+#' You will need to specify at least one air quality variable, such as PM10 or
+#' Carbon Monoxide, that you want forecasted data for. These variables are
+#' sampled or aggregated at _hourly_ intervals, and can be supplied as a list to
+#' request multiple variables over the same time period.
+#'
+#' Example hourly air quality variables include:
+#'
+#' |**Variable**     |**Description**                                          |
+#' |-----------------|---------------------------------------------------------|
+#' |`pm10`           |Particulate matter with diameter smaller than 10 µm      |
+#' |`carbon_monoxide`|Concentration in μg/m³ 10m above surface                 |
+#' |`european_aqi`   |European Air Quality Index                               |
+#' |`us_aqi`         |United States Air Quality Index                          |
+#' |`dust`           |Saharan dust particles 10m above ground                  |
+#'
+#' Full documentation for the forecast API is available at:
+#' <https://open-meteo.com/en/docs/air-quality-api>
+#'
+#' @param location Required. The location for which data will be retrieved.
+#'   Supplied as either a `c(latitude,longitude)` WGS84 coordinate pair or a
+#'   place name string (with co-ordinates obtained via [geocode()]).
+#' @param start,end Start and end dates in ISO 8601 (e.g. "2020-12-31"). If no
+#'   dates are supplied, data for the next 5 days will be provided by default.
+#' @param hourly Required. An air quality variable accepted by the
+#'   API, or list thereof. See details below.
+#' @param timezone specify timezone for time data as a string, i.e.
+#'   "australia/sydney" (defaults to "auto", the timezone local to the specified
+#'   `location`).
+#'
+#' @return Requested air quality data for the given location and time, as a
+#'   tidy tibble.
+#'
+#' @export
+#'
+#' @examples
+#' \donttest{
+#' # obtain Carbon Monoxide levels for Beijing over the next 5 days
+#' air_quality("Beijing", hourly = "carbon_monoxide")
+#' }
+air_quality <- function(
+    location,
+    start = NULL,
+    end = NULL,
+    hourly = NULL,
+    timezone = "auto") {
+  # validation
+  if (is.null(hourly)) {
+    stop("hourly measure not supplied")
+  }
+  if (!is.null(start) && !.is.date(start)) {
+    stop("start and end dates must be in ISO-1806 format")
+  }
+  if (!is.null(end) && !.is.date(end)) {
+    stop("start and end dates must be in ISO-1806 format")
+  }
+
+  base_url <- "https://air-quality-api.open-meteo.com/v1/air-quality"
+
+  .query_openmeteo(
+    location,
+    start, end,
+    hourly, NULL, # non-set fields passed as null
+    NULL,
+    NULL,
+    timezone,
+    base_url
+  )
+}

R/climate_forecast.R

@@ -0,0 +1,106 @@
+#' Retrieve climate change forecasts from the Open-Meteo API
+#'
+#' @description
+#'
+#' `climate_forecast()` calls the Open-Meteo Climate Change Forecast API to
+#' obtain long-range weather projections from a range of climate models.
+#'
+#' Refer to the API documentation at:
+#' <https://open-meteo.com/en/docs/climate-api>
+#'
+#' @details
+#'
+#' You will need to specify at least one weather variable, such as temperature,
+#' that you want projected forecasts for. The models currently only provide
+#' weather data aggregated at _daily_ intervals. Multiple variables can be
+#' supplied as a list.
+#'
+#' Example daily climate forecast variables include:
+#'
+#' |**Variable**        |**Description**                                       |
+#' |--------------------|------------------------------------------------------|
+#' |`temperature_2m_max`|Maximum daily air temperature at 2 meters above ground|
+#' |`precipitation_sum` |Sum of rain, showers, and snow over the preceding day |
+#' |`windspeed_10m_max` |Maximum daily wind speed at 10 meters above ground    |
+#'
+#' Different climate change models can be specified, which may differ in the
+#' weather variables predicted. Models include:
+#'
+#' |**Model**      |**Origin** |**Resolution**                                 |
+#' |---------------|-----------|-----------------------------------------------|
+#' |`EC_Earth3P_HR`|Europe     |29 km                                          |
+#' |`FGOALS_f3_H`  |China      |28 km                                          |
+#' |`MRI_AGCM3_2_S`|Japan      |20 km                                          |
+#'
+#' For all models and their available fields, refer to the full documentation
+#' for the climate API at: <https://open-meteo.com/en/docs/climate-api>
+#'
+#'
+#' @param location Required. The location for which data will be retrieved.
+#'   Supplied as either a `c(latitude,longitude)` WGS84 coordinate pair or a
+#'   place name string (with co-ordinates obtained via [geocode()]).
+#' @param start,end Required. Future start and end dates in ISO 8601 (e.g.
+#'   "2020-12-31").
+#' @param daily Required. A weather variable accepted by the API, or list
+#'   thereof. See details below.
+#' @param response_units Supply to convert temperature, windspeed, or
+#'   precipitation units. This defaults to: `list(temperature_unit = "celsius",`
+#'   `windspeed_unit = "kmh", precipitation_unit = "mm")`
+#' @param model Supply to specify a climate model for forecasted values (refer
+#'   to the API documentation).
+#' @param timezone specify timezone for time data as a string, i.e.
+#'   "australia/sydney" (defaults to "auto", the timezone local to the specified
+#'   `location`).
+#'
+#' @return Requested climate forecast data for the given location and time
+#'   period, as a tidy tibble.
+#'
+#' @export
+#'
+#' @examples
+#' \donttest{
+#' # Obtain projected precipitation for the North Pole in 2050
+#' climate_forecast(c(90, 0),
+#'   "2050-06-01", "2050-07-01",
+#'   daily = "precipitation_sum"
+#' )
+#'
+#' # Obtain projected temperatures for Madrid in 2050 in Fahrenheit, with ESMI1
+#' climate_forecast("Madrid",
+#'   "2050-06-01", "2050-07-01",
+#'   daily = "temperature_2m_max",
+#'   model = "MPI_ESM1_2_XR",
+#'   response_units = list(temperature_unit = "fahrenheit")
+#' )
+#' }
+climate_forecast <- function(
+    location,
+    start,
+    end,
+    daily = NULL,
+    response_units = NULL,
+    model = NULL,
+    timezone = "auto") {
+  # validation
+  if (is.null(daily)) {
+    stop("daily weather variables not supplied")
+  }
+  if (!is.null(start) && !.is.date(start)) {
+    stop("start and end dates must be in ISO-1806 format")
+  }
+  if (!is.null(end) && !.is.date(end)) {
+    stop("start and end dates must be in ISO-1806 format")
+  }
+
+  base_url <- "https://climate-api.open-meteo.com/v1/climate"
+
+  .query_openmeteo(
+    location,
+    start, end,
+    NULL, daily, # no hourly variables for climate forecasts
+    response_units,
+    model,
+    timezone,
+    base_url
+  )
+}

R/geocode.R

@@ -1,12 +1,12 @@
-#' Retrieve data from the Open-Meteo geocoding API
+#' Geocode a location using the Open-Meteo geocoding API
 #'
 #' @description
 #'
 #' Call the Open-Meteo Geocoding API to retrieve co-ordinates and other
 #' information for a given place name. The closest n matching records can be
 #' requested.
 #'
-#' Geocoding API documentation is available at
+#' Geocoding API documentation is available at:
 #' <https://open-meteo.com/en/docs/geocoding-api>.
 #'
 #' @param location_name Required. The location name to search for via fuzzy

R/marine_forecast.R

@@ -0,0 +1,95 @@
+#' Retrieve marine conditions data from the Open-Meteo API
+#'
+#' @description
+#'
+#' `marine_forecast()` calls the Open-Meteo Marine Forecast API to obtain swell
+#' and wave data for a given location. Limited historical data is also available
+#' via this API.
+#'
+#' Refer to the API documentation at:
+#' <https://open-meteo.com/en/docs/marine-weather-api>
+#'
+#' @details
+#'
+#' You will need to specify at least one variable to retrieve, such as wave
+#' height, that you want data for. These variables are sampled or aggregated at
+#' _hourly_ or _daily_ intervals, and can be supplied as a list to request
+#' multiple variables over the same time period.
+#'
+#' Example _Hourly_ variables include:
+#'
+#' |**Variable**         |**Description**                                      |
+#' |---------------------|-----------------------------------------------------|
+#' |`wave_height`        |Wave height of significant mean waves                |
+#' |`wind_wave_height`   |Wave height of significant wind waves                |
+#' |`swell_wave_height`  |Wave height of significant swell waves               |
+#' |`wind_wave_direction`|Mean direction of wind waves                         |
+#' |`swell_wave_period`  |Mean period between swell waves                      |
+#'
+#' Example _Daily_ variables include:
+#'
+#' |**Variable**                   |**Description**                            |
+#' |-------------------------------|-------------------------------------------|
+#' |`wave_height_max`              |Maximum wave height for mean waves         |
+#' |`wind_wave_direction_dominant` |Dominant wave direction of wind waves      |
+#' |`swell_wave_period_max`        |Maximum wave period of swell waves         |
+#'
+#' Full documentation for the marine API is available at:
+#' <https://open-meteo.com/en/docs/marine-weather-api>
+#'
+#'
+#' @param location Required. The location for which data will be retrieved.
+#'   Supplied as either a `c(latitude,longitude)` WGS84 coordinate pair or a
+#'   place name string (with co-ordinates obtained via [geocode()]).
+#' @param start,end Start and end dates in ISO 8601 (e.g. "2020-12-31"). If no
+#'   dates are supplied, data for the next 7 days will be provided by default.
+#' @param hourly,daily At least one required. A marine weather variable accepted
+#'   by the API, or list thereof. See details below.
+#' @param response_units Supply to convert response units for wave heights. This
+#'   defaults to: `list(length_unit="metric") for meters. Specify "Imperial" for
+#'   feet.`
+#' @param timezone specify timezone for time data as a string, i.e.
+#'   "australia/sydney" (defaults to "auto", the timezone local to the specified
+#'   `location`).
+#'
+#' @return Requested marine conditions data for the given location and time, as
+#'   a tidy tibble.
+#'
+#' @export
+#'
+#' @examples
+#' \donttest{
+#' # Obtain maximum wave heights in Nazare, Portugal, over the next week
+#' marine_forecast("Nazare", daily = "wave_height_max")
+#' }
+marine_forecast <- function(
+    location,
+    start = NULL,
+    end = NULL,
+    hourly = NULL,
+    daily = NULL,
+    response_units = NULL,
+    timezone = "auto") {
+  # validation
+  if (is.null(hourly) && is.null(daily)) {
+    stop("hourly or daily measure not supplied")
+  }
+  if (!is.null(start) && !.is.date(start)) {
+    stop("start and end dates must be in ISO-1806 format")
+  }
+  if (!is.null(end) && !.is.date(end)) {
+    stop("start and end dates must be in ISO-1806 format")
+  }
+
+  base_url <- "https://marine-api.open-meteo.com/v1/marine"
+
+  .query_openmeteo(
+    location,
+    start, end,
+    hourly, daily,
+    response_units,
+    NULL, # no model selection for marine api
+    timezone,
+    base_url
+  )
+}

R/openmeteo.R

@@ -5,19 +5,24 @@
 #'   in a tidy data format. An API key is _not_ required to access the
 #'   Open-Meteo API.
 #'
-#'   Open-Meteo provides several API endpoints. This package
-#'   currently enables access to the _Weather Forecast API_, the _Historical
-#'   Weather API_, and the _Geocoding API_ through the following functions:
+#'   Open-Meteo provides several API endpoints through the following functions:
 #'
+#'   **Core Weather APIs**
 #'   - [weather_forecast()] - retrieve weather forecasts for a location
 #'   - [weather_history()] - retrieve historical weather observations for a
 #'   location
 #'   - [weather_now()] - simple function to return current weather for a
 #'   location
-#'   - [geocode()] - return the co-ordinates and other data for a location name
 #'   - [weather_variables()] - retrieve a shortlist of valid forecast or
 #'   historical weather variables provided
 #'
+#'   **Other APIs**
+#'   - [geocode()] - return the co-ordinates and other data for a location name
+#'   - [climate_forecast()] - return long-range climate modelling for a location
+#'   - [river_discharge()] - return flow volumes for the nearest river
+#'   - [marine_forecast()] - return ocean conditions data for a location
+#'   - [air_quality()] - return air quality data for a location
+#'
 #'   Please review the API documentation at <https://open-meteo.com/> for
 #'   details regarding the data available, its types, units, and other caveats
 #'   and considerations.