Add first batch of docs & examples

.lintr

@@ -1,2 +1,2 @@
 linters: linters_with_defaults() # see vignette("lintr")
-encoding: "UTF-8"
+encoding: "UTF-8"

NAMESPACE

@@ -1,6 +1,16 @@
 # Generated by roxygen2: do not edit by hand
 
+export(uis_get)
+export(uis_get_entities)
+export(uis_get_versions)
+export(uis_get_versions_default)
 import(cli)
 import(httr2)
 import(jsonlite)
 import(tibble)
+importFrom(dplyr,filter)
+importFrom(dplyr,mutate)
+importFrom(dplyr,rename)
+importFrom(dplyr,select)
+importFrom(tidyr,nest)
+importFrom(tidyr,unnest)

R/perform_request.R

@@ -4,7 +4,8 @@ perform_request <- function(
   resource,
   entities = NULL,
   indicators = NULL,
-  time = NULL,
+  start_year = NULL,
+  end_year = NULL,
   version = NULL,
   disaggregations = NULL,
   glossary_terms = NULL
@@ -16,11 +17,14 @@ perform_request <- function(
   req <- request(base_url) |>
     req_url_path_append(resource) |>
     req_url_query(
-      entities = entities,
-
+      geoUnit = entities,
+      indicator = indicators,
+      start = start_year,
+      end = end_year,
       version = version,
       disaggregations = disaggregations,
-      glossary_terms = glossary_terms
+      glossary_terms = glossary_terms,
+      .multi = "explode"
     )
 
   tryCatch(
@@ -41,4 +45,6 @@ perform_request <- function(
       )
     }
   )
+
+  resp
 }

R/uis_get.R

@@ -1,28 +1,131 @@
+#' Get data from the UIS API
+#'
+#' @description
+#' Retrieves data from the UNESCO Institute for Statistics (UIS) API for
+#' specified entities, indicators, and time periods.
+#'
+#' @param entities Character vector. The entity IDs (geoUnits) to retrieve data
+#'  for. Must provide either this parameter or `indicators` or both.
+#' @param indicators Character vector. The indicator IDs to retrieve data for.
+#'   Must provide either this parameter or `entities` or both.
+#' @param start_year Numeric or character. The starting year for the data
+#'  retrieval period. If NULL, no start year constraint is applied.
+#' @param end_year Numeric or character. The ending year for the data retrieval
+#'  period. If NULL, no end year constraint is applied.
+#' @param version Character. The API version to use. If NULL, the default
+#'  version is used.
+#'
+#' @return A data frame with the following columns:
+#'   \item{entity_id}{Character. The ID of the entity (geoUnit).}
+#'   \item{indicator_id}{Character. The ID of the indicator.}
+#'   \item{year}{Numeric. The year of the observation.}
+#'   \item{value}{Numeric. The value of the indicator for the given entity and
+#'  year.}
+#'
+#' @examplesIf curl::has_internet()
+#' \donttest{
+#' # Get a single indicator for all countries
+#' literacy_data <- uis_get(
+#'   indicators = "200101",
+#'   start_year = 2015,
+#'   end_year = 2020
+#' )
+#'
+#' # Get multiple indicators for a single country
+#' uis_get(
+#'   entities = "BRA",
+#'   indicators = c("GER.1", "NER.1", "CR.1"),
+#'   start_year = 2010,
+#'   end_year = 2020
+#' )
+#' }
+#'
+#' @seealso
+#' \link{uis_get_entities} for retrieving available geographical entities and
+#' \link{uis_get_versions} for retrieving available API versions
+#'
+#' @export
 uis_get <- function(
   entities = NULL,
   indicators = NULL,
   start_year = NULL,
   end_year = NULL,
   version = NULL
 ) {
-  # TODO: at least entities or indicators must be given
+  if (is.null(entities) && is.null(indicators)) {
+    cli::cli_abort(
+      c(
+        "!" = "At least {.arg entities} or {.arg indicators} must be provided."
+      )
+    )
+  }
 
-  # TODO: add parameter validation
+  validate_character_vector(indicators, "indicators")
+  validate_character_vector(entities, "entities")
+  validate_year(start_year, "end_year")
+  validate_year(end_year, "end_year")
+  validate_version(version)
 
-  # TODO: add support for parameters
-  resp <- perform_request("data/indicators")
+  resp <- perform_request(
+    "data/indicators",
+    entities = entities,
+    indicators = indicators,
+    start_year = start_year,
+    end_year = end_year,
+    version = version
+  )
 
   data_raw <- resp |>
     resp_body_json(simplifyVector = TRUE)
 
-  data <- data_raw$records |>
-    as_tibble() |>
-    dplyr::select(
-      entity_id = geoUnit,
-      indicator_id = indicatorId,
-      year,
-      value
+  records <- data_raw$records
+
+  print(length(records))
+  if (length(records) == 0) {
+    cli::cli_inform(
+      c("i" = "No records found for this query.")
     )
+    return(invisible(NULL))
+  } else {
+    data <- records |>
+      as_tibble() |>
+      dplyr::select(
+        "entity_id" = "geoUnit",
+        "indicator_id" = "indicatorId",
+        "year",
+        "value"
+      )
+    return(data)
+  }
+}
+
+#' @noRd
+#' @keywords internal
+validate_character_vector <- function(arg, arg_name) {
+  if (!is.null(arg)) {
+    if (!is.character(arg) || any(is.na(arg))) {
+      cli::cli_abort(
+        c(
+          "!" = paste(
+            "{.arg {arg_name}} must be a character vector and cannot contain ",
+            "NA values."
+          )
+        )
+      )
+    }
+  }
+}
 
-  data
+#' @noRd
+#' @keywords internal
+validate_year <- function(year, arg_name) {
+  if (!is.null(year)) {
+    if (!is.numeric(year)) {
+      cli::cli_abort(
+        c(
+          "!" = paste("{.arg {arg_name}} must be an integer.")
+        )
+      )
+    }
+  }
 }

R/uis_get_entities.R

@@ -1,20 +1,51 @@
+#' Get geographical entities from UIS API
+#'
+#' @description
+#' Retrieves information about geographical entities (countries, regions, etc.)
+#' available in the UNESCO Institute for Statistics (UIS) API.
+#'
+#' @param version Character. The API version to use. If NULL (default), the
+#'  API's default version will be used.
+#'
+#' @return A data frame with information about geographical entities:
+#'   \item{entity_id}{Character. The unique identifier for the entity.}
+#'   \item{entity_name}{Character. The name of the geographical entity.}
+#'   \item{entity_typ}{Character. The type of entity (e.g., country, region).}
+#'   \item{region_group}{Character or list. Information about the region
+#' grouping.}
+#'
+#' @examples
+#' \donttest{
+#' uis_get_entities()
+#'
+#' # Download entities for a specific version
+#' uis_get_entities("20250225-2ae60fad")
+#' }
+#'
+#' @seealso
+#' \link{uis_get_versions} for retrieving available API versions and
+#' \link{uis_get_versions_default} for getting the default API version
+#'
+#' @export
 uis_get_entities <- function(
   version = NULL
 ) {
-  # TODO: add parameter validation
+  validate_version(version)
 
-  # TODO: add support for parameters
-  resp <- perform_request("definitions/geounits")
+  resp <- perform_request(
+    "definitions/geounits",
+    version = version
+  )
 
   entities_raw <- resp_body_json(resp) |>
     dplyr::bind_rows()
 
   entities <- entities_raw |>
     dplyr::rename(
-      entity_id = id,
-      entity_name = name,
-      entity_typ = type,
-      region_group = regionGroup
+      "entity_id" = "id",
+      "entity_name" = "name",
+      "entity_typ" = "type",
+      "region_group" = "regionGroup"
     )
 
   entities <- convert_to_snake_case(entities)

R/uis_get_indicators.R

@@ -3,20 +3,23 @@ uis_get_indicators <- function(
   disaggregations = NULL,
   glossary_terms = NULL
 ) {
-  # TODO: add parameter validation
+  validate_version(version)
 
   # TODO: add support for parameters
-  resp <- perform_request("definitions/indicators")
+  resp <- perform_request(
+    "definitions/indicators",
+    version = version
+  )
 
   indicators_raw <- resp_body_json(resp, simplifyVector = TRUE) |>
     as_tibble()
 
   # TODO: rename columns and nest them again afterwards with new names
   indicators <- indicators_raw |>
-    tidyr::unnest(dataAvailability) |>
-    tidyr::unnest(timeLine) |>
-    tidyr::unnest(geoUnits) |>
-    tidyr::unnest(types)
+    tidyr::unnest("dataAvailability") |>
+    tidyr::unnest("timeLine") |>
+    tidyr::unnest("geoUnits") |>
+    tidyr::unnest("types")
 
   indicators <- convert_to_snake_case(indicators)