Review documentation

.Rbuildignore

@@ -5,4 +5,5 @@
 ^pkgdown$
 ^\.github$
 .lintr
-cran-comments.md
+cran-comments.md
+^cran-comments\.md$

DESCRIPTION

@@ -7,7 +7,9 @@ Authors@R: c(
             comment = c(ORCID = "0009-0004-0423-6819"))
     )
 Description: Retrieve data from the UNESCO Institute for Statistics (UIS) API
-    <https://api.uis.unesco.org/api/public/documentation/>. 
+    <https://api.uis.unesco.org/api/public/documentation/>. UIS provides public 
+    access to more than 4,000 indicators focusing on education, science and
+    technology, culture, and communication.
 License: MIT + file LICENSE
 Depends: 
     R (>= 4.1)

R/uis_bulk_files.R

@@ -7,7 +7,7 @@
 #' @return A data frame with information about files:
 #'   \item{file_name}{Character. The name of the data set.}
 #'   \item{file_url}{Character. The URL of the data set.}
-#'   \item{last_updated}{Character. Information about last update.}
+#'   \item{last_updated_description}{Character. Information about last update.}
 #'
 #' @examples
 #' \donttest{
@@ -61,17 +61,17 @@ uis_bulk_files <- function() {
   files <- tibble(
     file_name = resources$title,
     file_url = resources$url,
-    last_updated = resources$lastUpdated
+    last_updated_description = resources$lastUpdated
   ) |>
     dplyr::filter(grepl(".zip", .data$file_url))
 
-  files$last_updated <- sub(
+  files$last_updated_description <- sub(
     "^.*last update: ([A-Za-z]+ \\d{4}).*$",
     "\\1",
-    files$last_updated
+    files$last_updated_description
   )
 
-  files$last_updated[files$last_updated == ""] <- NA
+  files$last_updated_description[files$last_updated_description == ""] <- NA
 
   files
 }

R/uis_get.R

@@ -4,16 +4,19 @@
 #' 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 entities Character vector. The entity IDs (ISO 3166-1 alpha-3 codes)
+#'  to retrieve data for. Must provide either this parameter or `indicators` or
+#'  both. See \link{uis_get_entities} for a list of supported entities.
 #' @param indicators Character vector. The indicator IDs to retrieve data for.
-#'   Must provide either this parameter or `entities` or both.
+#'   Must provide either this parameter or `entities` or both. See
+#' \link{uis_get_indicators} for a list of supported indicators.
 #' @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.
+#'  version is used. See \link{uis_get_versions} for a list of supported
+#'  versions.
 #'
 #' @return A data frame with the following columns:
 #'   \item{entity_id}{Character. The ID of the entity (geoUnit).}
@@ -49,10 +52,6 @@
 #' )
 #' }
 #'
-#' @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,

R/uis_get_entities.R

@@ -5,13 +5,14 @@
 #' 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.
+#'  API's default version will be used. See \link{uis_get_versions} for a list
+#'  of supported versions.
 #'
 #' @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
+#'   \item{entity_type}{Character. The type of entity (e.g., country, region).}
+#'   \item{region_group}{Character. Information about the region
 #' grouping.}
 #'
 #' @examples
@@ -23,9 +24,6 @@
 #' uis_get_entities("20240910-b5ad4d82")
 #' }
 #'
-#' @seealso
-#' \link{uis_get_versions} for retrieving available API versions.
-#'
 #' @export
 uis_get_entities <- function(
   version = NULL

R/uis_get_indicators.R

@@ -2,11 +2,11 @@
 #'
 #' @description
 #' Retrieves information about indicators available in the UNESCO Institute for
-#' Statistics (UIS) API, including their definitions, data availability, and
-#' associated metadata.
+#' Statistics (UIS) API.
 #'
 #' @param version Character. The API version to use. If NULL (default), the
-#'  API's default version will be used.
+#'  API's default version will be used. See \link{uis_get_versions} for a list
+#'  of supported versions.
 #' @param disaggregations Logical. If TRUE, includes disaggregation information
 #'  for indicators. Default is FALSE.
 #' @param glossary_terms Logical. If TRUE, includes glossary terms associated
@@ -15,6 +15,10 @@
 #' @return A data frame with information about indicators:
 #'   \item{indicator_id}{Character. The unique identifier for the indicator.}
 #'   \item{indicator_name}{Character. The name of the indicator.}
+#'   \item{theme}{Character. The theme of the indicator.}
+#'   \item{last_data_update}{Date. The last update date.}
+#'   \item{last_data_update_description}{Character. A description about the
+#'  last update date.}
 #'   \item{data_availability}{List column. Contains nested information about
 #'  data availability, including total record count and timeline min/max years.}
 #'   \item{entity_types}{List column. Contains information about entity types
@@ -29,9 +33,6 @@
 #' uis_get_indicators(disaggregations = TRUE, glossary_terms = TRUE)
 #' }
 #'
-#' @seealso
-#' \code{uis_get_versions} for retrieving available API versions.
-#'
 #' @export
 uis_get_indicators <- function(
   version = NULL,
@@ -127,6 +128,9 @@ uis_get_indicators <- function(
     ) |>
     tidyr::nest(
       "entity_types" = "entity_types"
+    ) |>
+    dplyr::mutate(
+      last_data_update = as.Date(.data$last_data_update)
     )
 
   if (disaggregations || glossary_terms) {

R/uis_get_versions.R

@@ -2,11 +2,10 @@
 #'
 #' @description
 #' Retrieves information about the available versions of the UNESCO Institute
-#' for Statistics (UIS) API, including version IDs, descriptions, and theme
-#' data.
+#' for Statistics (UIS) API.
 #'
-#' @param default Logical. Indicates whether only the current default version
-#'  should be retrievend. Defaults to FALSE.
+#' @param default_only Logical. Indicates whether only the current default
+#'  version should be retrievend. Defaults to FALSE.
 #'
 #' @return A data frame with the following columns:
 #'   \item{version}{Character. The version identifier.}
@@ -22,8 +21,8 @@
 #' }
 #'
 #' @export
-uis_get_versions <- function(default = FALSE) {
-  if (default) {
+uis_get_versions <- function(default_only = FALSE) {
+  if (default_only) {
     resp <- perform_request("versions/default")
   } else {
     resp <- perform_request("versions")

README.Rmd

@@ -21,15 +21,23 @@ knitr::opts_chunk$set(
 [![Codecov test coverage](https://codecov.io/gh/tidy-intelligence/r-uisapi/graph/badge.svg)](https://app.codecov.io/gh/tidy-intelligence/r-uisapi)
 <!-- badges: end -->
 
-Retrieve data from the [UNESCO Institute for Statistics (UIS) API](https://api.uis.unesco.org/api/public/documentation/).
+Retrieve data from the [UNESCO Institute for Statistics (UIS) API](https://api.uis.unesco.org/api/public/documentation/). UIS provides public access to more than 4,000 indicators focusing on education, science and technology, culture, and communication.
 
 The package is part of the [econdataverse](https://www.econdataverse.org/) family of packages aimed at helping economists and financial professionals work with sovereign-level economic data.
 
+ > 💡 The UIS API has no known rate limiting, but there is a 100,000 record limit for each request. For larger data downloads, the UIS recommends its [Bulk Data Download Service (BDDS)](https://databrowser.uis.unesco.org/resources/bulk.
+
 ## Installation
 
-You can install the development version of `uisapi` from GitHub with:
+You can install `uisapi` from CRAN via:
 
+```{r eval=FALSE}
+install.packages("uisapi")
 ```
+
+You can install the development version of `uisapi` from GitHub with:
+
+```{r eval=FALSE}
 # install.packages("pak")
 pak::pak("tidy-intelligence/r-uisapi")
 ```
@@ -71,10 +79,10 @@ The API supports versioning and you can retrieve all versions using:
 uis_get_versions()
 ```
 
-If you are only interested in the current default version, you can use the parameter `default`:
+If you are only interested in the current default version, you can use the parameter `default_only`:
 
 ```{r}
-uis_get_versions(default = TRUE)
+uis_get_versions(default_only = TRUE)
 ```
 
 The API will only return 100,000 records for each query, if more data is requested, the API call with fail with a 400 http status code. If you need more data, then UIS recommends using the [Bulk Data Download Service (BDDS)](https://databrowser.uis.unesco.org/resources/bulk). You can get a list of available files via:

README.md

@@ -13,19 +13,34 @@ coverage](https://codecov.io/gh/tidy-intelligence/r-uisapi/graph/badge.svg)](htt
 <!-- badges: end -->
 
 Retrieve data from the [UNESCO Institute for Statistics (UIS)
-API](https://api.uis.unesco.org/api/public/documentation/).
+API](https://api.uis.unesco.org/api/public/documentation/). UIS provides
+public access to more than 4,000 indicators focusing on education,
+science and technology, culture, and communication.
 
 The package is part of the
 [econdataverse](https://www.econdataverse.org/) family of packages aimed
 at helping economists and financial professionals work with
 sovereign-level economic data.
 
+> 💡 The UIS API has no known rate limiting, but there is a 100,000
+> record limit for each request. For larger data downloads, the UIS
+> recommends its \[Bulk Data Download Service
+> (BDDS)\](<https://databrowser.uis.unesco.org/resources/bulk>.
+
 ## Installation
 
+You can install `uisapi` from CRAN via:
+
+``` r
+install.packages("uisapi")
+```
+
 You can install the development version of `uisapi` from GitHub with:
 
-    # install.packages("pak")
-    pak::pak("tidy-intelligence/r-uisapi")
+``` r
+# install.packages("pak")
+pak::pak("tidy-intelligence/r-uisapi")
+```
 
 ## Usage
 
@@ -86,7 +101,7 @@ The list of available indicators can be retrieved via:
 uis_get_indicators()
 #> # A tibble: 4,247 × 7
 #>    indicator_id indicator_name     theme last_data_update last_data_update_des…¹
-#>    <chr>        <chr>              <chr> <chr>            <chr>                 
+#>    <chr>        <chr>              <chr> <date>           <chr>                 
 #>  1 10           Official entrance… EDUC… 2025-02-23       February 2025 Data Re…
 #>  2 10403        Start month of th… EDUC… 2025-02-23       February 2025 Data Re…
 #>  3 10404        End month of the … EDUC… 2025-02-23       February 2025 Data Re…
@@ -118,10 +133,10 @@ uis_get_versions()
 ```
 
 If you are only interested in the current default version, you can use
-the parameter `default`:
+the parameter `default_only`:
 
 ``` r
-uis_get_versions(default = TRUE)
+uis_get_versions(default_only = TRUE)
 #> # A tibble: 1 × 4
 #>   version           publication_date    description      theme           
 #>   <chr>             <dttm>              <chr>            <list>          
@@ -137,19 +152,20 @@ can get a list of available files via:
 ``` r
 uis_bulk_files()
 #> # A tibble: 11 × 3
-#>    file_name                                               file_url last_updated
-#>    <chr>                                                   <chr>    <chr>       
-#>  1 "SDG 4 Education - Global and Thematic Indicators "     https:/… Septembre 2…
-#>  2 "Other Policy Relevant Indicators (OPRI)"               https:/… September 2…
-#>  3 " SDG 9.5 - Research and Development (R&D)"             https:/… October 2024
-#>  4 "Research and Development (R&D) – Other Policy Relevan… https:/… October 2024
-#>  5 "SDG 11.4 Protect the Worlds Cultural and Natural Heri… https:/… October 2024
-#>  6 "Demographic and Socio-economic Indicators"             https:/… September 2…
-#>  7 "Education Non Core Archive February 2020"              https:/… <NA>        
-#>  8 "Research and Development (R&D) Archive March 2021"     https:/… <NA>        
-#>  9 "Innovation Archive April 2017"                         https:/… <NA>        
-#> 10 "Cultural employment Archive June 2019"                 https:/… <NA>        
-#> 11 "Cultural trade Archive June 2021"                      https:/… <NA>
+#>    file_name                                     file_url last_updated_descrip…¹
+#>    <chr>                                         <chr>    <chr>                 
+#>  1 "SDG 4 Education - Global and Thematic Indic… https:/… Septembre 2024        
+#>  2 "Other Policy Relevant Indicators (OPRI)"     https:/… September 2024        
+#>  3 " SDG 9.5 - Research and Development (R&D)"   https:/… October 2024          
+#>  4 "Research and Development (R&D) – Other Poli… https:/… October 2024          
+#>  5 "SDG 11.4 Protect the Worlds Cultural and Na… https:/… October 2024          
+#>  6 "Demographic and Socio-economic Indicators"   https:/… September 2024        
+#>  7 "Education Non Core Archive February 2020"    https:/… <NA>                  
+#>  8 "Research and Development (R&D) Archive Marc… https:/… <NA>                  
+#>  9 "Innovation Archive April 2017"               https:/… <NA>                  
+#> 10 "Cultural employment Archive June 2019"       https:/… <NA>                  
+#> 11 "Cultural trade Archive June 2021"            https:/… <NA>                  
+#> # ℹ abbreviated name: ¹​last_updated_description
 ```
 
 Each bulk files consists of multiple CSV files and the `uisapi` package

cran-comments.md

@@ -0,0 +1,5 @@
+## R CMD check results
+
+0 errors | 0 warnings | 1 note
+
+* This is a new release.