diff --git a/NAMESPACE b/NAMESPACE
index c8bd8d5e87878711db092b0fcacb813d1b9ec7fa..da6adecfc21c18a78386566f0e02b24de81e62d8 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,4 +1,8 @@
# Generated by roxygen2: do not edit by hand
-export(get_prelevements_chronique)
-export(get_prelevements_prelevement)
+export(doApiQuery)
+export(get_available_params)
+export(get_indicateurs_services_communes)
+export(get_indicateurs_services_indicateurs)
+export(get_prelevements_chroniques)
+export(get_prelevements_points_prelevement)
diff --git a/R/doApiQuery.R b/R/doApiQuery.R
index 3b13992ba075e21613d37a63cc3b94cd4affc086..2b61f459588afa5912b1e3d83769611c312f0ded 100644
--- a/R/doApiQuery.R
+++ b/R/doApiQuery.R
@@ -1,8 +1,60 @@
-doApiQuery <- function(url_path,
+#' Main internal functions for querying the Hub'eau APIs
+#'
+#' The function `doQueryApi` is called by all the function querying the APIs and return the raw data sent by the API.
+#' Pagination of the queries is handled automatically and the returned [list] is the concatenation of all the results sent by the API.
+#'
+#' The function `get_available_params` returns the list of available query parameters for a given operation in an API.
+#'
+#' @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
+#' @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 parameters for a given operation in an API
+#' @template param_get_common
+#'
+#' @return A [list] with the concatenated results returned by the API.
+#' @export
+#' @rdname doApiQuery
+#'
+#' @examples
+#' # To get the available APIs in the package
+#' cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
+#' names(cfg$apis)
+#'
+#' # To get the available operation in an API
+#' names(cfg$apis[["prelevements"]]$operations)
+#'
+#' # To get available parameters in operation "chroniques" of the API "prelevements"
+#' get_available_params(api = "prelevements", operation = "chroniques")
+#'
+#' # To query the operation "chroniques" of the API "prelevements"
+#' # on all devices in the commune of Romilly-sur-Seine in 2018
+#' doApiQuery(api = "prelevements",
+#' operation = "chroniques",
+#' params = list(code_commune_insee = "10323", annee = "2018"))
+doApiQuery <- function(api,
+ operation,
params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))) {
- query <- file.path(cfg$api$url, url_path)
+ availableParams <- get_available_params(api, operation, cfg)
+
+ query <-
+ file.path(cfg$api_url, cfg$apis[[api]]$path, cfg$apis[[api]]$operations[[operation]]$path)
for (paramName in names(params)) {
+ if (!paramName %in% cfg$apis[[api]]$operations[[operation]]$fields) {
+ stop(
+ sprintf(
+ "The parameter '%s' is not available for this query. ",
+ paramName
+ ),
+ "\n",
+ sprintf(
+ "Run `hubeau::get_available_params(\"%s\", \"%s\")` to get available parameters.",
+ api,
+ operation
+ )
+ )
+ }
if (!is.null(params[[paramName]])) {
query <- urltools::param_set(query,
key = paramName,
@@ -10,15 +62,37 @@ doApiQuery <- function(url_path,
}
}
data <- list()
+
repeat {
resp <- httr::GET(query)
- if (resp$status_code >= 300) {
- stop("Error", resp$status_code, " on query: ", query)
+ if (resp$status_code >= 400) {
+ l <- NULL
+ try(l <- httr::content(resp, "parsed"), TRUE)
+ if (is.null(l$field_errors)) {
+ stop("Error ", resp$status_code, " on query: ", query)
+ } else {
+ field_errors <-
+ sapply(l$field_errors, function(x) {
+ paste(x$field, x$message)
+ })
+ stop(
+ "Error ",
+ resp$status_code,
+ " on query: ",
+ query,
+ "\n Error on parameters:\n",
+ paste(field_errors, collapse = "\n")
+ )
+ }
} else {
l <- httr::content(resp, "parsed")
data <- c(data, l$data)
if (resp$status_code == 206) {
query <- l$`next`
+ if (is.null(query)) {
+ # Bug https://github.com/BRGM/hubeau/issues/72
+ break
+ }
}
if (resp$status_code == 200) {
break
diff --git a/R/get_available_params.R b/R/get_available_params.R
new file mode 100644
index 0000000000000000000000000000000000000000..333e4f34d0ee0bf18cc07aeca7cb817f549aead3
--- /dev/null
+++ b/R/get_available_params.R
@@ -0,0 +1,15 @@
+#' @rdname doApiQuery
+#' @export
+#'
+get_available_params <- function(api,
+ operation,
+ cfg = config::get(file = system.file("config.yml",
+ package = "hubeau"))) {
+ if (is.null(cfg$apis[[api]])) {
+ stop("The API '", api, "' is not available on Hub'eau, or is not implemented in the package")
+ }
+ if (is.null(cfg$apis[[api]]$operations[[operation]])) {
+ stop("The operation '", operation, "' is not available for this API, or is not implemented in the package")
+ }
+ cfg$apis[[api]]$operations[[operation]]$fields
+}
diff --git a/R/get_indicateurs_services_communes.R b/R/get_indicateurs_services_communes.R
new file mode 100644
index 0000000000000000000000000000000000000000..7a857ac18bd5262098280b9a877f8a7b3fba54e2
--- /dev/null
+++ b/R/get_indicateurs_services_communes.R
@@ -0,0 +1,38 @@
+#' 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}
+#'
+#' @param params [list] where the keys are the names of the filtered parameters and the values are the values of the filters. See the API documentation for the complete list of available filter parameters
+#' @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
+#' # For retrieving 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
+ })
+ l <- lapply(l, function(row) {lapply(row, function(cell) { if(is.null(unlist(cell))) NA else unlist(cell) })})
+ return(purrr::map_df(l, tibble::as_tibble))
+}
diff --git a/R/get_indicateurs_services_indicateurs.R b/R/get_indicateurs_services_indicateurs.R
new file mode 100644
index 0000000000000000000000000000000000000000..35a54f6fa770203d1187499958a83204db8fcd1f
--- /dev/null
+++ b/R/get_indicateurs_services_indicateurs.R
@@ -0,0 +1,38 @@
+#' 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}
+#'
+#' @param params [list] where the keys are the names of the filtered parameters and the values are the values of the filters. See the API documentation for the complete list of available filter parameters
+#' @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
+#' # For retrieving 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)
+
+ li <- lapply(l, function(x) {
+ x$codes_commune <- NULL
+ x$noms_commune <- NULL
+ x
+ })
+ li <- lapply(li, function(row) {lapply(row, function(cell) { if(is.null(unlist(cell))) NA else unlist(cell) })})
+ df <- purrr::map_df(li, tibble::as_tibble)
+ return()
+}
diff --git a/R/get_prelevements_chronique.R b/R/get_prelevements_chroniques.R
similarity index 73%
rename from R/get_prelevements_chronique.R
rename to R/get_prelevements_chroniques.R
index 640943a025686fb81c660d8ce0d56a5e5dd505bb..227a4d0cd9b5fa95a7226e424791966d3d6a4ba4 100644
--- a/R/get_prelevements_chronique.R
+++ b/R/get_prelevements_chroniques.R
@@ -3,19 +3,21 @@
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/chronique}
#'
#' @param params [list] where the keys are the names of the filtered parameters and the values are the values of the filters. See the API documentation for the complete list of available filter parameters
-#' @param cfg a [config] object Configuration of the communication. Use by default the internal package
-#' configuration
+#' @template param_get_common
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by device, year and usage.
#' @export
#'
#' @examples
#' # For retrieving the withdrawal time series of the devices located in Romilly-sur-Seine
-#' get_prelevements_chronique(list(code_commune_insee = "10323"))
+#' get_prelevements_chroniques(list(code_commune_insee = "10323"))
#'
-get_prelevements_chronique <- function(params, cfg = config::get(file = system.file("config.yml",
+get_prelevements_chroniques <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
- l <- doApiQuery(cfg$api_prelevements$chronique, params)
+ l <- doApiQuery(api = "prelevements",
+ operation = "chroniques",
+ params = params,
+ cfg = cfg)
l <- lapply(l, function(x) {
x$geometry <- NULL
x
diff --git a/R/get_prelevements_prelevement.R b/R/get_prelevements_points_prelevement.R
similarity index 70%
rename from R/get_prelevements_prelevement.R
rename to R/get_prelevements_points_prelevement.R
index 8b274dbab4662fff0b0577df3249c834e6f293b1..694885011bcd71fdfe26d80fea719db49491438a 100644
--- a/R/get_prelevements_prelevement.R
+++ b/R/get_prelevements_points_prelevement.R
@@ -3,19 +3,22 @@
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/prelevement}
#'
#' @param params [list] where the keys are the names of the filtered parameters and the values are the values of the filters. See the API documentation for the complete list of available filter parameters
-#' @param cfg a [config] object Configuration of the communication. Use by default the internal package
-#' configuration
+#' @template param_get_common
#'
#' @return a [tibble::tibble] with all available parameters in columns and one row by device.
#' @export
#'
#' @examples
#' # For retrieving the withdrawal points located in Romilly-sur-Seine
-#' get_prelevements_prelevement(list(code_commune_insee = "10323"))
+#' get_prelevements_points_prelevement(list(code_commune_insee = "10323"))
#'
-get_prelevements_prelevement <- function(params, cfg = config::get(file = system.file("config.yml",
+get_prelevements_points_prelevement <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
- l <- doApiQuery(cfg$api_prelevements$points_prelevement, params)
+ l <- doApiQuery(api = "prelevements",
+ operation = "points_prelevement",
+ params = params,
+ cfg = cfg)
+
l <- lapply(l, function(row) {lapply(row, function(cell) { if(is.null(unlist(cell))) NA else unlist(cell) })})
return(purrr::map_df(l, tibble::as_tibble))
}
diff --git a/R/hubeau.R b/R/hubeau.R
new file mode 100644
index 0000000000000000000000000000000000000000..3ba2d41fafae8d39614154086e0ceea18af709c3
--- /dev/null
+++ b/R/hubeau.R
@@ -0,0 +1,28 @@
+#' hubeau: A package for retrieving data on the French databases on water "Hub'eau"
+#'
+#' The 'hubeau' package provides functions for APIs and related "operations". These functions are named as follow: `hubeau::get_[API]_[operation]`.
+#'
+#' Currently available APIs and related "operations" are listed below.
+#'
+#' **API "Indicateurs des services"**
+#'
+#' API documentation: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
+#'
+#' Available functions:
+#'
+#' - [get_indicateurs_services_communes]
+#' - [get_indicateurs_services_indicateurs]
+#'
+#' **API "Prélèvements en eau"**
+#'
+#' API documentation: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau}
+#'
+#' Available functions:
+#'
+#' - [get_prelevements_chroniques]
+#' - [get_prelevements_points_prelevement]
+#'
+#' @docType package
+#' @name hubeau
+#'
+NULL
diff --git a/README.Rmd b/README.Rmd
index c51a711ffb9b464757abd441e11cceeae889bb3a..57addb9309a9809f22f52c3f5cedb66b7882378c 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -13,18 +13,18 @@ knitr::opts_chunk$set(
)
```
-# hubeau
+# hubeau an R package for the Hub'eau APIs
<!-- badges: start -->
`r badger::badge_license(color = "orange")`
`r badger::badge_lifecycle("experimental", color = "blue")`
<!-- badges: end -->
-'hubeau' is an R-package proposing a collection of function to help retrieve the French national data bank of quantitative withdrawals (Banque Nationale des Prélèvements quantitatifs en Eau - BNPE) available on its website https://hubeau.eaufrance.fr and on https://hubeau.eaufrance.fr/page/api-prelevements-eau
+'hubeau' is an R-package proposing a collection of function to help retrieve data from the French national databases on water: https://hubeau.eaufrance.fr
## Installation
-You can install the hubeau R-package from it's development repository with:
+You can install the 'hubeau' R-package from it's development repository with:
``` r
install.packages("remotes")
@@ -37,27 +37,19 @@ remotes::install_gitlab("in-wop/hubeau", host = "gitlab.irstea.fr")
library(hubeau)
```
-## Loading data from the Hub'Eau API
+## Get started
-Two functions are available:
+See the package documentation by typing:
-- `get_prelevements_prelevement`: retrieve data about abstraction points
-- `get_prelevements_chronique`: retrieve annual volume time series and characteristics
-The available filters for these functions are detailed in the API documentation respectively: https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/prelevement and https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/chronique
+```{r}
+?hubeau
+```
-Examples:
+Each function is documented with at least one example:
```{r}
-# Characteristics of surface abstraction points in the Ardennes departement
-pp08 <- get_prelevements_prelevement(list(code_departement = "08", code_type_milieu = "CONT"))
-str(pp08)
-
-# Time series of annual abstracted volumes for drinking water supply from surface water in the Ardennes departement
-# As the parameter "source of the water" (ground, surface...) is not available here, we can use the list of abstraction points previously downloaded as filter:
-dfAEP <- get_prelevements_chronique(list(code_ouvrage = paste(pp08$code_ouvrage, collapse = ","),
- code_usage = "AEP"))
-str(dfAEP)
+example("get_prelevements_chroniques")
```
diff --git a/README.md b/README.md
index 46f609586663bf018a5d158b94bc49ec617451c8..912596300f4e0b8e65246eb514d1bf54a653e0ce 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
<!-- README.md is generated from README.Rmd. Please edit that file -->
-# hubeau
+# hubeau an R package for the Hub’eau APIs
<!-- badges: start -->
@@ -11,14 +11,12 @@ MIT](https://img.shields.io/badge/license-MIT-orange.svg)](https://cran.r-projec
<!-- badges: end -->
‘hubeau’ is an R-package proposing a collection of function to help
-retrieve the French national data bank of quantitative withdrawals
-(Banque Nationale des Prélèvements quantitatifs en Eau - BNPE) available
-on its website <https://hubeau.eaufrance.fr> and on
-<https://hubeau.eaufrance.fr/page/api-prelevements-eau>
+retrieve data from the French national databases on water:
+<https://hubeau.eaufrance.fr>
## Installation
-You can install the hubeau R-package from it’s development repository
+You can install the ‘hubeau’ R-package from it’s development repository
with:
``` r
@@ -32,84 +30,40 @@ remotes::install_gitlab("in-wop/hubeau", host = "gitlab.irstea.fr")
library(hubeau)
```
-## Loading data from the Hub’Eau API
+## Get started
-Two functions are available:
+See the package documentation by typing:
-- `get_prelevements_prelevement`: retrieve data about abstraction
- points
-- `get_prelevements_chronique`: retrieve annual volume time series and
- characteristics
-
-The available filters for these functions are detailed in the API
-documentation respectively:
-<https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/prelevement>
-and
-<https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/chronique>
+``` r
+?hubeau
+```
-Examples:
+Each function is documented with at least one example:
``` r
-# Characteristics of surface abstraction points in the Ardennes departement
-pp08 <- get_prelevements_prelevement(list(code_departement = "08", code_type_milieu = "CONT"))
-str(pp08)
-#> tibble [85 x 28] (S3: tbl_df/tbl/data.frame)
-#> $ code_point_prelevement : chr [1:85] "PTP000000000005792" "PTP000000000005793" "PTP000000000005794" "PTP000000000005795" ...
-#> $ nom_point_prelevement : chr [1:85] "SARL WIEDENMANN" "ENERPRO BOGNY" "FORCES ENERGIES ELECTRIQUES" "STE EXPL CHUTES HYDRAULIQUES" ...
-#> $ date_exploitation_debut : chr [1:85] "1900-01-01" "1900-01-01" "1900-01-01" "1900-01-01" ...
-#> $ date_exploitation_fin : logi [1:85] NA NA NA NA NA NA ...
-#> $ code_type_milieu : chr [1:85] "CONT" "CONT" "CONT" "CONT" ...
-#> $ libelle_type_milieu : chr [1:85] "Surface continental" "Surface continental" "Surface continental" "Surface continental" ...
-#> $ code_nature : chr [1:85] "F" "F" "F" "F" ...
-#> $ libelle_nature : chr [1:85] "FICTIF" "FICTIF" "FICTIF" "FICTIF" ...
-#> $ lieu_dit : logi [1:85] NA NA NA NA NA NA ...
-#> $ commentaire : logi [1:85] NA NA NA NA NA NA ...
-#> $ code_commune_insee : chr [1:85] "08083" "08081" "08185" "08302" ...
-#> $ nom_commune : chr [1:85] "Brévilly" "Bogny-sur-Meuse" "Fumay" "Monthermé" ...
-#> $ code_departement : chr [1:85] "08" "08" "08" "08" ...
-#> $ libelle_departement : chr [1:85] "Ardennes" "Ardennes" "Ardennes" "Ardennes" ...
-#> $ code_entite_hydro_cours_eau: logi [1:85] NA NA NA NA NA NA ...
-#> $ uri_entite_hydro_cours_eau : logi [1:85] NA NA NA NA NA NA ...
-#> $ code_entite_hydro_plan_eau : logi [1:85] NA NA NA NA NA NA ...
-#> $ uri_entite_hydro_plan_eau : logi [1:85] NA NA NA NA NA NA ...
-#> $ code_zone_hydro : chr [1:85] NA NA NA NA ...
-#> $ uri_zone_hydro : chr [1:85] NA NA NA NA ...
-#> $ code_mer_ocean : logi [1:85] NA NA NA NA NA NA ...
-#> $ nappe_accompagnement : logi [1:85] TRUE TRUE TRUE TRUE TRUE TRUE ...
-#> $ uri_bss_point_eau : logi [1:85] NA NA NA NA NA NA ...
-#> $ code_ouvrage : chr [1:85] "OPR0000005780" "OPR0000005781" "OPR0000005782" "OPR0000005783" ...
-#> $ uri_ouvrage : chr [1:85] "https://id.eaufrance.fr/OuvragePrel/OPR0000005780" "https://id.eaufrance.fr/OuvragePrel/OPR0000005781" "https://id.eaufrance.fr/OuvragePrel/OPR0000005782" "https://id.eaufrance.fr/OuvragePrel/OPR0000005783" ...
-#> $ code_bdlisa : logi [1:85] NA NA NA NA NA NA ...
-#> $ uri_bdlisa : logi [1:85] NA NA NA NA NA NA ...
-#> $ code_bss_point_eau : logi [1:85] NA NA NA NA NA NA ...
-
-# Time series of annual abstracted volumes for drinking water supply from surface water in the Ardennes departement
-# As the parameter "source of the water" (ground, surface...) is not available here, we can use the list of abstraction points previously downloaded as filter:
-dfAEP <- get_prelevements_chronique(list(code_ouvrage = paste(pp08$code_ouvrage, collapse = ","),
- code_usage = "AEP"))
-str(dfAEP)
-#> tibble [40 x 23] (S3: tbl_df/tbl/data.frame)
-#> $ code_ouvrage : chr [1:40] "OPR0000000767" "OPR0000000767" "OPR0000000767" "OPR0000000767" ...
-#> $ annee : int [1:40] 2012 2013 2014 2015 2016 2017 2018 2012 2013 2014 ...
-#> $ volume : num [1:40] 189938 175878 167035 169552 169694 ...
-#> $ code_usage : chr [1:40] "AEP" "AEP" "AEP" "AEP" ...
-#> $ libelle_usage : chr [1:40] "EAU POTABLE" "EAU POTABLE" "EAU POTABLE" "EAU POTABLE" ...
-#> $ code_statut_volume : chr [1:40] "1" "1" "1" "1" ...
-#> $ libelle_statut_volume : chr [1:40] "Contrôlé Niveau 1" "Contrôlé Niveau 1" "Contrôlé Niveau 1" "Contrôlé Niveau 1" ...
-#> $ code_qualification_volume : chr [1:40] "1" "1" "1" "1" ...
-#> $ libelle_qualification_volume : chr [1:40] "Correcte" "Correcte" "Correcte" "Correcte" ...
-#> $ code_statut_instruction : chr [1:40] "REA" "REA" "REA" "REA" ...
-#> $ libelle_statut_instruction : chr [1:40] "Prélèvement réalisé" "Prélèvement réalisé" "Prélèvement réalisé" "Prélèvement réalisé" ...
-#> $ code_mode_obtention_volume : chr [1:40] "MED" "MED" "MED" "MED" ...
-#> $ libelle_mode_obtention_volume: chr [1:40] "Mesure directe" "Mesure directe" "Mesure directe" "Mesure directe" ...
-#> $ prelevement_ecrasant : logi [1:40] FALSE FALSE FALSE FALSE FALSE FALSE ...
-#> $ producteur_donnee : chr [1:40] "AERM" "AERM" "AERM" "AERM" ...
-#> $ longitude : num [1:40] 4.83 4.83 4.83 4.83 4.83 ...
-#> $ latitude : num [1:40] 50.1 50.1 50.1 50.1 50.1 ...
-#> $ code_commune_insee : chr [1:40] "08247" "08247" "08247" "08247" ...
-#> $ nom_commune : chr [1:40] "Landrichamps" "Landrichamps" "Landrichamps" "Landrichamps" ...
-#> $ code_departement : chr [1:40] "08" "08" "08" "08" ...
-#> $ libelle_departement : chr [1:40] "Ardennes" "Ardennes" "Ardennes" "Ardennes" ...
-#> $ nom_ouvrage : chr [1:40] "COMMUNE DE GIVET" "COMMUNE DE GIVET" "COMMUNE DE GIVET" "COMMUNE DE GIVET" ...
-#> $ uri_ouvrage : chr [1:40] "https://id.eaufrance.fr/OuvragePrel/OPR0000000767" "https://id.eaufrance.fr/OuvragePrel/OPR0000000767" "https://id.eaufrance.fr/OuvragePrel/OPR0000000767" "https://id.eaufrance.fr/OuvragePrel/OPR0000000767" ...
+example("get_prelevements_chroniques")
+#>
+#> gt_pr_> # For retrieving the withdrawal time series of the devices located in Romilly-sur-Seine
+#> gt_pr_> get_prelevements_chroniques(list(code_commune_insee = "10323"))
+#> # A tibble: 36 x 23
+#> code_ouvrage annee volume code_usage libelle_usage code_statut_volume
+#> <chr> <int> <dbl> <chr> <chr> <chr>
+#> 1 OPR0000032603 2012 617624 AEP EAU POTABLE 1
+#> 2 OPR0000032603 2013 463545 AEP EAU POTABLE 1
+#> 3 OPR0000032603 2014 535557 AEP EAU POTABLE 1
+#> 4 OPR0000032603 2015 541785 AEP EAU POTABLE 1
+#> 5 OPR0000032603 2016 478938 AEP EAU POTABLE 1
+#> 6 OPR0000032603 2017 402363 AEP EAU POTABLE 1
+#> 7 OPR0000032603 2018 402383 AEP EAU POTABLE 1
+#> 8 OPR0000032604 2012 617624 AEP EAU POTABLE 1
+#> 9 OPR0000032604 2013 463545 AEP EAU POTABLE 1
+#> 10 OPR0000032604 2014 535557 AEP EAU POTABLE 1
+#> # ... with 26 more rows, and 17 more variables: libelle_statut_volume <chr>,
+#> # code_qualification_volume <chr>, libelle_qualification_volume <chr>,
+#> # code_statut_instruction <chr>, libelle_statut_instruction <chr>,
+#> # code_mode_obtention_volume <chr>, libelle_mode_obtention_volume <chr>,
+#> # prelevement_ecrasant <lgl>, producteur_donnee <chr>, longitude <dbl>,
+#> # latitude <dbl>, code_commune_insee <chr>, nom_commune <chr>,
+#> # code_departement <chr>, libelle_departement <chr>, nom_ouvrage <chr>,
+#> # uri_ouvrage <chr>
```
diff --git a/inst/config.yml b/inst/config.yml
index 736ca55fa9b2c0e88da58b648a49a7880eca726b..e95862137d2cc886ee6cc9101f3625ff0e161d9d 100644
--- a/inst/config.yml
+++ b/inst/config.yml
@@ -1,11 +1,76 @@
default:
- api_prelevements:
- url: https://hubeau.eaufrance.fr/api/v1/prelevements
- points_prelevement: referentiel/points_prelevement
- chroniques: chroniques
- url: https://bnpe.eaufrance.fr/Bnpe-Diffusion
- url_time_series: synthese/synthese_temporelle
- url_com_series: synthese/synthese_geographique
- url_ouvrage: suggest/get_ouvrages
- url_ouv_series: synthese/synthese_temporelle_ouvrage
- user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:88.0) Gecko/20100101 Firefox/88.0
+ api_url: https://hubeau.eaufrance.fr/api
+ apis:
+ prelevements:
+ path: v1/prelevements
+ operations:
+ points_prelevement:
+ path: referentiel/points_prelevement
+ fields:
+ - code_bdlisa
+ - code_bss_point_eau
+ - code_commune_insee
+ - code_departement
+ - code_entite_hydro_cours_eau
+ - code_entite_hydro_plan_eau
+ - code_mer_ocean
+ - code_nature
+ - code_ouvrage
+ - code_point_prelevement
+ - code_type_milieu
+ - code_zone_hydro
+ - date_exploitation
+ - fields
+ - libelle_departement
+ - nappe_accompagnement
+ - nom_commune
+ - nom_point_prelevement
+ chroniques:
+ path: chroniques
+ fields:
+ - annee
+ - bbox
+ - code_commune_insee
+ - code_departement
+ - code_mode_obtention_volume
+ - code_ouvrage
+ - code_qualification_volume
+ - code_statut_instruction
+ - code_statut_volume
+ - code_usage
+ - distance
+ - fields
+ - latitude
+ - libelle_departement
+ - longitude
+ - nom_commune
+ - prelevement_ecrasant
+ - producteur_donnee
+ - volume_max
+ - volume_min
+ indicateurs_services:
+ path: v0/indicateurs_services
+ operations:
+ communes:
+ path: communes
+ fields:
+ - annee
+ - code_commune
+ - code_departement
+ - detail_service
+ - fields
+ - type_service
+ indicateurs:
+ path: indicateurs
+ fields:
+ - annee
+ - code_indicateur
+ - fields
+ services:
+ path: services
+ fields:
+ - annee
+ - code_commune
+ - code_departement
+ - fields
+ - type_service
diff --git a/man-roxygen/param_get_common.R b/man-roxygen/param_get_common.R
index 24fd79675f7c30fd42a82bd68da039746c39aa91..ecf131342898dfef8a667319b9e9bb0371d37c77 100644
--- a/man-roxygen/param_get_common.R
+++ b/man-roxygen/param_get_common.R
@@ -1,13 +1,2 @@
-#' @param code_usage a [character()] representing the withdrawal destination which can take the following values:
-#' - "ENE" for energy
-#' - "CAN" for artificial canals
-#' - "BAR" for turbined water (dam)
-#' - "AEP" for drinking water
-#' - "IND" for industry
-#' - "IRR" for irrigation
-#' @param code_type_eau a [character()] representing the withdrawal source which can take the following values:
-#' - "CONT" for continental surface
-#' - "SOUT" for subsurface
-#' - "LIT" for littoral
-#' @param cookie a named [character] [vector] with the values of the cookies (See [getCookie])
-#' @inheritParams getCookie
+#' @param cfg a [config] object Configuration of the communication. Use by default the internal package
+#' configuration
diff --git a/man/doApiQuery.Rd b/man/doApiQuery.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..afd4a33b2ac3bb0ca019c57f37eaeeddf4220b2e
--- /dev/null
+++ b/man/doApiQuery.Rd
@@ -0,0 +1,59 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/doApiQuery.R, R/get_available_params.R
+\name{doApiQuery}
+\alias{doApiQuery}
+\alias{get_available_params}
+\title{Main internal functions for querying the Hub'eau APIs}
+\usage{
+doApiQuery(
+ api,
+ operation,
+ params,
+ cfg = config::get(file = system.file("config.yml", package = "hubeau"))
+)
+
+get_available_params(
+ api,
+ operation,
+ cfg = config::get(file = system.file("config.yml", package = "hubeau"))
+)
+}
+\arguments{
+\item{api}{a \link{character} name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs}
+
+\item{operation}{a \link{character} name of the operation, see example for available operations in an API}
+
+\item{params}{a \link{list} the list of parameters of the queries and their values in the format \code{list(ParamName = "Param value", ...)}, use the function \code{get_available_params} for a list of the available parameters for a given operation in an API}
+
+\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
+configuration}
+}
+\value{
+A \link{list} with the concatenated results returned by the API.
+}
+\description{
+The function \code{doQueryApi} is called by all the function querying the APIs and return the raw data sent by the API.
+Pagination of the queries is handled automatically and the returned \link{list} is the concatenation of all the results sent by the API.
+}
+\details{
+The function \code{get_available_params} returns the list of available query parameters for a given operation in an API.
+
+The functions \verb{get_[api]_[operation]} call the function \code{doQueryApi} and convert the response in a convenient format for the user (\link{data.frame} or \link{tibble})
+}
+\examples{
+# To get the available APIs in the package
+cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
+names(cfg$apis)
+
+# To get the available operation in an API
+names(cfg$apis[["prelevements"]]$operations)
+
+# To get available parameters in operation "chroniques" of the API "prelevements"
+get_available_params(api = "prelevements", operation = "chroniques")
+
+# To query the operation "chroniques" of the API "prelevements"
+# on all devices in the commune of Romilly-sur-Seine in 2018
+doApiQuery(api = "prelevements",
+ operation = "chroniques",
+ params = list(code_commune_insee = "10323", annee = "2018"))
+}
diff --git a/man/get_indicateurs_services_communes.Rd b/man/get_indicateurs_services_communes.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..d5d1002bda4c9b1f83f59d5bffca3f44c6491eff
--- /dev/null
+++ b/man/get_indicateurs_services_communes.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/get_indicateurs_services_communes.R
+\name{get_indicateurs_services_communes}
+\alias{get_indicateurs_services_communes}
+\title{Retrieve performance indicators from drinking water supply and sanitation services at commune level}
+\usage{
+get_indicateurs_services_communes(
+ params,
+ cfg = config::get(file = system.file("config.yml", package = "hubeau"))
+)
+}
+\arguments{
+\item{params}{\link{list} where the keys are the names of the filtered parameters and the values are the values of the filters. See the API documentation for the complete list of available filter parameters}
+
+\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
+configuration}
+}
+\value{
+a \link[tibble:tibble]{tibble::tibble} with one row by commune, by service and by year and the following columns:
+\itemize{
+\item "code_commune_insee": \link{character} identifier of the commune
+\item "nom_commune": \link{character} name of the commune
+\item "codes_service": \link{integer} identifier of the drinking water supply and/or sanitation service
+\item "annee": \link{integer} year of the data
+\item 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}.
+}
+}
+\description{
+See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
+}
+\examples{
+# For retrieving performance indicator time series of the services in Romilly-sur-Seine
+get_indicateurs_services_communes(list(code_commune = "10323"))
+
+}
diff --git a/man/get_indicateurs_services_indicateurs.Rd b/man/get_indicateurs_services_indicateurs.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..a3157ee456cca8fbc266b71e201fc7f1e4eb41e0
--- /dev/null
+++ b/man/get_indicateurs_services_indicateurs.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/get_indicateurs_services_indicateurs.R
+\name{get_indicateurs_services_indicateurs}
+\alias{get_indicateurs_services_indicateurs}
+\title{Retrieve performance indicators from drinking water supply and sanitation services at commune level}
+\usage{
+get_indicateurs_services_indicateurs(
+ params,
+ cfg = config::get(file = system.file("config.yml", package = "hubeau"))
+)
+}
+\arguments{
+\item{params}{\link{list} where the keys are the names of the filtered parameters and the values are the values of the filters. See the API documentation for the complete list of available filter parameters}
+
+\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
+configuration}
+}
+\value{
+a \link[tibble:tibble]{tibble::tibble} with one row by commune, by service and by year and the following columns:
+\itemize{
+\item "code_commune_insee": \link{character} identifier of the commune
+\item "nom_commune": \link{character} name of the commune
+\item "codes_service": \link{integer} identifier of the drinking water supply and/or sanitation service
+\item "annee": \link{integer} year of the data
+\item 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}.
+}
+}
+\description{
+See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
+}
+\examples{
+# For retrieving the withdrawal time series of the devices located in Romilly-sur-Seine
+get_indicateurs_services_indicateurs(list(code_indicateur = "D102.0", annee = "2012"))
+
+}
diff --git a/man/get_prelevements_chronique.Rd b/man/get_prelevements_chroniques.Rd
similarity index 80%
rename from man/get_prelevements_chronique.Rd
rename to man/get_prelevements_chroniques.Rd
index 588ffeb868818c57eccd755332f6a7e19a8eaab9..6a1071d86fd288e621df9c24689a9d41aed31011 100644
--- a/man/get_prelevements_chronique.Rd
+++ b/man/get_prelevements_chroniques.Rd
@@ -1,10 +1,10 @@
% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/get_prelevements_chronique.R
-\name{get_prelevements_chronique}
-\alias{get_prelevements_chronique}
+% Please edit documentation in R/get_prelevements_chroniques.R
+\name{get_prelevements_chroniques}
+\alias{get_prelevements_chroniques}
\title{Retrieve time series of withdrawals from Hub'Eau API}
\usage{
-get_prelevements_chronique(
+get_prelevements_chroniques(
params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))
)
@@ -23,6 +23,6 @@ See the API documentation for available filter parameters: \url{https://hubeau.e
}
\examples{
# For retrieving the withdrawal time series of the devices located in Romilly-sur-Seine
-get_prelevements_chronique(list(code_commune_insee = "10323"))
+get_prelevements_chroniques(list(code_commune_insee = "10323"))
}
diff --git a/man/get_prelevements_prelevement.Rd b/man/get_prelevements_points_prelevement.Rd
similarity index 76%
rename from man/get_prelevements_prelevement.Rd
rename to man/get_prelevements_points_prelevement.Rd
index 63f6390171b938c225acc42c07a24250f6957337..e158909c2879db5aae22588c0f84601e92b9e838 100644
--- a/man/get_prelevements_prelevement.Rd
+++ b/man/get_prelevements_points_prelevement.Rd
@@ -1,10 +1,10 @@
% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/get_prelevements_prelevement.R
-\name{get_prelevements_prelevement}
-\alias{get_prelevements_prelevement}
+% Please edit documentation in R/get_prelevements_points_prelevement.R
+\name{get_prelevements_points_prelevement}
+\alias{get_prelevements_points_prelevement}
\title{Retrieve withdrawal points from Hub'Eau API}
\usage{
-get_prelevements_prelevement(
+get_prelevements_points_prelevement(
params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))
)
@@ -23,6 +23,6 @@ See the API documentation for available filter parameters: \url{https://hubeau.e
}
\examples{
# For retrieving the withdrawal points located in Romilly-sur-Seine
-get_prelevements_prelevement(list(code_commune_insee = "10323"))
+get_prelevements_points_prelevement(list(code_commune_insee = "10323"))
}
diff --git a/man/hubeau.Rd b/man/hubeau.Rd
new file mode 100644
index 0000000000000000000000000000000000000000..3de365ccb8b2369475ea62d0c953d29984a2d26e
--- /dev/null
+++ b/man/hubeau.Rd
@@ -0,0 +1,32 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/hubeau.R
+\docType{package}
+\name{hubeau}
+\alias{hubeau}
+\title{hubeau: A package for retrieving data on the French databases on water "Hub'eau"}
+\description{
+The 'hubeau' package provides functions for APIs and related "operations". These functions are named as follow: \verb{hubeau::get_[API]_[operation]}.
+}
+\details{
+Currently available APIs and related "operations" are listed below.
+
+\strong{API "Indicateurs des services"}
+
+API documentation: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
+
+Available functions:
+\itemize{
+\item \link{get_indicateurs_services_communes}
+\item \link{get_indicateurs_services_indicateurs}
+}
+
+\strong{API "Prélèvements en eau"}
+
+API documentation: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau}
+
+Available functions:
+\itemize{
+\item \link{get_prelevements_chroniques}
+\item \link{get_prelevements_points_prelevement}
+}
+}