frostr (version 0.2.0)

get_observations: Get weather observations from the "observation" resource in the Frost API

Description

get_observations() retrieves historical weather data from the Frost API. This is the core resource for retrieving actual observation data from MET Norway's data storage systems. The function requires input for client_id, sources, reference_time, and elements. The other function arguments are optional, and default to NULL, which means that the response from the API is not filtered on these parameters.

Usage

get_observations(client_id,
                 sources,
                 reference_time,
                 elements,
                 maxage = NULL,
                 limit = NULL,
                 time_offsets = NULL,
                 time_resolutions = NULL,
                 time_series_ids = NULL,
                 performance_categories = NULL,
                 exposure_categories = NULL,
                 qualities = NULL,
                 levels = NULL,
                 include_extra = NULL,
                 fields = NULL,
                 return_response = FALSE)

Arguments

client_id

A string. The client ID to use to send requests to the Frost API.

sources

A character vector. The station IDs of the data sources to get observations for. For example, "SN18700" is the station ID for "Blindern". The full list of station IDs can be retrieved with get_sources().

reference_time

A string. The time range to get observations for in either extended ISO-8601 format or the single word "latest".

elements

A character vector. The elements to get observations for. The full list of elements can be retrieved with the get_elements().

maxage

A string. The maximum observation age as an ISO-8601 period, e.g. "P1D". This parameter is only applicable when reference_time = "latest". Defaults to "PT3H".

limit

A string or a positive integer. The maximum number of observation times to be returned for each combination of source and element, counting from the most recent time. This parameter is only applicable when reference_time = "latest". Set limit = "all" to get all available times or a positive integer. Defaults to 1.

time_offsets

A character vector. The time offsets to get observations for provided as a vector of ISO-8601 periods, e.g. c("PT6H", "PT18H").

time_resolutions

A character vector. The time resolutions to get observations for provided as a vector of ISO-8601 periods e.g. c("PT6H", "PT18H").

time_series_ids

A numeric vector. The internal time series IDs to get observations for as a vector of integers, e.g. c(0, 1).

performance_categories

A character vector. The performance categories to get observations for as a vector of letters, e.g. c("A", "C").

exposure_categories

A numeric vector. The exposure categories to get observations for as a vector of integers, e.g. c(1, 2).

qualities

A numeric vector. The qualities to get observations for as a vector of integers, e.g. c(1, 2).

levels

A numeric vector. The sensor levels to get observations for as a vector of integers, e.g. c(1, 2, 10, 20).

include_extra

An integer. If this parameter is set to 1, and extra data is available, then this data is included in the response. Extra data currently consists of the original observation value and the 16-character control info.

fields

A character vector. Fields to include in the response (i.e. output). If this parameter is specified, then only these fields are returned in the response. If not specified, then all fields will be returned in the response.

return_response

A logical. If set to TRUE, then the function returns the response from the GET request. If set to FALSE (default), then the function returns a tibble (data frame) of the content in the response.

Value

The function returns either a data frame of historical weather observations, or the response of the GET request, depending on the boolean value set for return_response.

Examples

# NOT RUN {
frost_client_id <- "<YOUR FROST CLIENT ID>"

# Get daily data for temperature, rain, and wind speed for 2018
sources <- "SN18700"
reference_time <- "2018-01-01/2018-12-31"
elements <- c("mean(air_temperature P1D)",
              "sum(precipitation_amount P1D)",
              "mean(wind_speed P1D)")

observations_df <- get_observations(client_id      = frost_client_id,
                                    sources        = sources,
                                    reference_time = reference_time,
                                    elements       = elements)
# }
# NOT RUN {
# }