feat: add `get_hydrometrie_sites`

Refs #7

NAMESPACE

@@ -2,6 +2,7 @@
 
 export(doApiQuery)
 export(get_available_params)
+export(get_hydrometrie_sites)
 export(get_hydrometrie_stations)
 export(get_indicateurs_services_communes)
 export(get_indicateurs_services_indicateurs)

R/get_hydrometrie_sites.R

+#' Retrieve hydrometric sites 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 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
+#'
+#' @examples
+#' # For retrieving the hydrometric sites in the department of Aube
+#' get_hydrometrie_sites(list(code_departement = "10"))
+#'
+#' # 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)
+#'
+get_hydrometrie_sites  <- function(params,
+                                   unique_site = TRUE,
+                                   cfg = config::get(file = system.file("config.yml",
+                                                        package = "hubeau"))) {
+  l <- doApiQuery(
+    api = "hydrometrie",
+    operation = "sites",
+    params = params,
+    cfg = cfg
+  )
+  l <- lapply(l, function(x) {
+    fields <-
+      c(
+        "code_commune_site",
+        "libelle_commune",
+        "code_departement",
+        "code_region",
+        "libelle_region",
+        "libelle_departement"
+      )
+    bFirst <- TRUE
+    for (field in fields) {
+      fieldValue <- unique(unlist(x[[field]]))
+      if (unique_site && length(fieldValue) > 1) {
+        if(bFirst) {
+          warning(
+            "The site '",
+            x$code_site,
+            "' has ",
+            length(fieldValue),
+            " different locations, only the first one is returned",
+            call. = FALSE
+          )
+          bFirst <- FALSE
+        }
+        fieldValue <- x[[field]][[1]]
+      }
+      x[[field]] <- fieldValue
+    }
+    x$geometry <- NULL
+    x
+  })
+  convert_list_to_tibble(l)
+}

R/hubeau.R

@@ -10,6 +10,7 @@
 #'
 #' Available functions:
 #'
+#' - [get_hydrometrie_sites]
 #' - [get_hydrometrie_stations]
 #'
 #' **API "Indicateurs des services"**

inst/config.yml

@@ -119,3 +119,20 @@ default:
             - libelle_site
             - libelle_station
             - longitude
+        sites:
+          path: referentiel/sites
+          fields:
+            - bbox
+            - code_commune_site
+            - code_cours_eau
+            - code_departement
+            - code_region
+            - code_site
+            - code_troncon_hydro_site
+            - code_zone_hydro_site
+            - distance
+            - fields
+            - latitude
+            - libelle_cours_eau
+            - libelle_site
+            - longitude

man/get_hydrometrie_sites.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/get_hydrometrie_sites.R
+\name{get_hydrometrie_sites}
+\alias{get_hydrometrie_sites}
+\title{Retrieve hydrometric sites from API "Hydrométrie"}
+\usage{
+get_hydrometrie_sites(
+  params,
+  unique_site = TRUE,
+  cfg = config::get(file = system.file("config.yml", package = "hubeau"))
+)
+}
+\arguments{
+\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{unique_site}{optional \link{logical}, if set to \code{FALSE} sites with several different locations produce one row by different location otherwise the first location found is used for fields \code{code_commune_site}, \code{libelle_commune}, \code{code_departement}, \code{code_region}, \code{libelle_region}, \code{libelle_departement}}
+
+\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 all available parameters in columns and one row by device, year and usage.
+}
+\description{
+See the API documentation for available filter parameters: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
+}
+\examples{
+# For retrieving the hydrometric sites in the department of Aube
+get_hydrometrie_sites(list(code_departement = "10"))
+
+# 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)
+
+}

man/hubeau.Rd

@@ -16,6 +16,7 @@ API documentation: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
 
 Available functions:
 \itemize{
+\item \link{get_hydrometrie_sites}
 \item \link{get_hydrometrie_stations}
 }