docs: Aggregate documentation pby API

Closes #16

NAMESPACE

 # Generated by roxygen2: do not edit by hand
 
+export(convert_list_to_tibble)
 export(doApiQuery)
 export(get_available_params)
 export(get_hydrometrie_obs_elab)

NEWS.md

@@ -3,6 +3,7 @@ hubeau (development version)
 
 New features
 ------------
+* Aggregate documentation by API (#16)
 * Add informations in DESCRIPTION file (#12)
 * `get_hydrometrie_observations_tr` add an option for handling duplicate entries (#10)
 * Deploy pkgdown website on github (#9)

R/doApiQuery.R

@@ -8,8 +8,10 @@
 #' @details The functions `get_[api]_[operation]` call the function `doQueryApi` and convert the response in a convenient format for the user ([data.frame] or [tibble::tibble])
 #'
 #' @param api a [character] name of the API (e.g.: "indicateurs_services", "prelevements"...), see example for available APIs
-#' @param operation a [character] name of the operation, see example for available operations in an API
-#' @template param_get_common
+#' @param operation a [character] name of the endpoint, see example for available endpoints in an API
+#' @param params a [list] the list of parameters of the queries and their values in the format `list(ParamName = "Param value", ...)`, use the function [get_available_params] for a list of the available filter parameters for a given operation in an API and see the API documentation for their description
+#' @param cfg a [config] object describing the configuration of the APIs. Use the internal package configuration by default
+#'        configuration
 #'
 #' @return A [list] with the concatenated results returned by the API.
 #' @export
@@ -110,12 +112,13 @@ doApiQuery <- function(api,
 }
 
 
-#' Convert list provided by the API into a tibble
+#' Convert list provided by the APIs into a tibble
 #'
-#' @param l a [list] provided by the API
+#' @param l a [list] provided by the API (See [doApiQuery])
 #'
-#' @return a [tibble:tibble] with one row by list item and one column by list sub-item
-#' @noRd
+#' @return a [tibble::tibble] with one row by list item and one column by list sub-item
+#'
+#' @export
 #'
 convert_list_to_tibble <- function(l) {
   l <-

R/get_hydrometrie_sites.R → R/get_hydrometrie.R

-#' Retrieve hydrometric sites from API "Hydrométrie"
+#' Retrieve data from API "Hydrométrie"
 #'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
+#' @description
+#'
+#' Available endpoints are:
+#'
+#' - `get_hydrometrie_obs_elab` retrieves hydrometric elaborate observations (daily/monthly mean flow)
+#' - `get_hydrometrie_observations_tr` retrieves hydrometric "real time" observations ()
+#' - `get_hydrometrie_sites` retrieves hydrometric sites
+#' - `get_hydrometrie_stations` retrieves hydrometric stations
+#'
+#' See the API documentation of each endpoint for available filter parameters:
+#' \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
 #'
 #' @template param_get_common
-#' @param unique_site optional [logical], if set to `FALSE` sites with several different locations produce one row by different location otherwise the first location found is used for fields `code_commune_site`, `libelle_commune`, `code_departement`, `code_region`, `libelle_region`, `libelle_departement`
 #'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by device, year and usage.
 #' @export
-#'
+#' @rdname get_hydrometrie
 #' @examples
 #' # Retrieve the hydrometric sites in the department of Aube
 #' get_hydrometrie_sites(list(code_departement = "10"))
@@ -15,6 +23,78 @@
 #' # The same operation returning 2 rows for the site 'H0203020' which has 2 different locations
 #' get_hydrometrie_sites(list(code_departement = "10"), unique_site = FALSE)
 #'
+#' \dontrun{
+#' # This function is currently (2021-12-23) unstable and can be unavailable
+#' # (See https://github.com/BRGM/hubeau/issues/85)
+#' # Retrieve the hydrometric stations in the department of Aube
+#' get_hydrometrie_stations(list(code_departement = "10"))
+#' }
+#'
+#' # Which parameters are available for endpoint "obs_elab" of API "hydrometrie"?
+#' get_available_params("hydrometrie", "obs_elab")
+#'
+#' # Retrieve the hydrometric monthly mean flow at site 'H0203020'
+#' get_hydrometrie_obs_elab(list(code_entite = "H0203020", grandeur_hydro_elab = "QmM"))
+#'
+#' # Retrieve the hydrometric daily mean flow at site 'H0203020' of the last 30 days
+#' get_hydrometrie_obs_elab(
+#'   list(code_entite = "H0203020",
+#'   date_debut_obs_elab = format(Sys.Date() -30, "%Y-%m-%d"),
+#'   grandeur_hydro_elab = "QmJ"))
+#'
+get_hydrometrie_obs_elab <- function(params,
+                                     cfg = config::get(file = system.file("config.yml",
+                                                                          package = "hubeau"))) {
+  l <- doApiQuery(
+    api = "hydrometrie",
+    operation = "obs_elab",
+    params = params,
+    cfg = cfg
+  )
+  convert_list_to_tibble(l)
+}
+
+#' @param entities 1-length [character] string filtering the rows of the returned value, possible values are: "station" for filtering on station rows, "site" for filtering on site rows, "both" for keeping all the rows
+#' @rdname get_hydrometrie
+#' @export
+get_hydrometrie_observations_tr  <- function(params,
+                                             entities = "station",
+                                             cfg = config::get(file = system.file("config.yml",
+                                                        package = "hubeau"))) {
+  # Checks
+  if(!entities %in% c("station", "site", "both")) {
+    stop("Argument 'entities' must be one of these values: 'station', 'site', 'both'")
+  }
+
+  l <- doApiQuery(
+    api = "hydrometrie",
+    operation = "observations_tr",
+    params = params,
+    cfg = cfg
+  )
+  if(!is.null(l)) {
+    l <- lapply(l, function(x) {
+      x$geometry <- NULL
+      if (entities == "station") {
+        if (is.null(x$code_station)) {
+          return(NULL)
+        }
+      } else if (entities == "site") {
+        if (!is.null(x$code_station)) {
+          return(NULL)
+        }
+      }
+      return(x)
+    })
+    l[sapply(l, is.null)] <- NULL
+    l <- convert_list_to_tibble(l)
+  }
+  return(l)
+}
+
+#' @param unique_site optional [logical], if set to `FALSE` sites with several different locations produce one row by different location otherwise the first location found is used for fields `code_commune_site`, `libelle_commune`, `code_departement`, `code_region`, `libelle_region`, `libelle_departement`
+#' @rdname get_hydrometrie
+#' @export
 get_hydrometrie_sites  <- function(params,
                                    unique_site = TRUE,
                                    cfg = config::get(file = system.file("config.yml",
@@ -61,3 +141,22 @@ get_hydrometrie_sites  <- function(params,
   })
   convert_list_to_tibble(l)
 }
+
+#' @param code_sandre_reseau_station optional [logical] indicating if `code_sandre_reseau_station` field is included in the result; if so, one line is added by item and other fields are repeated
+#' @rdname get_hydrometrie
+#' @export
+get_hydrometrie_stations  <- function(params, code_sandre_reseau_station = FALSE, cfg = config::get(file = system.file("config.yml",
+                                                                                      package = "hubeau"))) {
+  l <- doApiQuery(api = "hydrometrie",
+                  operation = "stations",
+                  params = params,
+                  cfg = cfg)
+  l <- lapply(l, function(x) {
+    if (!code_sandre_reseau_station) {
+      x$code_sandre_reseau_station <- NULL
+    }
+    x$geometry <- NULL
+    x
+  })
+  convert_list_to_tibble(l)
+}

R/get_hydrometrie_obs_elab.R

-#' Retrieve hydrometric elaborate observations from API "Hydrométrie"
-#'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie#operations-hydrometrie-observationsElaborees}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
-#' @export
-#'
-#' @examples
-#' # Retrieve the hydrometric last real time observed discharge at station 'H020302002'
-#' get_hydrometrie_obs_elab(list(code_entite = "H0203020", grandeur_hydro_elab = "QmM"))
-get_hydrometrie_obs_elab <- function(params,
-                                     cfg = config::get(file = system.file("config.yml",
-                                                                          package = "hubeau"))) {
-  l <- doApiQuery(
-    api = "hydrometrie",
-    operation = "obs_elab",
-    params = params,
-    cfg = cfg
-  )
-  convert_list_to_tibble(l)
-}

R/get_hydrometrie_observations_tr.R

-#' Retrieve hydrometric "real time" observations from API "Hydrométrie"
-#'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
-#'
-#' @template param_get_common
-#' @param entities 1-[character] string filtering the rows of the returned value, possible values are: "station" for filtering on station rows, "site" for filtering on site rows, "both" for keeping all the rows
-#'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
-#' If the query returns no records then the returned value is [NULL].
-#'
-#' @export
-#'
-#' @examples
-#' # Retrieve the hydrometric last real time observed discharge at station 'H020302002'
-#' get_hydrometrie_observations_tr(list(code_entite = "H0203020", grandeur_hydro = "Q"))
-#'
-get_hydrometrie_observations_tr  <- function(params,
-                                             entities = "station",
-                                             cfg = config::get(file = system.file("config.yml",
-                                                        package = "hubeau"))) {
-  # Checks
-  if(!entities %in% c("station", "site", "both")) {
-    stop("Argument 'entities' must be one of these values: 'station', 'site', 'both'")
-  }
-
-  l <- doApiQuery(
-    api = "hydrometrie",
-    operation = "observations_tr",
-    params = params,
-    cfg = cfg
-  )
-  if(!is.null(l)) {
-    l <- lapply(l, function(x) {
-      x$geometry <- NULL
-      if (entities == "station") {
-        if (is.null(x$code_station)) {
-          return(NULL)
-        }
-      } else if (entities == "site") {
-        if (!is.null(x$code_station)) {
-          return(NULL)
-        }
-      }
-      return(x)
-    })
-    l[sapply(l, is.null)] <- NULL
-    l <- convert_list_to_tibble(l)
-  }
-  return(l)
-}

R/get_hydrometrie_stations.R

-#' Retrieve hydrometric stations from API "Hydrométrie"
-#'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
-#'
-#' @template param_get_common
-#' @param code_sandre_reseau_station optional [logical] indicating if `code_sandre_reseau_station` field is included in the result; if so, one line is added by item and other fields are repeated
-#'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by station.
-#' @export
-#'
-#' @examples
-#' \dontrun{
-#' # This function is temporarily unavailable because of https://github.com/BRGM/hubeau/issues/85
-#'
-#' # Retrieve the hydrometric stations in the department of Aube
-#' get_hydrometrie_stations(list(code_departement = "10"))
-#' }
-get_hydrometrie_stations  <- function(params, code_sandre_reseau_station = FALSE, cfg = config::get(file = system.file("config.yml",
-                                                                                      package = "hubeau"))) {
-  l <- doApiQuery(api = "hydrometrie",
-                  operation = "stations",
-                  params = params,
-                  cfg = cfg)
-  l <- lapply(l, function(x) {
-    if (!code_sandre_reseau_station) {
-      x$code_sandre_reseau_station <- NULL
-    }
-    x$geometry <- NULL
-    x
-  })
-  convert_list_to_tibble(l)
-}

R/get_indicateurs_services.R

+#' Retrieve performance indicators from drinking water supply and sanitation services at commune level
+#'
+#' @description
+#' Available endpoints are:
+#'
+#' -
+#'
+#' See [get_available_params] and the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-indicateurs-services}
+#'
+#' @template param_get_common
+#'
+#' @details
+#' `get_indicateurs_services_communes` returns a [tibble::tibble] with one row by commune, by service and by year and the following columns:
+#'
+#' - "code_commune_insee": [character] identifier of the commune
+#' - "nom_commune": [character] name of the commune
+#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
+#' - "annee": [integer] year of the data
+#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
+#'
+#' a [tibble::tibble] with one row by commune, by service and by year and the following columns:
+#'
+#' - "code_commune_insee": [character] identifier of the commune
+#' - "nom_commune": [character] name of the commune
+#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
+#' - "annee": [integer] year of the data
+#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
+#'
+#' `get_indicateurs_services_indicateurs` returns a [tibble::tibble] with one row by service and by year and the following columns:
+#'
+#' - "code_service": [character] identifier of the service
+#' - "nom_service": [character] name of the service
+#' - "numero_siren ": [character] SIREN identifier of the service
+#' - "type_collectivite": [character] kind of collectivity
+#' - "mode_gestion": [character] management mechanism of the service
+#' - "annee": [integer] year of the data
+#' - "indicateur": value of the indicator
+#' - "uri_indicateur": the link to the indicator documentation
+#'
+#' `get_indicateurs_services_services` returns a [tibble::tibble] with one row by commune, by service and by year and the following columns:
+#'
+#' - "code_service": [character] identifier of the service
+#' - "nom_service": [character] name of the service
+#' - "code_commune_insee": [character] identifier of the commune
+#' - "nom_commune": [character] name of the commune
+#' - "numero_siren ": [character] SIREN identifier of the service
+#' - "type_collectivite": [character] kind of collectivity
+#' - "mode_gestion": [character] management mechanism of the service
+#' - "annee": [integer] year of the data
+#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
+#'
+#' @export
+#' @rdname get_indicateurs_services
+#'
+#' @examples
+#' # Retrieve performance indicator time series in the commune of Romilly-sur-Seine
+#' get_indicateurs_services_communes(list(code_commune = "10323"))
+#'
+#' # Retrieve the drinking water withdrawal indicators of the year 2012 for all services
+#' get_indicateurs_services_indicateurs(list(code_indicateur = "D102.0", annee = "2012"))
+#'
+#' # Retrieve performance indicator time series of Romilly-sur-Seine with service details
+#' get_indicateurs_services_services(list(code_commune = "10323"))
+#'
+get_indicateurs_services_communes <- function(params,
+                                              cfg = config::get(file = system.file("config.yml",
+                                                                                   package = "hubeau"))) {
+
+  l <- doApiQuery(api = "indicateurs_services",
+                  operation = "communes",
+                  params = params,
+                  cfg = cfg)
+
+  l <- lapply(l, function(x) {
+    x <- c(x, x$indicateurs)
+    x$indicateurs <- NULL
+    x
+  })
+  convert_list_to_tibble(l)
+}
+
+#' @export
+#' @rdname get_indicateurs_services
+get_indicateurs_services_indicateurs <- function(params,
+                                                cfg = config::get(file = system.file("config.yml",
+                                                                                     package = "hubeau"))) {
+  l <- doApiQuery(api = "indicateurs_services",
+                  operation = "indicateurs",
+                  params = params,
+                  cfg = cfg)
+
+  l <- lapply(l, function(x) {
+    x$codes_commune <- NULL
+    x$noms_commune <- NULL
+    x
+  })
+  convert_list_to_tibble(l)
+}
+
+#' @export
+#' @rdname get_indicateurs_services
+get_indicateurs_services_services <- function(params,
+                                              cfg = config::get(file = system.file("config.yml",
+                                                                                   package = "hubeau"))) {
+
+  l <- doApiQuery(api = "indicateurs_services",
+                  operation = "services",
+                  params = params,
+                  cfg = cfg)
+
+  l <- lapply(l, function(x) {
+    x <- c(x, x$indicateurs)
+    x$indicateurs <- NULL
+    x
+  })
+  convert_list_to_tibble(l)
+}

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}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with one row by commune, by service and by year and the following columns:
-#'
-#' - "code_commune_insee": [character] identifier of the commune
-#' - "nom_commune": [character] name of the commune
-#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
-#' - "annee": [integer] year of the data
-#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
-#'
-#' @export
-#'
-#' @examples
-#' # Retrieve performance indicator time series of the services in Romilly-sur-Seine
-#' get_indicateurs_services_communes(list(code_commune = "10323"))
-#'
-get_indicateurs_services_communes <- function(params,
-                                              cfg = config::get(file = system.file("config.yml",
-                                                                                   package = "hubeau"))) {
-
-  l <- doApiQuery(api = "indicateurs_services",
-                  operation = "communes",
-                  params = params,
-                  cfg = cfg)
-
-  l <- lapply(l, function(x) {
-    x <- c(x, x$indicateurs)
-    x$indicateurs <- NULL
-    x
-  })
-  convert_list_to_tibble(l)
-}

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}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with one row by commune, by service and by year and the following columns:
-#'
-#' - "code_commune_insee": [character] identifier of the commune
-#' - "nom_commune": [character] name of the commune
-#' - "codes_service": [integer] identifier of the drinking water supply and/or sanitation service
-#' - "annee": [integer] year of the data
-#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
-#'
-#' @export
-#'
-#' @examples
-#' # Retrieve the withdrawal time series of the devices located in Romilly-sur-Seine
-#' get_indicateurs_services_indicateurs(list(code_indicateur = "D102.0", annee = "2012"))
-#'
-get_indicateurs_services_indicateurs <- function(params,
-                                                cfg = config::get(file = system.file("config.yml",
-                                                                                     package = "hubeau"))) {
-  l <- doApiQuery(api = "indicateurs_services",
-                  operation = "indicateurs",
-                  params = params,
-                  cfg = cfg)
-
-  l <- lapply(l, function(x) {
-    x$codes_commune <- NULL
-    x$noms_commune <- NULL
-    x
-  })
-  convert_list_to_tibble(l)
-}

R/get_indicateurs_services_services.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}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with one row by commune, by service and by year and the following columns:
-#'
-#' - "code_service": [character] identifier of the service
-#' - "nom_service": [character] name of the service
-#' - "code_commune_insee": [character] identifier of the commune
-#' - "nom_commune": [character] name of the commune
-#' - "numero_siren ": [character] SIREN identifier of the service
-#' - "type_collectivite": [character] kind of collectivity
-#' - "mode_gestion": [character] management mechanism of the service
-#' - "annee": [integer] year of the data
-#' - The following columns are the performance indicators flagged by their respective codes. The documentation of these codes can be found at this URL: \url{https://www.services.eaufrance.fr/indicateurs/indicateurs}.
-#'
-#' @export
-#'
-#' @examples
-#' # Retrieve performance indicator time series of the services in Romilly-sur-Seine
-#' get_indicateurs_services_services(list(code_commune = "10323"))
-#'
-get_indicateurs_services_services <- function(params,
-                                              cfg = config::get(file = system.file("config.yml",
-                                                                                   package = "hubeau"))) {
-
-  l <- doApiQuery(api = "indicateurs_services",
-                  operation = "services",
-                  params = params,
-                  cfg = cfg)
-
-  l <- lapply(l, function(x) {
-    x <- c(x, x$indicateurs)
-    x$indicateurs <- NULL
-    x
-  })
-  convert_list_to_tibble(l)
-}

R/get_niveaux_nappes_chroniques.R → R/get_niveaux_nappes.R

-#' Retrieve piezometric archived time series from API "Piézométrie"
+#' Retrieve data from API "Piézométrie"
+#'
+#' @description
+#' The available endpoints are:
+#'
+#' - `get_niveaux_nappes_stations` retrieves list of piezometric stations
+#' - `get_nappes_chroniques` retrieves piezometric archived time series
+#' - `get_nappes_chroniques_tr` retrieves piezometric "real time" data
 #'
 #' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-piezometrie}
 #'
 #' @template param_get_common
 #'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
+#' @rdname get_niveaux_nappes
 #' @export
 #'
 #' @examples
+#' # Retrieve the hydrometric stations in the department of Aube
+#' get_niveaux_nappes_stations(list(code_departement = "10"))
+#'
 #' # Retrieve the archived observed piezometric level at station '07548X0009/F' (old BSS identifier)
 #' # for the year 2020
 #' df <- get_niveaux_nappes_chroniques(list(code_bss = "07548X0009/F",
@@ -17,6 +27,28 @@
 #' # Plot the water elevation (NGF)
 #' plot(as.POSIXct(df$date_mesure), df$niveau_nappe_eau, type = "l")
 #'
+#' # For retrieving the last real time observed piezometric level
+#' # at station 'BSS001VZGZ' (new BSS identifier)
+#' df <- get_niveaux_nappes_chroniques_tr(list(bss_id = "BSS001VZGZ"))
+#'
+#' # Plot the water elevation (NGF)
+#' plot(as.POSIXct(df$date_mesure), df$niveau_eau_ngf, type = "l")
+#'
+get_niveaux_nappes_stations  <- function(params, cfg = config::get(file = system.file("config.yml",
+                                                                                      package = "hubeau"))) {
+  l <- doApiQuery(api = "niveaux_nappes",
+                  operation = "stations",
+                  params = params,
+                  cfg = cfg)
+  l <- lapply(l, function(x) {
+    x$geometry <- NULL
+    x
+  })
+  convert_list_to_tibble(l)
+}
+
+#' @rdname get_niveaux_nappes
+#' @export
 get_niveaux_nappes_chroniques  <- function(params,
                                    cfg = config::get(file = system.file("config.yml",
                                                         package = "hubeau"))) {
@@ -28,3 +60,17 @@ get_niveaux_nappes_chroniques  <- function(params,
   )
   convert_list_to_tibble(l)
 }
+
+#' @rdname get_niveaux_nappes
+#' @export
+get_niveaux_nappes_chroniques_tr  <- function(params,
+                                   cfg = config::get(file = system.file("config.yml",
+                                                        package = "hubeau"))) {
+  l <- doApiQuery(
+    api = "niveaux_nappes",
+    operation = "chroniques_tr",
+    params = params,
+    cfg = cfg
+  )
+  convert_list_to_tibble(l)
+}

R/get_niveaux_nappes_chroniques_tr.R

-#' Retrieve piezometric "real time" chroniques from API "Piézométrie"
-#'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-piezometrie}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by time step and by station.
-#' @export
-#'
-#' @examples
-#' # For retrieving the last real time observed piezometric level
-#' # at station 'BSS001VZGZ' (new BSS identifier)
-#' df <- get_niveaux_nappes_chroniques_tr(list(bss_id = "BSS001VZGZ"))
-#'
-#' # Plot the water elevation (NGF)
-#' plot(as.POSIXct(df$date_mesure), df$niveau_eau_ngf, type = "l")
-get_niveaux_nappes_chroniques_tr  <- function(params,
-                                   cfg = config::get(file = system.file("config.yml",
-                                                        package = "hubeau"))) {
-  l <- doApiQuery(
-    api = "niveaux_nappes",
-    operation = "chroniques_tr",
-    params = params,
-    cfg = cfg
-  )
-  convert_list_to_tibble(l)
-}

R/get_niveaux_nappes_stations.R

-#' Retrieve piezometric stations from API "Piézométrie"
-#'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-piezometrie}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by station.
-#' @export
-#'
-#' @examples
-#' # Retrieve the hydrometric stations in the department of Aube
-#' get_niveaux_nappes_stations(list(code_departement = "10"))
-#'
-get_niveaux_nappes_stations  <- function(params, cfg = config::get(file = system.file("config.yml",
-                                                                                      package = "hubeau"))) {
-  l <- doApiQuery(api = "niveaux_nappes",
-                  operation = "stations",
-                  params = params,
-                  cfg = cfg)
-  l <- lapply(l, function(x) {
-    x$geometry <- NULL
-    x
-  })
-  convert_list_to_tibble(l)
-}

R/get_prelevements_ouvrages.R → R/get_prelevements.R

-#' Retrieve withdrawal devices from API "Prélèvements en eau"
+#' Retrieve data from API "Prélèvements en eau"
+#'
+#' @description
+#' Available endpoints are:
+#'
+#' - `get_prelevements_points_prelevement` retrieves withdrawal points
+#' - `get_prelevements_ouvrages` retrieves withdrawal devices
+#' - `get_prelevements_chroniques` retrieves time series of withdrawals
 #'
 #' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau}
 #'
 #' @template param_get_common
 #'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by device.
+#' @rdname get_prelevements
 #' @export
 #'
 #' @examples
+#' # Retrieve the withdrawal points located in Romilly-sur-Seine
+#' get_prelevements_points_prelevement(list(code_commune_insee = "10323"))
+#'
 #' # Retrieve the withdrawal devices located in Romilly-sur-Seine
 #' get_prelevements_ouvrages(list(code_commune_insee = "10323"))
 #'
+#' # Retrieve the withdrawal time series of the devices located in Romilly-sur-Seine
+#' get_prelevements_chroniques(list(code_commune_insee = "10323"))
+#'
+get_prelevements_points_prelevement <- function(params, cfg = config::get(file = system.file("config.yml",
+                                                                        package = "hubeau"))) {
+  l <- doApiQuery(api = "prelevements",
+                  operation = "points_prelevement",
+                  params = params,
+                  cfg = cfg)
+
+  convert_list_to_tibble(l)
+}
+
+#' @rdname get_prelevements
+#' @export
 get_prelevements_ouvrages <- function(params, cfg = config::get(file = system.file("config.yml",
                                                                                              package = "hubeau"))) {
   l <- doApiQuery(api = "prelevements",
@@ -25,3 +50,18 @@ get_prelevements_ouvrages <- function(params, cfg = config::get(file = system.fi
 
   convert_list_to_tibble(l)
 }
+
+#' @rdname get_prelevements
+#' @export
+get_prelevements_chroniques <- function(params, cfg = config::get(file = system.file("config.yml",
+                                                                       package = "hubeau"))) {
+  l <- doApiQuery(api = "prelevements",
+                  operation = "chroniques",
+                  params = params,
+                  cfg = cfg)
+  l <- lapply(l, function(x) {
+    x$geometry <- NULL
+    x
+  })
+  convert_list_to_tibble(l)
+}

R/get_prelevements_chroniques.R

-#' Retrieve time series of withdrawals from API "Prélèvements en eau"
-#'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by device, year and usage.
-#' @export
-#'
-#' @examples
-#' # Retrieve the withdrawal time series of the devices located in Romilly-sur-Seine
-#' get_prelevements_chroniques(list(code_commune_insee = "10323"))
-#'
-get_prelevements_chroniques <- function(params, cfg = config::get(file = system.file("config.yml",
-                                                                       package = "hubeau"))) {
-  l <- doApiQuery(api = "prelevements",
-                  operation = "chroniques",
-                  params = params,
-                  cfg = cfg)
-  l <- lapply(l, function(x) {
-    x$geometry <- NULL
-    x
-  })
-  convert_list_to_tibble(l)
-}

R/get_prelevements_points_prelevement.R

-#' Retrieve withdrawal points from API "Prélèvements en eau"
-#'
-#' See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-prelevements-eau#/prelevements/prelevement}
-#'
-#' @template param_get_common
-#'
-#' @return a [tibble::tibble] with all available parameters in columns and one row by withdrawal point.
-#' @export
-#'
-#' @examples
-#' # Retrieve the withdrawal points located in Romilly-sur-Seine
-#' get_prelevements_points_prelevement(list(code_commune_insee = "10323"))
-#'
-get_prelevements_points_prelevement <- function(params, cfg = config::get(file = system.file("config.yml",
-                                                                        package = "hubeau"))) {
-  l <- doApiQuery(api = "prelevements",
-                  operation = "points_prelevement",
-                  params = params,
-                  cfg = cfg)
-
-  convert_list_to_tibble(l)
-}

man-roxygen/param_get_common.R

-#' @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 and 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
+#' @param params a [list] the list of parameters of the queries and their values in the format `list(ParamName = "Param value", ...)`, use the function [get_available_params] for a list of the available filter parameters for a given operation in an API and see the API documentation for their description
+#' @param cfg a [config] object describing the configuration of the APIs. Use the internal package configuration by default
 #'        configuration
+#'
+#' @return a [tibble::tibble] with all available parameters in columns.
+#'
+#' @seealso [doApiQuery] for more details on the API querying process.

man/convert_list_to_tibble.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/doApiQuery.R
+\name{convert_list_to_tibble}
+\alias{convert_list_to_tibble}
+\title{Convert list provided by the APIs into a tibble}
+\usage{
+convert_list_to_tibble(l)
+}
+\arguments{
+\item{l}{a \link{list} provided by the API (See \link{doApiQuery})}
+}
+\value{
+a \link[tibble:tibble]{tibble::tibble} with one row by list item and one column by list sub-item
+}
+\description{
+Convert list provided by the APIs into a tibble
+}

man/doApiQuery.Rd

@@ -21,11 +21,11 @@ get_available_params(
 \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{operation}{a \link{character} name of the endpoint, see example for available endpoints 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 \link{get_available_params} for a list of the available parameters for a given operation in an API and see the API documentation for the complete list of available filter parameters}
+\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 \link{get_available_params} for a list of the available filter parameters for a given operation in an API and see the API documentation for their description}
 
-\item{cfg}{a \link{config} object Configuration of the communication. Use by default the internal package
+\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
 configuration}
 }
 \value{