,
Willem Maetens [ctb],
Peter Desmet [ctb] ,
Research Institute for Nature and Forest (INBO) [cph]
(https://www.vlaanderen.be/inbo/en-gb/),
LifeWatch Belgium [fnd] (https://lifewatch.be)| Title: | Download Time Series Data from Waterinfo.be |
|---|---|
| Description: | wateRinfo facilitates access to waterinfo.be (<https://www.waterinfo.be>), a website managed by the Flanders Environment Agency (VMM) and Flanders Hydraulics Research. The website provides access to real-time water and weather related environmental variables for Flanders (Belgium), such as rainfall, air pressure, discharge, and water level. The package provides functions to search for stations and variables, and download time series. |
| Authors: | Stijn Van Hoey [aut, cre] ,
Willem Maetens [ctb],
Peter Desmet [ctb] ,
Research Institute for Nature and Forest (INBO) [cph]
(https://www.vlaanderen.be/inbo/en-gb/),
LifeWatch Belgium [fnd] (https://lifewatch.be) |
| Maintainer: | Stijn Van Hoey <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.3.0.9065 |
| Built: | 2024-08-29 23:16:13 UTC |
| Source: | https://github.com/ropensci/wateRinfo |
A dataset compiled by downloading 1 day of air pressure data for the available stations of Waterinfo.be
air_pressureair_pressure
A data frame with 710 rows and 13 variables:
identifier of the downloaded time serie
datetime
measured value of the variable
Quality code of the measurement
latitude coordinate
longitude coordinate
identifier of the measurement station
short code name of the measurement station
full name of the measurement station
parameter name on station level
parameter type name
unit of the variable
provider of the time series value
Check if the format of the period is conform the specifications of VMM
check_period_format(period_string)check_period_format(period_string)
period_string |
input string according to format required by waterinfo: The period string is provided as P#Y#M#DT#H#M#S, with P defines 'Period', each # is an integer value and the codes define the number of... Y - years M - months D - days T required if information about sub-day resolution is present H - hours D - days M - minutes S - seconds Instead of D (days), the usage of W - weeks is possible as well Examples of valid period strings: P3D, P1Y, P1DT12H, PT6H, P1Y6M3DT4H20M30S. |
str period string itself if valid
check_period_format("P2DT6H") # period of 2 days and 6 hours check_period_format("P3D") # period of 3 dayscheck_period_format("P2DT6H") # period of 2 days and 6 hours check_period_format("P3D") # period of 3 days
For a given timeseriesgroup (variable), provide a list of measurement
stations providing data. An overview of the variables is provided by the
function supported_variables.
get_stations(variable_name = NULL, frequency = "15min", token = NULL)get_stations(variable_name = NULL, frequency = "15min", token = NULL)
variable_name |
char valid nam of available variable as timeseriesgroup |
frequency |
char valid frequency for the given variable, for most variables, the 15min frequency is available |
token |
token to use with the call (optional, can be retrieved via
|
A data.frame with 10 variables:
Unique timeseries identifier to access time series data corresponding to a combination of the station, measured variable and frequency.
Latitude coordinates of the station (WGS84)
Longitude coordinates of the station (WGS84)
Identifier of the station as used in the waterinfo backend
Station ID as provided on the waterinfo.be website.
Official name of the measurement station.
Station specific variable description.
Measured variable description.
Unit of the variable.
Data provider of the time series data.
The URL of the specific request is provided as a comment attribute to the
returned data.frame. Use comment(df) to get the request URL.
For the moment, this only works for measurement stations of VMM (meetnet 1), and stations from other measurement data sources are not included in the list
data.frame with an overview of the available stations for the requested variable
supported_variables
get_stations('irradiance') get_stations('soil_saturation')get_stations('irradiance') get_stations('soil_saturation')
Using the ts_id codes and by providing a given date period, download the corresponding time series from the waterinfo.be website
get_timeseries_tsid( ts_id, period = NULL, from = NULL, to = NULL, datasource = 1, token = NULL )get_timeseries_tsid( ts_id, period = NULL, from = NULL, to = NULL, datasource = 1, token = NULL )
ts_id |
waterinfo.be database ts_id, defining a timeserie variable and frequency it is defined. |
period |
input string according to format required by waterinfo: De period string is provided as P#Y#M#DT#H#M#S, with P defines 'Period', each # is an integer value and the codes define the number of... Y - years M - months D - days T required if information about sub-day resolution is present H - hours D - days M - minutes S - seconds Instead of D (days), the usage of W - weeks is possible as well Examples of valid period strings: P3D, P1Y, P1DT12H, PT6H, P1Y6M3DT4H20M30S. |
from |
date of datestring as start of the time series |
to |
date of datestring as end of the time series |
datasource |
int [0-4] defines the 'meetnet' of which the measurement station is part of. VMM based stations are net '1', MOW-HIC is net '2' |
token |
token to use with the call (optional, can be retrieved via
|
A data.frame with 3 variables:
Datetime of the measurement.
Measured value.
Quality code of the measurement, dependent on the data source used:
VMM Quality Code Interpretation (datasource 1)
10/110 - Excellent
30/100/130 - Good
50/150 - Moderate
70/170 - Poor
80/180 - Estimated
90/190 - Suspect
220 - Default
-1 - Missing
HIC Quality Code Interpretation (datasource 2)
40 - Good
80 - Estimated
120 - Suspect
200 - Unchecked
60 - Complete
160 - Incomplete
-1 - Missing
Aggregated timeseries
40 - Good
100 - Estimated
120 - Suspect
200 - Unchecked
-1 - Missing
The URL of the specific request is provided as a comment attribute to the
returned data.frame. Use comment(df) to get the request URL.
data.frame with the timestamps, values and quality code
get_timeseries_tsid("35055042", from = "2017-01-01", to = "2017-01-02") get_timeseries_tsid("5156042", period = "P3D") get_timeseries_tsid("55419010", from = "2017-06-01", to = "2017-06-03", datasource = 4)get_timeseries_tsid("35055042", from = "2017-01-01", to = "2017-01-02") get_timeseries_tsid("5156042", period = "P3D") get_timeseries_tsid("55419010", from = "2017-06-01", to = "2017-06-03", datasource = 4)
Retrieve a fresh waterinfo token. A token is not required to get started, see Details section for more information.
get_token( client = NULL, client_id = NULL, client_secret = NULL, token_url = "http://download.waterinfo.be/kiwis-auth/token" ) is.expired(token) expires.in(token)get_token( client = NULL, client_id = NULL, client_secret = NULL, token_url = "http://download.waterinfo.be/kiwis-auth/token" ) is.expired(token) expires.in(token)
client |
base64 encoded client containing the client id and client secret, seperated by : |
client_id |
client id string |
client_secret |
client secret string |
token_url |
url to get the token from |
token |
a token object |
Notice you do not need to get a token right away to download data. For limited and irregular downloads, a token will not be required. The amount of data downloaded from waterinfo.be is limited via a credit system. When you require more extended data requests, request a download token.
Either client or client_id and client_secret need to be passed as arguments. If provided, client is always used. Tokens remain valid for 24 hours, after which a fresh one must be acquired. To limit load on the server, token objects should be reused as much as possible until expiration in stead of creating fresh ones for each call.
The client_id and client_secret provided in the examples are for test purposes, get your very own client via [email protected].
An object of class token containing the token string with the token_url, token type and moment of expiration as attributes.
# Get token via client_id and client_secret client_id <- '32dceece-826c-4b98-9c2d-b16978f0ca6a' client_secret <- '4ada871a-9528-4b4d-bfd5-b570ce8f4d2d' my_token <- get_token(client_id = client_id,client_secret = client_secret) print(my_token) # get token via client client <- paste0('MzJkY2VlY2UtODI2Yy00Yjk4LTljMmQtYjE2OTc4ZjBjYTZhOjRhZGE4', 'NzFhLTk1MjgtNGI0ZC1iZmQ1LWI1NzBjZThmNGQyZA==') my_token <- get_token(client = client) print(my_token) is.expired(my_token) expires.in # Use the token when requesting for data (i.e. get_* functions), e.g. get_stations(variable_name = "verdamping_monteith", token = my_token)# Get token via client_id and client_secret client_id <- '32dceece-826c-4b98-9c2d-b16978f0ca6a' client_secret <- '4ada871a-9528-4b4d-bfd5-b570ce8f4d2d' my_token <- get_token(client_id = client_id,client_secret = client_secret) print(my_token) # get token via client client <- paste0('MzJkY2VlY2UtODI2Yy00Yjk4LTljMmQtYjE2OTc4ZjBjYTZhOjRhZGE4', 'NzFhLTk1MjgtNGI0ZC1iZmQ1LWI1NzBjZThmNGQyZA==') my_token <- get_token(client = client) print(my_token) is.expired(my_token) expires.in # Use the token when requesting for data (i.e. get_* functions), e.g. get_stations(variable_name = "verdamping_monteith", token = my_token)
Get list of variables for a given station
get_variables(station_no, token = NULL)get_variables(station_no, token = NULL)
station_no |
'stations-nummer' as it appears on the download page of waterinfo.be |
token |
token to use with the call (optional, can be retrieved via
|
A data.frame with 6 variables:
Official name of the measurement station.
Station ID as provided on the waterinfo.be website.
Unique timeseries identifier to access time series data corresponding to a combination of the station, measured variable and frequency.
Timeseries identifier description name as provided by 'waterinfo.be'.
Measured variable description.
Station specific variable description.
The URL of the specific request is provided as a comment attribute to the
returned data.frame. Use comment(df) to get the request URL.
data.frame with the station_name, station_no, ts_id, ts_name and parametertype_name for each of the variables for this station.
variables_overpelt <- get_variables("ME11_002")variables_overpelt <- get_variables("ME11_002")
Check if variable is supported by VMM ts group id
is_supported_variable(variable_name)is_supported_variable(variable_name)
variable_name |
char |
Raise error when variable is not supported directly, otherwise NULL
is_supported_variable("wind_speed")is_supported_variable("wind_speed")
A dataset compiled by downloading 1 day of soil moisture data for the Liedekerke measurement station of Waterinfo.be
liedekerkeliedekerke
A data frame with 23,816 rows and 9 variables:
identifier of the downloaded time serie
datetime
measured value of the variable
Quality code of the measurement
full name of the measurement station
short code name of the measurement station
type/frequency of the time serie
parameter type name
parameter name on station level
Custom print function of the API request response
## S3 method for class 'waterinfo_api' print(x, ...)## S3 method for class 'waterinfo_api' print(x, ...)
x |
waterinfo_api |
... |
args further arguments passed to or from other methods. |
Using the 'stations-nummer' as provided on waterinfo.be, this function tries to identify the datasource to use for the particular variable
resolve_datasource(station_no)resolve_datasource(station_no)
station_no |
'stations-nummer' as it appears on the download page of waterinfo.be |
Notice that VMM did not provide this in the official documentation, but this has just been derived by checking the API response as such. A more automated and less hard-coded approach would be beneficial, but this data is not available at the moment.
integer 1 for VMM, 4 for other 'meetnetten' (HIC,...)
resolve_datasource('akl03e-1066') resolve_datasource('K07_OM421')resolve_datasource('akl03e-1066') resolve_datasource('K07_OM421')
Translate the usage of available variables to the corresponding timeseriesgroupID, based on the provided lookup table from VMM
resolve_timeseriesgroupid(variable_name, frequency = "15min")resolve_timeseriesgroupid(variable_name, frequency = "15min")
variable_name |
valid variable name, supported by VMM API |
frequency |
valid frequency for the given variable |
Remark that this information is NOT based on a query, but on information provided by the package itself to make variable names more readable
The lookup table is provided as external data of the package, see inst/extdata
list containing the timeseriesgroup_id of the variable
frequency combination
resolve_timeseriesgroupid("rainfall", "15min")resolve_timeseriesgroupid("rainfall", "15min")
Provide list of VMM supported frequencies for a given timeseriesgroupID in either dutch or english
supported_frequencies(variable_name)supported_frequencies(variable_name)
variable_name |
char name of a valid variable in either dutch or english |
supported_frequencies('rainfall')supported_frequencies('rainfall')
Provide list of VMM supported variables in the timeseriesgroupID in either dutch or english
supported_variables(language = "nl")supported_variables(language = "nl")
language |
char |
data.frame containing the variable names in either english or dutch
# Request supported variables in Dutch supported_variables("nl") # Request supported variables in English supported_variables("en")# Request supported variables in Dutch supported_variables("nl") # Request supported variables in English supported_variables("en")