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

NAMESPACE

 # 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)

R/doApiQuery.R

-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

R/get_available_params.R

+#' @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

+#' 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

+#' 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

@@ -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

R/get_prelevements_prelevement.R → 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))
 }

R/hubeau.R

+#' 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

@@ -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")
 ```
 
 

README.md

 
 <!-- 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>
 ```

inst/config.yml

 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

man-roxygen/param_get_common.R

-#' @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

man/doApiQuery.Rd

+% 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}
+