diff --git a/R/doApiQuery.R b/R/doApiQuery.R
index 455420137db1e6ad2887f5a7a2d2f177064b2837..e42152104e7d1193ab32130849829dca2c99fe9f 100644
--- a/R/doApiQuery.R
+++ b/R/doApiQuery.R
@@ -1,15 +1,13 @@
-#' Main internal functions for querying the Hub'eau APIs
+#' Main internal functions for querying the Hub'eau API endpoints
#'
-#' The function `doQueryApi` is called by all the function querying the APIs and return the raw data sent by the API.
+#' The function `doQueryApi` is called by all the function querying the API endpoints and return the raw data sent by the endpoint.
#' 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])
+#' @details The functions `get_[api]_[endpoint]` 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 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 endpoint 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 API endpoint 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
#'
@@ -23,26 +21,26 @@
#' names(cfg$apis)
#'
#' # To get the available endpoints in an API
-#' names(cfg$apis[["prelevements"]]$operations)
+#' names(cfg$apis[["prelevements"]]$endpoints)
#'
-#' # To get available parameters in operation "chroniques" of the API "prelevements"
-#' get_available_params(api = "prelevements", operation = "chroniques")
+#' # To get available parameters in endpoint "chroniques" of the API "prelevements"
+#' get_available_params(api = "prelevements", endpoint = "chroniques")
#'
-#' # To query the operation "chroniques" of the API "prelevements"
+#' # To query the endpoint "chroniques" of the API "prelevements"
#' # on all devices in the commune of Romilly-sur-Seine in 2018
#' doApiQuery(api = "prelevements",
-#' operation = "chroniques",
+#' endpoint = "chroniques",
#' params = list(code_commune_insee = "10323", annee = "2018"))
doApiQuery <- function(api,
- operation,
+ endpoint,
params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))) {
- availableParams <- get_available_params(api, operation, cfg)
+ availableParams <- get_available_params(api, endpoint, cfg)
query <-
- file.path(cfg$api_url, cfg$apis[[api]]$path, cfg$apis[[api]]$operations[[operation]]$path)
+ file.path(cfg$api_url, cfg$apis[[api]]$path, cfg$apis[[api]]$endpoints[[endpoint]]$path)
for (paramName in names(params)) {
- if (!paramName %in% cfg$apis[[api]]$operations[[operation]]$fields) {
+ if (!paramName %in% cfg$apis[[api]]$endpoints[[endpoint]]$fields) {
stop(
sprintf(
"The parameter '%s' is not available for this query. ",
@@ -52,7 +50,7 @@ doApiQuery <- function(api,
sprintf(
"Run `hubeau::get_available_params(\"%s\", \"%s\")` to get available parameters.",
api,
- operation
+ endpoint
)
)
}
diff --git a/R/get_available_params.R b/R/get_available_params.R
index 55a2a632ed2b123315121d23a6e28c6a32115319..f88e76fbe68100bc2e31d4494497a48690e12e91 100644
--- a/R/get_available_params.R
+++ b/R/get_available_params.R
@@ -8,14 +8,14 @@
#' @inherit doApiQuery examples
#'
get_available_params <- function(api,
- operation,
+ endpoint,
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")
+ if (is.null(cfg$apis[[api]]$endpoints[[endpoint]])) {
+ stop("The endpoint '", endpoint, "' is not available for this API, or is not implemented in the package")
}
- cfg$apis[[api]]$operations[[operation]]$fields
+ cfg$apis[[api]]$endpoints[[endpoint]]$fields
}
diff --git a/R/get_hydrometrie.R b/R/get_hydrometrie.R
index cae435b9f6164b217e6652ba9432c446a491b98d..762e3d05a196c1d9f423127a471a140a482f65b6 100644
--- a/R/get_hydrometrie.R
+++ b/R/get_hydrometrie.R
@@ -47,7 +47,7 @@ get_hydrometrie_obs_elab <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "hydrometrie",
- operation = "obs_elab",
+ endpoint = "obs_elab",
params = params,
cfg = cfg
)
@@ -68,7 +68,7 @@ get_hydrometrie_observations_tr <- function(params,
l <- doApiQuery(
api = "hydrometrie",
- operation = "observations_tr",
+ endpoint = "observations_tr",
params = params,
cfg = cfg
)
@@ -101,7 +101,7 @@ get_hydrometrie_sites <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "hydrometrie",
- operation = "sites",
+ endpoint = "sites",
params = params,
cfg = cfg
)
@@ -148,7 +148,7 @@ get_hydrometrie_sites <- function(params,
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",
+ endpoint = "stations",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
diff --git a/R/get_indicateurs_services.R b/R/get_indicateurs_services.R
index 0e3efe659c290cf98f96be97f9e3f77eee8d4ca1..a363c189550407fc464443e701f79d37a95d562c 100644
--- a/R/get_indicateurs_services.R
+++ b/R/get_indicateurs_services.R
@@ -67,7 +67,7 @@ get_indicateurs_services_communes <- function(params,
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
- operation = "communes",
+ endpoint = "communes",
params = params,
cfg = cfg)
@@ -85,7 +85,7 @@ get_indicateurs_services_indicateurs <- function(params,
cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
- operation = "indicateurs",
+ endpoint = "indicateurs",
params = params,
cfg = cfg)
@@ -104,7 +104,7 @@ get_indicateurs_services_services <- function(params,
package = "hubeau"))) {
l <- doApiQuery(api = "indicateurs_services",
- operation = "services",
+ endpoint = "services",
params = params,
cfg = cfg)
diff --git a/R/get_niveaux_nappes.R b/R/get_niveaux_nappes.R
index 371b6be92756aeba54685867e551f03e8633a464..b3a2d9185c79f63cf384f1d577f2868426253ae1 100644
--- a/R/get_niveaux_nappes.R
+++ b/R/get_niveaux_nappes.R
@@ -37,7 +37,7 @@
get_niveaux_nappes_stations <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "niveaux_nappes",
- operation = "stations",
+ endpoint = "stations",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
@@ -54,7 +54,7 @@ get_niveaux_nappes_chroniques <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "niveaux_nappes",
- operation = "chroniques",
+ endpoint = "chroniques",
params = params,
cfg = cfg
)
@@ -68,7 +68,7 @@ get_niveaux_nappes_chroniques_tr <- function(params,
package = "hubeau"))) {
l <- doApiQuery(
api = "niveaux_nappes",
- operation = "chroniques_tr",
+ endpoint = "chroniques_tr",
params = params,
cfg = cfg
)
diff --git a/R/get_prelevements.R b/R/get_prelevements.R
index a6224f614c3c912b3c94a5a4545863039b6cdcc8..e0883edfee8267773f7742d9d50e12e94fc7d51e 100644
--- a/R/get_prelevements.R
+++ b/R/get_prelevements.R
@@ -27,7 +27,7 @@
get_prelevements_points_prelevement <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "prelevements",
- operation = "points_prelevement",
+ endpoint = "points_prelevement",
params = params,
cfg = cfg)
@@ -39,7 +39,7 @@ get_prelevements_points_prelevement <- function(params, cfg = config::get(file =
get_prelevements_ouvrages <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "prelevements",
- operation = "ouvrages",
+ endpoint = "ouvrages",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
@@ -56,7 +56,7 @@ get_prelevements_ouvrages <- function(params, cfg = config::get(file = system.fi
get_prelevements_chroniques <- function(params, cfg = config::get(file = system.file("config.yml",
package = "hubeau"))) {
l <- doApiQuery(api = "prelevements",
- operation = "chroniques",
+ endpoint = "chroniques",
params = params,
cfg = cfg)
l <- lapply(l, function(x) {
diff --git a/R/hubeau.R b/R/hubeau.R
index 78cd22d07b327193bfdf0f7f627d13e30e0b8253..df2ded4b1664b50a0302b2971851201b2a53fc1a 100644
--- a/R/hubeau.R
+++ b/R/hubeau.R
@@ -1,8 +1,9 @@
#' 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]`.
+#' The 'hubeau' package provides functions for "Hub'eau" APIs and their related endpoints.
+#' These functions are named as follow: `hubeau::get_[API]_[endpoint]`.
#'
-#' Currently available APIs and related "operations" are listed below.
+#' Currently available APIs and related endpoints are listed below.
#'
#' **API "Hydrométrie"**
#'
@@ -10,9 +11,10 @@
#'
#' Available functions:
#'
-#' - [get_hydrometrie_observations_tr]: hydrometry water level and discharge time series
#' - [get_hydrometrie_sites]: hydrometry sites (can contain several stations)
#' - [get_hydrometrie_stations]: hydrometry stations
+#' - [get_hydrometrie_observations_tr]: hydrometry water level and discharge time series
+#' - [get_hydrometrie_obs_elab]: hydrometric elaborate observations (daily/monthly mean flow)
#'
#' **API "Indicateurs des services"**
#'
diff --git a/inst/config.yml b/inst/config.yml
index 628a16269e3feec2b16f71ac9ceed5d4861e4a65..318f6f8a523aa67318fb4dc774b4f827498d49d3 100644
--- a/inst/config.yml
+++ b/inst/config.yml
@@ -3,7 +3,7 @@ default:
apis:
prelevements:
path: v1/prelevements
- operations:
+ endpoints:
points_prelevement:
path: referentiel/points_prelevement
fields:
@@ -71,7 +71,7 @@ default:
- nom_ouvrage
indicateurs_services:
path: v0/indicateurs_services
- operations:
+ endpoints:
communes:
path: communes
fields:
@@ -97,7 +97,7 @@ default:
- type_service
hydrometrie:
path: v1/hydrometrie
- operations:
+ endpoints:
stations:
path: referentiel/stations
fields:
@@ -167,7 +167,7 @@ default:
- resultat_min
niveaux_nappes:
path: v1/niveaux_nappes
- operations:
+ endpoints:
chroniques:
path: chroniques
fields:
diff --git a/man-roxygen/param_get_common.R b/man-roxygen/param_get_common.R
index e7d4259fc081da771b60d2afb5edec2a7b61b91f..80831c4dab1252ec2749f9a61622cc2ae804f6ea 100644
--- a/man-roxygen/param_get_common.R
+++ b/man-roxygen/param_get_common.R
@@ -1,4 +1,4 @@
-#' @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 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 query parameters for a given API endpoint and see the API documentation for their descriptions
#' @param cfg a [config] object describing the configuration of the APIs. Use the internal package configuration by default
#' configuration
#'
diff --git a/man/doApiQuery.Rd b/man/doApiQuery.Rd
index fc2627150d3527d7d24e52f7cce6d8274ac59981..4f13b74da24c3e29ea2d7eb5238d60fd900c2b10 100644
--- a/man/doApiQuery.Rd
+++ b/man/doApiQuery.Rd
@@ -2,11 +2,11 @@
% Please edit documentation in R/doApiQuery.R
\name{doApiQuery}
\alias{doApiQuery}
-\title{Main internal functions for querying the Hub'eau APIs}
+\title{Main internal functions for querying the Hub'eau API endpoints}
\usage{
doApiQuery(
api,
- operation,
+ endpoint,
params,
cfg = config::get(file = system.file("config.yml", package = "hubeau"))
)
@@ -14,9 +14,9 @@ doApiQuery(
\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 endpoint, see example for available endpoints in an API}
+\item{endpoint}{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 filter parameters for a given operation in an API and see the API documentation for their description}
+\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 API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
@@ -25,13 +25,11 @@ configuration}
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.
+The function \code{doQueryApi} is called by all the function querying the API endpoints and return the raw data sent by the endpoint.
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:tibble]{tibble::tibble})
+The functions \verb{get_[api]_[endpoint]} call the function \code{doQueryApi} and convert the response in a convenient format for the user (\link{data.frame} or \link[tibble:tibble]{tibble::tibble})
}
\examples{
# To get the available APIs in the package
@@ -39,14 +37,14 @@ cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
names(cfg$apis)
# To get the available endpoints in an API
-names(cfg$apis[["prelevements"]]$operations)
+names(cfg$apis[["prelevements"]]$endpoints)
-# To get available parameters in operation "chroniques" of the API "prelevements"
-get_available_params(api = "prelevements", operation = "chroniques")
+# To get available parameters in endpoint "chroniques" of the API "prelevements"
+get_available_params(api = "prelevements", endpoint = "chroniques")
-# To query the operation "chroniques" of the API "prelevements"
+# To query the endpoint "chroniques" of the API "prelevements"
# on all devices in the commune of Romilly-sur-Seine in 2018
doApiQuery(api = "prelevements",
- operation = "chroniques",
+ endpoint = "chroniques",
params = list(code_commune_insee = "10323", annee = "2018"))
}
diff --git a/man/get_available_params.Rd b/man/get_available_params.Rd
index 95040b2df949a5d44ae768b8ee0dde7ead544fb1..d1a3dceec69fcf1935f647fe40b9a9ee7f3875cd 100644
--- a/man/get_available_params.Rd
+++ b/man/get_available_params.Rd
@@ -6,14 +6,14 @@
\usage{
get_available_params(
api,
- operation,
+ endpoint,
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 endpoint, see example for available endpoints in an API}
+\item{endpoint}{a \link{character} name of the endpoint, see example for available endpoints in an API}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
@@ -30,14 +30,14 @@ cfg <- config::get(file = system.file("config.yml", package = "hubeau"))
names(cfg$apis)
# To get the available endpoints in an API
-names(cfg$apis[["prelevements"]]$operations)
+names(cfg$apis[["prelevements"]]$endpoints)
-# To get available parameters in operation "chroniques" of the API "prelevements"
-get_available_params(api = "prelevements", operation = "chroniques")
+# To get available parameters in endpoint "chroniques" of the API "prelevements"
+get_available_params(api = "prelevements", endpoint = "chroniques")
-# To query the operation "chroniques" of the API "prelevements"
+# To query the endpoint "chroniques" of the API "prelevements"
# on all devices in the commune of Romilly-sur-Seine in 2018
doApiQuery(api = "prelevements",
- operation = "chroniques",
+ endpoint = "chroniques",
params = list(code_commune_insee = "10323", annee = "2018"))
}
diff --git a/man/get_hydrometrie.Rd b/man/get_hydrometrie.Rd
index 597564e8425c65336c9477edd750f5aa69faf1c4..730ee7df2b458718f14087edc6e2ec1388fef3f6 100644
--- a/man/get_hydrometrie.Rd
+++ b/man/get_hydrometrie.Rd
@@ -31,7 +31,7 @@ get_hydrometrie_stations(
)
}
\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 filter parameters for a given operation in an API and see the API documentation for their description}
+\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 query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
diff --git a/man/get_indicateurs_services.Rd b/man/get_indicateurs_services.Rd
index 65936f9b3fc1c12b535b2ccfaffa01cca428be53..7be6c5b654cb53b67a6b6606d8f3786050ea5b11 100644
--- a/man/get_indicateurs_services.Rd
+++ b/man/get_indicateurs_services.Rd
@@ -22,7 +22,7 @@ get_indicateurs_services_services(
)
}
\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 filter parameters for a given operation in an API and see the API documentation for their description}
+\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 query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
diff --git a/man/get_niveaux_nappes.Rd b/man/get_niveaux_nappes.Rd
index 66952288ae27c4aa0c4eddcee5489c0b0e55f768..37bbb9e14566651bead46c319a1eb7c3541fd1b9 100644
--- a/man/get_niveaux_nappes.Rd
+++ b/man/get_niveaux_nappes.Rd
@@ -22,7 +22,7 @@ get_niveaux_nappes_chroniques_tr(
)
}
\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 filter parameters for a given operation in an API and see the API documentation for their description}
+\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 query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
diff --git a/man/get_prelevements.Rd b/man/get_prelevements.Rd
index 096d8673b8e39d0b51628621931b128919139f21..87f4e89d219c6805221c61378c9b8847c3ebef90 100644
--- a/man/get_prelevements.Rd
+++ b/man/get_prelevements.Rd
@@ -22,7 +22,7 @@ get_prelevements_chroniques(
)
}
\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 filter parameters for a given operation in an API and see the API documentation for their description}
+\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 query parameters for a given API endpoint and see the API documentation for their description}
\item{cfg}{a \link{config} object describing the configuration of the APIs. Use the internal package configuration by default
configuration}
diff --git a/man/hubeau.Rd b/man/hubeau.Rd
index 52bc3f5ccade95d0d36a3d3d9f12efe827be88f2..dcf61dcde71906c8f1255cfdcd2475b8bfda6aee 100644
--- a/man/hubeau.Rd
+++ b/man/hubeau.Rd
@@ -5,10 +5,11 @@
\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]}.
+The 'hubeau' package provides functions for "Hub'eau" APIs and their related endpoints.
+These functions are named as follow: \verb{hubeau::get_[API]_[endpoint]}.
}
\details{
-Currently available APIs and related "operations" are listed below.
+Currently available APIs and related endpoints are listed below.
\strong{API "Hydrométrie"}
@@ -16,9 +17,10 @@ API documentation: \url{https://hubeau.eaufrance.fr/page/api-hydrometrie}
Available functions:
\itemize{
-\item \link{get_hydrometrie_observations_tr}: hydrometry water level and discharge time series
\item \link{get_hydrometrie_sites}: hydrometry sites (can contain several stations)
\item \link{get_hydrometrie_stations}: hydrometry stations
+\item \link{get_hydrometrie_observations_tr}: hydrometry water level and discharge time series
+\item \link{get_hydrometrie_obs_elab}: hydrometric elaborate observations (daily/monthly mean flow)
}
\strong{API "Indicateurs des services"}