Commit bd7ab768 authored by Dorchies David's avatar Dorchies David
Browse files

docs: Aggregate documentation pby API

Closes #16
parent 549017d7
Pipeline #30391 passed with stages
in 2 minutes and 49 seconds
# Generated by roxygen2: do not edit by hand
export(convert_list_to_tibble)
export(doApiQuery)
export(get_available_params)
export(get_hydrometrie_obs_elab)
......
......@@ -3,6 +3,7 @@ hubeau (development version)
New features
------------
* Aggregate documentation by API (#16)
* Add informations in DESCRIPTION file (#12)
* `get_hydrometrie_observations_tr` add an option for handling duplicate entries (#10)
* Deploy pkgdown website on github (#9)
......
......@@ -8,8 +8,10 @@
#' @details The functions `get_[api]_[operation]` call the function `doQueryApi` and convert the response in a convenient format for the user ([data.frame] or [tibble::tibble])
#'
#' @param api a [character] name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs
#' @param operation a [character] name of the operation, see example for available operations in an API
#' @template param_get_common
#' @param operation a [character] name of the endpoint, see example for available endpoints in an API
#' @param params a [list] the list of parameters of the queries and their values in the format `list(ParamName = "Param value", ...)`, use the function [get_available_params] for a list of the available filter parameters for a given operation in an API and see the API documentation for their description
#' @param cfg a [config] object describing the configuration of the APIs. Use the internal package configuration by default
#' configuration
#'
#' @return A [list] with the concatenated results returned by the API.
#' @export
......@@ -110,12 +112,13 @@ doApiQuery <- function(api,
}
#' Convert list provided by the API into a tibble
#' Convert list provided by the APIs into a tibble
#'
#' @param l a [list] provided by the API
#' @param l a [list] provided by the API (See [doApiQuery])
#'
#' @return a [tibble:tibble] with one row by list item and one column by list sub-item
#' @noRd
#' @return a [tibble::tibble] with one row by list item and one column by list sub-item
#'
#' @export
#'
convert_list_to_tibble <- function(l) {
l <-
......
#' Retrieve hydrometric sites from API "Hydrométrie"
#' Retrieve data from API "Hydrométrie"
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
#' @description
#'
#' Available endpoints are:
#'
#' - `get_hydrometrie_obs_elab` retrieves hydrometric elaborate observations (daily/monthly mean flow)
#' - `get_hydrometrie_observations_tr` retrieves hydrometric "real time" observations ()
#' - `get_hydrometrie_sites` retrieves hydrometric sites
#' - `get_hydrometrie_stations` retrieves hydrometric stations
#'
#' See the API documentation of each endpoint for available filter parameters:
#' \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
#'
#' @template param_get_common
#' @param unique_site optional [logical], if set to `FALSE` sites with several different locations produce one row by different location otherwise the first location found is used for fields `code_commune_site`, `libelle_commune`, `code_departement`, `code_region`, `libelle_region`, `libelle_departement`
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by device, year and usage.
#' @export
#'
#' @rdname get_hydrometrie
#' @examples
#' # Retrieve the hydrometric sites in the department of Aube
#' get_hydrometrie_sites(list(code_departement = "10"))
......@@ -15,6 +23,78 @@
#' # The same operation returning 2 rows for the site 'H0203020' which has 2 different locations
#' get_hydrometrie_sites(list(code_departement = "10"), unique_site = FALSE)
#'
#' \dontrun{
#' # This function is currently (2021-12-23) unstable and can be unavailable
#' # (See https://github.com/BRGM/hubeau/issues/85)
#' # Retrieve the hydrometric stations in the department of Aube
#' get_hydrometrie_stations(list(code_departement = "10"))
#' }
#'
#' # Which parameters are available for endpoint "obs_elab" of API "hydrometrie"?
#' get_available_params("hydrometrie", "obs_elab")
#'
#' # Retrieve the hydrometric monthly mean flow at site 'H0203020'
#' get_hydrometrie_obs_elab(list(code_entite = "H0203020", grandeur_hydro_elab = "QmM"))
#'
#' # Retrieve the hydrometric daily mean flow at site 'H0203020' of the last 30 days
#' get_hydrometrie_obs_elab(
#' list(code_entite = "H0203020",
#' date_debut_obs_elab = format(Sys.Date() -30, "%Y-%m-%d"),
#' grandeur_hydro_elab = "QmJ"))
#'
get_hydrometrie_obs_elab <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(
api = "hydrometrie",
operation = "obs_elab",
params = params,
cfg = cfg
)
convert_list_to_tibble(l)
}
#' @param entities 1-length [character] string filtering the rows of the returned value, possible values are: "station" for filtering on station rows, "site" for filtering on site rows, "both" for keeping all the rows
#' @rdname get_hydrometrie
#' @export
get_hydrometrie_observations_tr <- function(params,
entities = "station",
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
# Checks
if(!entities %in% c("station", "site", "both")) {
stop("Argument 'entities' must be one of these values: 'station', 'site', 'both'")
}
l <- doApiQuery(
api = "hydrometrie",
operation = "observations_tr",
params = params,
cfg = cfg
)
if(!is.null(l)) {
l <- lapply(l, function(x) {
x$geometry <- NULL
if (entities == "station") {
if (is.null(x$code_station)) {
return(NULL)
}
} else if (entities == "site") {
if (!is.null(x$code_station)) {
return(NULL)
}
}
return(x)
})
l[sapply(l, is.null)] <- NULL
l <- convert_list_to_tibble(l)
}
return(l)
}
#' @param unique_site optional [logical], if set to `FALSE` sites with several different locations produce one row by different location otherwise the first location found is used for fields `code_commune_site`, `libelle_commune`, `code_departement`, `code_region`, `libelle_region`, `libelle_departement`
#' @rdname get_hydrometrie
#' @export
get_hydrometrie_sites <- function(params,
unique_site = TRUE,
cfg = config::get(file = system.file("config.yml",
......@@ -61,3 +141,22 @@ get_hydrometrie_sites <- function(params,
})
convert_list_to_tibble(l)
}
#' @param code_sandre_reseau_station optional [logical] indicating if `code_sandre_reseau_station` field is included in the result; if so, one line is added by item and other fields are repeated
#' @rdname get_hydrometrie
#' @export
get_hydrometrie_stations <- function(params, code_sandre_reseau_station = FALSE, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "hydrometrie",
operation = "stations",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
if (!code_sandre_reseau_station) {
x$code_sandre_reseau_station <- NULL
}
x$geometry <- NULL
x
})
convert_list_to_tibble(l)
}
#' Retrieve hydrometric elaborate observations from API "Hydrométrie"
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie#operations-hydrometrie-observationsElaborees}
#'
#' @template param_get_common
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
#' @export
#'
#' @examples
#' # Retrieve the hydrometric last real time observed discharge at station 'H020302002'
#' get_hydrometrie_obs_elab(list(code_entite = "H0203020", grandeur_hydro_elab = "QmM"))
get_hydrometrie_obs_elab <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(
api = "hydrometrie",
operation = "obs_elab",
params = params,
cfg = cfg
)
convert_list_to_tibble(l)
}
#' Retrieve hydrometric "real time" observations from API "Hydrométrie"
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
#'
#' @template param_get_common
#' @param entities 1-[character] string filtering the rows of the returned value, possible values are: "station" for filtering on station rows, "site" for filtering on site rows, "both" for keeping all the rows
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
#' If the query returns no records then the returned value is [NULL].
#'
#' @export
#'
#' @examples
#' # Retrieve the hydrometric last real time observed discharge at station 'H020302002'
#' get_hydrometrie_observations_tr(list(code_entite = "H0203020", grandeur_hydro = "Q"))
#'
get_hydrometrie_observations_tr <- function(params,
entities = "station",
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
# Checks
if(!entities %in% c("station", "site", "both")) {
stop("Argument 'entities' must be one of these values: 'station', 'site', 'both'")
}
l <- doApiQuery(
api = "hydrometrie",
operation = "observations_tr",
params = params,
cfg = cfg
)
if(!is.null(l)) {
l <- lapply(l, function(x) {
x$geometry <- NULL
if (entities == "station") {
if (is.null(x$code_station)) {
return(NULL)
}
} else if (entities == "site") {
if (!is.null(x$code_station)) {
return(NULL)
}
}
return(x)
})
l[sapply(l, is.null)] <- NULL
l <- convert_list_to_tibble(l)
}
return(l)
}
#' Retrieve hydrometric stations from API "Hydrométrie"
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
#'
#' @template param_get_common
#' @param code_sandre_reseau_station optional [logical] indicating if `code_sandre_reseau_station` field is included in the result; if so, one line is added by item and other fields are repeated
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by station.
#' @export
#'
#' @examples
#' \dontrun{
#' # This function is temporarily unavailable because of https://github.com/BRGM/hubeau/issues/85
#'
#' # Retrieve the hydrometric stations in the department of Aube
#' get_hydrometrie_stations(list(code_departement = "10"))
#' }
get_hydrometrie_stations <- function(params, code_sandre_reseau_station = FALSE, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "hydrometrie",
operation = "stations",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
if (!code_sandre_reseau_station) {
x$code_sandre_reseau_station <- NULL
}
x$geometry <- NULL
x
})
convert_list_to_tibble(l)
}
#' Retrieve performance indicators from drinking water supply and sanitation services at commune level
#'
#' @description
#' Available endpoints are:
#'
#' -
#'
#' See [get_available_params] and the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
#'
#' @template param_get_common
#'
#' @details
#' `get_indicateurs_services_communes` returns a [tibble::tibble] with one row by commune, by service and by year and the following columns:
#'
#' - "code_commune_insee": [character] identifier of the commune
#' - "nom_commune": [character] name of the commune
#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
#' - "annee": [integer] year of the data
#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
#'
#' a [tibble::tibble] with one row by commune, by service and by year and the following columns:
#'
#' - "code_commune_insee": [character] identifier of the commune
#' - "nom_commune": [character] name of the commune
#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
#' - "annee": [integer] year of the data
#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
#'
#' `get_indicateurs_services_indicateurs` returns a [tibble::tibble] with one row by service and by year and the following columns:
#'
#' - "code_service": [character] identifier of the service
#' - "nom_service": [character] name of the service
#' - "numero_siren ": [character] SIREN identifier of the service
#' - "type_collectivite": [character] kind of collectivity
#' - "mode_gestion": [character] management mechanism of the service
#' - "annee": [integer] year of the data
#' - "indicateur": value of the indicator
#' - "uri_indicateur": the link to the indicator documentation
#'
#' `get_indicateurs_services_services` returns a [tibble::tibble] with one row by commune, by service and by year and the following columns:
#'
#' - "code_service": [character] identifier of the service
#' - "nom_service": [character] name of the service
#' - "code_commune_insee": [character] identifier of the commune
#' - "nom_commune": [character] name of the commune
#' - "numero_siren ": [character] SIREN identifier of the service
#' - "type_collectivite": [character] kind of collectivity
#' - "mode_gestion": [character] management mechanism of the service
#' - "annee": [integer] year of the data
#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
#'
#' @export
#' @rdname get_indicateurs_services
#'
#' @examples
#' # Retrieve performance indicator time series in the commune of Romilly-sur-Seine
#' get_indicateurs_services_communes(list(code_commune = "10323"))
#'
#' # Retrieve the drinking water withdrawal indicators of the year 2012 for all services
#' get_indicateurs_services_indicateurs(list(code_indicateur = "D102.0", annee = "2012"))
#'
#' # Retrieve performance indicator time series of Romilly-sur-Seine with service details
#' get_indicateurs_services_services(list(code_commune = "10323"))
#'
get_indicateurs_services_communes <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "communes",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
x <- c(x, x$indicateurs)
x$indicateurs <- NULL
x
})
convert_list_to_tibble(l)
}
#' @export
#' @rdname get_indicateurs_services
get_indicateurs_services_indicateurs <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "indicateurs",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
x$codes_commune <- NULL
x$noms_commune <- NULL
x
})
convert_list_to_tibble(l)
}
#' @export
#' @rdname get_indicateurs_services
get_indicateurs_services_services <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "services",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
x <- c(x, x$indicateurs)
x$indicateurs <- NULL
x
})
convert_list_to_tibble(l)
}
#' Retrieve performance indicators from drinking water supply and sanitation services at commune level
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
#'
#' @template param_get_common
#'
#' @return a [tibble::tibble] with one row by commune, by service and by year and the following columns:
#'
#' - "code_commune_insee": [character] identifier of the commune
#' - "nom_commune": [character] name of the commune
#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
#' - "annee": [integer] year of the data
#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
#'
#' @export
#'
#' @examples
#' # Retrieve performance indicator time series of the services in Romilly-sur-Seine
#' get_indicateurs_services_communes(list(code_commune = "10323"))
#'
get_indicateurs_services_communes <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "communes",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
x <- c(x, x$indicateurs)
x$indicateurs <- NULL
x
})
convert_list_to_tibble(l)
}
#' Retrieve performance indicators from drinking water supply and sanitation services at commune level
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
#'
#' @template param_get_common
#'
#' @return a [tibble::tibble] with one row by commune, by service and by year and the following columns:
#'
#' - "code_commune_insee": [character] identifier of the commune
#' - "nom_commune": [character] name of the commune
#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
#' - "annee": [integer] year of the data
#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
#'
#' @export
#'
#' @examples
#' # Retrieve the withdrawal time series of the devices located in Romilly-sur-Seine
#' get_indicateurs_services_indicateurs(list(code_indicateur = "D102.0", annee = "2012"))
#'
get_indicateurs_services_indicateurs <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "indicateurs",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
x$codes_commune <- NULL
x$noms_commune <- NULL
x
})
convert_list_to_tibble(l)
}
#' Retrieve performance indicators from drinking water supply and sanitation services at commune level
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
#'
#' @template param_get_common
#'
#' @return a [tibble::tibble] with one row by commune, by service and by year and the following columns:
#'
#' - "code_service": [character] identifier of the service
#' - "nom_service": [character] name of the service
#' - "code_commune_insee": [character] identifier of the commune
#' - "nom_commune": [character] name of the commune
#' - "numero_siren ": [character] SIREN identifier of the service
#' - "type_collectivite": [character] kind of collectivity
#' - "mode_gestion": [character] management mechanism of the service
#' - "annee": [integer] year of the data
#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
#'
#' @export
#'
#' @examples
#' # Retrieve performance indicator time series of the services in Romilly-sur-Seine
#' get_indicateurs_services_services(list(code_commune = "10323"))
#'
get_indicateurs_services_services <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
operation = "services",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
x <- c(x, x$indicateurs)
x$indicateurs <- NULL
x
})
convert_list_to_tibble(l)
}
#' Retrieve piezometric archived time series from API "Piézométrie"
#' Retrieve data from API "Piézométrie"
#'
#' @description
#' The available endpoints are:
#'
#' - `get_niveaux_nappes_stations` retrieves list of piezometric stations
#' - `get_nappes_chroniques` retrieves piezometric archived time series
#' - `get_nappes_chroniques_tr` retrieves piezometric "real time" data
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-piezometrie}
#'
#' @template param_get_common
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
#' @rdname get_niveaux_nappes
#' @export
#'
#' @examples
#' # Retrieve the hydrometric stations in the department of Aube
#' get_niveaux_nappes_stations(list(code_departement = "10"))
#'
#' # Retrieve the archived observed piezometric level at station '07548X0009/F' (old BSS identifier)
#' # for the year 2020
#' df <- get_niveaux_nappes_chroniques(list(code_bss = "07548X0009/F",
......@@ -17,6 +27,28 @@
#' # Plot the water elevation (NGF)
#' plot(as.POSIXct(df$date_mesure), df$niveau_nappe_eau, type = "l")
#'
#' # For retrieving the last real time observed piezometric level
#' # at station 'BSS001VZGZ' (new BSS identifier)
#' df <- get_niveaux_nappes_chroniques_tr(list(bss_id = "BSS001VZGZ"))
#'
#' # Plot the water elevation (NGF)
#' plot(as.POSIXct(df$date_mesure), df$niveau_eau_ngf, type = "l")
#'
get_niveaux_nappes_stations <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "niveaux_nappes",
operation = "stations",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
x$geometry <- NULL
x
})
convert_list_to_tibble(l)
}
#' @rdname get_niveaux_nappes
#' @export
get_niveaux_nappes_chroniques <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
......@@ -28,3 +60,17 @@ get_niveaux_nappes_chroniques <- function(params,
)
convert_list_to_tibble(l)
}
#' @rdname get_niveaux_nappes
#' @export
get_niveaux_nappes_chroniques_tr <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(
api = "niveaux_nappes",
operation = "chroniques_tr",
params = params,
cfg = cfg
)
convert_list_to_tibble(l)
}
#' Retrieve piezometric "real time" chroniques from API "Piézométrie"
#'
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-piezometrie}
#'
#' @template param_get_common
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
#' @export
#'
#' @examples
#' # For retrieving the last real time observed piezometric level
#' # at station 'BSS001VZGZ' (new BSS identifier)
#' df <- get_niveaux_nappes_chroniques_tr(list(bss_id = "BSS001VZGZ"))
#'
#' # Plot the water elevation (NGF)
#' plot(as.POSIXct(df$date_mesure), df$niveau_eau_ngf, type = "l")
get_niveaux_nappes_chroniques_tr <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(