Skip to content
GitLab
Commit 351333b0 authored by Dorchies David's avatar Dorchies David
Browse files

feat: Add API indicateurs_services 

- rename prelevements APIs functions
- add parameter checks for each operation
- add `get_indicateurs_services_communes` and `get_indicateurs_services_indicateurs`
- add package documentation main page and improve documentation

Refs #4
parent 85145070
master
No related merge requests found
Pipeline #26070 passed with stages
in 1 minute and 49 seconds
Hide whitespace changes
Inline Side-by-side
Showing
with 511 additions and 148 deletions
+511 -148
NAMESPACE
+ 6
− 2
View file @ 351333b0
# Generated by roxygen2: do not edit by hand # Generated by roxygen2: do not edit by hand
export(get_prelevements_chronique) export(doApiQuery)
export(get_prelevements_prelevement) export(get_available_params)
export(get_indicateurs_services_communes)
export(get_indicateurs_services_indicateurs)
export(get_prelevements_chroniques)
export(get_prelevements_points_prelevement)
R/doApiQuery.R
+ 78
− 4
View file @ 351333b0
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, params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))) { 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)) { 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]])) { if (!is.null(params[[paramName]])) {
query <- urltools::param_set(query, query <- urltools::param_set(query,
key = paramName, key = paramName,
...@@ -10,15 +62,37 @@ doApiQuery <- function(url_path, ...@@ -10,15 +62,37 @@ doApiQuery <- function(url_path,
} }
} }
data <- list() data <- list()
repeat { repeat {
resp <- httr::GET(query) resp <- httr::GET(query)
if (resp$status_code >= 300) { if (resp$status_code >= 400) {
stop("Error", resp$status_code, " on query: ", query) 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 { } else {
l <- httr::content(resp, "parsed") l <- httr::content(resp, "parsed")
data <- c(data, l$data) data <- c(data, l$data)
if (resp$status_code == 206) { if (resp$status_code == 206) {
query <- l$`next` query <- l$`next`
if (is.null(query)) {
# Bug https://github.com/BRGM/hubeau/issues/72
break
}
} }
if (resp$status_code == 200) { if (resp$status_code == 200) {
break break
......
R/get_available_params.R 0 → 100644
+ 15
− 0
View file @ 351333b0
#' @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
}
R/get_indicateurs_services_communes.R 0 → 100644
+ 38
− 0
View file @ 351333b0
#' 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))
}
R/get_indicateurs_services_indicateurs.R 0 → 100644
+ 38
− 0
View file @ 351333b0
#' 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()
}
R/get_prelevements_chronique.R → R/get_prelevements_chroniques.R
+ 7
− 5
View file @ 351333b0
...@@ -3,19 +3,21 @@ ...@@ -3,19 +3,21 @@
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/chronique} #' 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 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 #' @template param_get_common
#' configuration
#' #'
#' @return a [tibble::tibble] with all available parameters in columns and one row by device, year and usage. #' @return a [tibble::tibble] with all available parameters in columns and one row by device, year and usage.
#' @export #' @export
#' #'
#' @examples #' @examples
#' # For retrieving the withdrawal time series of the devices located in Romilly-sur-Seine #' # 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"))) { package = "hubeau"))) {
l <- doApiQuery(cfg$api_prelevements$chronique, params) l <- doApiQuery(api = "prelevements",
operation = "chroniques",
params = params,
cfg = cfg)
l <- lapply(l, function(x) { l <- lapply(l, function(x) {
x$geometry <- NULL x$geometry <- NULL
x x
......
R/get_prelevements_prelevement.R → R/get_prelevements_points_prelevement.R
+ 8
− 5
View file @ 351333b0
...@@ -3,19 +3,22 @@ ...@@ -3,19 +3,22 @@
#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/prelevement} #' 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 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 #' @template param_get_common
#' configuration
#' #'
#' @return a [tibble::tibble] with all available parameters in columns and one row by device. #' @return a [tibble::tibble] with all available parameters in columns and one row by device.
#' @export #' @export
#' #'
#' @examples #' @examples
#' # For retrieving the withdrawal points located in Romilly-sur-Seine #' # 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"))) { 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) })}) 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)) return(purrr::map_df(l, tibble::as_tibble))
} }
R/hubeau.R 0 → 100644
+ 28
− 0
View file @ 351333b0
#' 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
README.Rmd
+ 10
− 18
View file @ 351333b0
...@@ -13,18 +13,18 @@ knitr::opts_chunk$set( ...@@ -13,18 +13,18 @@ knitr::opts_chunk$set(
) )
``` ```
# hubeau # hubeau an R package for the Hub'eau APIs
<!-- badges: start --> <!-- badges: start -->
`r badger::badge_license(color = "orange")` `r badger::badge_license(color = "orange")`
`r badger::badge_lifecycle("experimental", color = "blue")` `r badger::badge_lifecycle("experimental", color = "blue")`
<!-- badges: end --> <!-- 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 ## 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 ``` r
install.packages("remotes") install.packages("remotes")
...@@ -37,27 +37,19 @@ remotes::install_gitlab("in-wop/hubeau", host = "gitlab.irstea.fr") ...@@ -37,27 +37,19 @@ remotes::install_gitlab("in-wop/hubeau", host = "gitlab.irstea.fr")
library(hubeau) 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} ```{r}
# Characteristics of surface abstraction points in the Ardennes departement example("get_prelevements_chroniques")
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)
``` ```
README.md
+ 35
− 81
View file @ 351333b0
<!-- README.md is generated from README.Rmd. Please edit that file --> <!-- README.md is generated from README.Rmd. Please edit that file -->
# hubeau # hubeau an R package for the Hub’eau APIs
<!-- badges: start --> <!-- badges: start -->
...@@ -11,14 +11,12 @@ MIT](https://img.shields.io/badge/license-MIT-orange.svg)](https://cran.r-projec ...@@ -11,14 +11,12 @@ MIT](https://img.shields.io/badge/license-MIT-orange.svg)](https://cran.r-projec
<!-- badges: end --> <!-- badges: end -->
‘hubeau’ is an R-package proposing a collection of function to help ‘hubeau’ is an R-package proposing a collection of function to help
retrieve the French national data bank of quantitative withdrawals retrieve data from the French national databases on water:
(Banque Nationale des Prélèvements quantitatifs en Eau - BNPE) available <https://hubeau.eaufrance.fr>
on its website <https://hubeau.eaufrance.fr> and on
<https://hubeau.eaufrance.fr/page/api-prelevements-eau>
## Installation ## 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: with:
``` r ``` r
...@@ -32,84 +30,40 @@ remotes::install_gitlab("in-wop/hubeau", host = "gitlab.irstea.fr") ...@@ -32,84 +30,40 @@ remotes::install_gitlab("in-wop/hubeau", host = "gitlab.irstea.fr")
library(hubeau) 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 ``` r
points ?hubeau
- `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>
Examples: Each function is documented with at least one example:
``` r ``` r
# Characteristics of surface abstraction points in the Ardennes departement example("get_prelevements_chroniques")
pp08 <- get_prelevements_prelevement(list(code_departement = "08", code_type_milieu = "CONT")) #>
str(pp08) #> gt_pr_> # For retrieving the withdrawal time series of the devices located in Romilly-sur-Seine
#> tibble [85 x 28] (S3: tbl_df/tbl/data.frame) #> gt_pr_> get_prelevements_chroniques(list(code_commune_insee = "10323"))
#> $ code_point_prelevement : chr [1:85] "PTP000000000005792" "PTP000000000005793" "PTP000000000005794" "PTP000000000005795" ... #> # A tibble: 36 x 23
#> $ nom_point_prelevement : chr [1:85] "SARL WIEDENMANN" "ENERPRO BOGNY" "FORCES ENERGIES ELECTRIQUES" "STE EXPL CHUTES HYDRAULIQUES" ... #> code_ouvrage annee volume code_usage libelle_usage code_statut_volume
#> $ date_exploitation_debut : chr [1:85] "1900-01-01" "1900-01-01" "1900-01-01" "1900-01-01" ... #> <chr> <int> <dbl> <chr> <chr> <chr>
#> $ date_exploitation_fin : logi [1:85] NA NA NA NA NA NA ... #> 1 OPR0000032603 2012 617624 AEP EAU POTABLE 1
#> $ code_type_milieu : chr [1:85] "CONT" "CONT" "CONT" "CONT" ... #> 2 OPR0000032603 2013 463545 AEP EAU POTABLE 1
#> $ libelle_type_milieu : chr [1:85] "Surface continental" "Surface continental" "Surface continental" "Surface continental" ... #> 3 OPR0000032603 2014 535557 AEP EAU POTABLE 1
#> $ code_nature : chr [1:85] "F" "F" "F" "F" ... #> 4 OPR0000032603 2015 541785 AEP EAU POTABLE 1
#> $ libelle_nature : chr [1:85] "FICTIF" "FICTIF" "FICTIF" "FICTIF" ... #> 5 OPR0000032603 2016 478938 AEP EAU POTABLE 1
#> $ lieu_dit : logi [1:85] NA NA NA NA NA NA ... #> 6 OPR0000032603 2017 402363 AEP EAU POTABLE 1
#> $ commentaire : logi [1:85] NA NA NA NA NA NA ... #> 7 OPR0000032603 2018 402383 AEP EAU POTABLE 1
#> $ code_commune_insee : chr [1:85] "08083" "08081" "08185" "08302" ... #> 8 OPR0000032604 2012 617624 AEP EAU POTABLE 1
#> $ nom_commune : chr [1:85] "Brévilly" "Bogny-sur-Meuse" "Fumay" "Monthermé" ... #> 9 OPR0000032604 2013 463545 AEP EAU POTABLE 1
#> $ code_departement : chr [1:85] "08" "08" "08" "08" ... #> 10 OPR0000032604 2014 535557 AEP EAU POTABLE 1
#> $ libelle_departement : chr [1:85] "Ardennes" "Ardennes" "Ardennes" "Ardennes" ... #> # ... with 26 more rows, and 17 more variables: libelle_statut_volume <chr>,
#> $ code_entite_hydro_cours_eau: logi [1:85] NA NA NA NA NA NA ... #> # code_qualification_volume <chr>, libelle_qualification_volume <chr>,
#> $ uri_entite_hydro_cours_eau : logi [1:85] NA NA NA NA NA NA ... #> # code_statut_instruction <chr>, libelle_statut_instruction <chr>,
#> $ code_entite_hydro_plan_eau : logi [1:85] NA NA NA NA NA NA ... #> # code_mode_obtention_volume <chr>, libelle_mode_obtention_volume <chr>,
#> $ uri_entite_hydro_plan_eau : logi [1:85] NA NA NA NA NA NA ... #> # prelevement_ecrasant <lgl>, producteur_donnee <chr>, longitude <dbl>,
#> $ code_zone_hydro : chr [1:85] NA NA NA NA ... #> # latitude <dbl>, code_commune_insee <chr>, nom_commune <chr>,
#> $ uri_zone_hydro : chr [1:85] NA NA NA NA ... #> # code_departement <chr>, libelle_departement <chr>, nom_ouvrage <chr>,
#> $ code_mer_ocean : logi [1:85] NA NA NA NA NA NA ... #> # uri_ouvrage <chr>
#> $ 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" ...
``` ```
inst/config.yml
+ 75
− 10
View file @ 351333b0
default: default:
api_prelevements: api_url: https://hubeau.eaufrance.fr/api
url: https://hubeau.eaufrance.fr/api/v1/prelevements apis:
points_prelevement: referentiel/points_prelevement prelevements:
chroniques: chroniques path: v1/prelevements
url: https://bnpe.eaufrance.fr/Bnpe-Diffusion operations:
url_time_series: synthese/synthese_temporelle points_prelevement:
url_com_series: synthese/synthese_geographique path: referentiel/points_prelevement
url_ouvrage: suggest/get_ouvrages fields:
url_ouv_series: synthese/synthese_temporelle_ouvrage - code_bdlisa
user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:88.0) Gecko/20100101 Firefox/88.0 - 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
man-roxygen/param_get_common.R
+ 2
− 13
View file @ 351333b0
#' @param code_usage a [character()] representing the withdrawal destination which can take the following values: #' @param cfg a [config] object Configuration of the communication. Use by default the internal package
#' - "ENE" for energy #' configuration
#' - "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
man/doApiQuery.Rd 0 → 100644
+ 59
− 0
View file @ 351333b0
% 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"))
}
man/get_indicateurs_services_communes.Rd 0 → 100644
+ 35
− 0
View file @ 351333b0
% 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"))
}
man/get_indicateurs_services_indicateurs.Rd 0 → 100644
+ 35
− 0
View file @ 351333b0
% 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"))
}
man/get_prelevements_chronique.Rd → man/get_prelevements_chroniques.Rd
+ 5
− 5
View file @ 351333b0
% Generated by roxygen2: do not edit by hand % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_prelevements_chronique.R % Please edit documentation in R/get_prelevements_chroniques.R
\name{get_prelevements_chronique} \name{get_prelevements_chroniques}
\alias{get_prelevements_chronique} \alias{get_prelevements_chroniques}
\title{Retrieve time series of withdrawals from Hub'Eau API} \title{Retrieve time series of withdrawals from Hub'Eau API}
\usage{ \usage{
get_prelevements_chronique( get_prelevements_chroniques(
params, params,
cfg = config::get(file = system.file("config.yml", package = "hubeau")) 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 ...@@ -23,6 +23,6 @@ See the API documentation for available filter parameters: \url{https://hubeau.e
} }
\examples{ \examples{
# For retrieving the withdrawal time series of the devices located in Romilly-sur-Seine # 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"))
} }
man/get_prelevements_prelevement.Rd → man/get_prelevements_points_prelevement.Rd
+ 5
− 5
View file @ 351333b0
% Generated by roxygen2: do not edit by hand % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_prelevements_prelevement.R % Please edit documentation in R/get_prelevements_points_prelevement.R
\name{get_prelevements_prelevement} \name{get_prelevements_points_prelevement}
\alias{get_prelevements_prelevement} \alias{get_prelevements_points_prelevement}
\title{Retrieve withdrawal points from Hub'Eau API} \title{Retrieve withdrawal points from Hub'Eau API}
\usage{ \usage{
get_prelevements_prelevement( get_prelevements_points_prelevement(
params, params,
cfg = config::get(file = system.file("config.yml", package = "hubeau")) 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 ...@@ -23,6 +23,6 @@ See the API documentation for available filter parameters: \url{https://hubeau.e
} }
\examples{ \examples{
# For retrieving the withdrawal points located in Romilly-sur-Seine # 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"))
} }
man/hubeau.Rd 0 → 100644
+ 32
− 0
View file @ 351333b0
% 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}
}
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment