diff --git a/.Rbuildignore b/.Rbuildignore index 3b440e3..8ee0526 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -5,4 +5,5 @@ ^pkgdown$ ^\.github$ .lintr -cran-comments.md \ No newline at end of file +cran-comments.md +^cran-comments\.md$ diff --git a/DESCRIPTION b/DESCRIPTION index 7a58fec..25c54b3 100644 --- a/DESCRIPTION +++ b/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 - . + . 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) diff --git a/R/uis_bulk_files.R b/R/uis_bulk_files.R index 06c8c93..b9a5d51 100644 --- a/R/uis_bulk_files.R +++ b/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 } diff --git a/R/uis_get.R b/R/uis_get.R index 7f6a220..38a8e3a 100644 --- a/R/uis_get.R +++ b/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, diff --git a/R/uis_get_entities.R b/R/uis_get_entities.R index 7b323f9..7efe909 100644 --- a/R/uis_get_entities.R +++ b/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 diff --git a/R/uis_get_indicators.R b/R/uis_get_indicators.R index b023d9c..32caba8 100644 --- a/R/uis_get_indicators.R +++ b/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) { diff --git a/R/uis_get_versions.R b/R/uis_get_versions.R index 1a7c91d..ca858b5 100644 --- a/R/uis_get_versions.R +++ b/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") diff --git a/README.Rmd b/README.Rmd index dfc9d98..3bd5c44 100644 --- a/README.Rmd +++ b/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) -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: diff --git a/README.md b/README.md index 3b06346..fe882fd 100644 --- a/README.md +++ b/README.md @@ -13,19 +13,34 @@ coverage](https://codecov.io/gh/tidy-intelligence/r-uisapi/graph/badge.svg)](htt 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)\](. + ## 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…¹ -#> +#> #> 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 #> @@ -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 -#> -#> 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:/… -#> 8 "Research and Development (R&D) Archive March 2021" https:/… -#> 9 "Innovation Archive April 2017" https:/… -#> 10 "Cultural employment Archive June 2019" https:/… -#> 11 "Cultural trade Archive June 2021" https:/… +#> file_name file_url last_updated_descrip…¹ +#> +#> 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:/… +#> 8 "Research and Development (R&D) Archive Marc… https:/… +#> 9 "Innovation Archive April 2017" https:/… +#> 10 "Cultural employment Archive June 2019" https:/… +#> 11 "Cultural trade Archive June 2021" https:/… +#> # ℹ abbreviated name: ¹​last_updated_description ``` Each bulk files consists of multiple CSV files and the `uisapi` package diff --git a/cran-comments.md b/cran-comments.md new file mode 100644 index 0000000..858617d --- /dev/null +++ b/cran-comments.md @@ -0,0 +1,5 @@ +## R CMD check results + +0 errors | 0 warnings | 1 note + +* This is a new release. diff --git a/man/uis_bulk_files.Rd b/man/uis_bulk_files.Rd index 0753bfa..50abbc7 100644 --- a/man/uis_bulk_files.Rd +++ b/man/uis_bulk_files.Rd @@ -10,7 +10,7 @@ uis_bulk_files() 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.} } \description{ Retrieves information about files available in the UNESCO Institute for diff --git a/man/uis_get.Rd b/man/uis_get.Rd index 623e136..911da09 100644 --- a/man/uis_get.Rd +++ b/man/uis_get.Rd @@ -13,11 +13,13 @@ uis_get( ) } \arguments{ -\item{entities}{Character vector. The entity IDs (geoUnits) to retrieve data -for. Must provide either this parameter or \code{indicators} or both.} +\item{entities}{Character vector. The entity IDs (ISO 3166-1 alpha-3 codes) +to retrieve data for. Must provide either this parameter or \code{indicators} or +both. See \link{uis_get_entities} for a list of supported entities.} \item{indicators}{Character vector. The indicator IDs to retrieve data for. -Must provide either this parameter or \code{entities} or both.} +Must provide either this parameter or \code{entities} or both. See +\link{uis_get_indicators} for a list of supported indicators.} \item{start_year}{Numeric or character. The starting year for the data retrieval period. If NULL, no start year constraint is applied.} @@ -26,7 +28,8 @@ retrieval period. If NULL, no start year constraint is applied.} period. If NULL, no end year constraint is applied.} \item{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.} } \value{ A data frame with the following columns: @@ -69,7 +72,3 @@ uis_get( } \dontshow{\}) # examplesIf} } -\seealso{ -\link{uis_get_entities} for retrieving available geographical entities and -\link{uis_get_versions} for retrieving available API versions -} diff --git a/man/uis_get_entities.Rd b/man/uis_get_entities.Rd index f2509b3..7e405d4 100644 --- a/man/uis_get_entities.Rd +++ b/man/uis_get_entities.Rd @@ -8,14 +8,15 @@ uis_get_entities(version = NULL) } \arguments{ \item{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.} } \value{ 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.} } \description{ @@ -32,6 +33,3 @@ uis_get_entities("20240910-b5ad4d82") } } -\seealso{ -\link{uis_get_versions} for retrieving available API versions. -} diff --git a/man/uis_get_indicators.Rd b/man/uis_get_indicators.Rd index 873fcf0..44c86bd 100644 --- a/man/uis_get_indicators.Rd +++ b/man/uis_get_indicators.Rd @@ -12,7 +12,8 @@ uis_get_indicators( } \arguments{ \item{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.} \item{disaggregations}{Logical. If TRUE, includes disaggregation information for indicators. Default is FALSE.} @@ -24,6 +25,10 @@ with indicators. Default is FALSE.} 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 @@ -31,8 +36,7 @@ associated with the indicator.} } \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. } \examples{ \donttest{ @@ -44,6 +48,3 @@ uis_get_indicators(disaggregations = TRUE, glossary_terms = TRUE) } } -\seealso{ -\code{uis_get_versions} for retrieving available API versions. -} diff --git a/man/uis_get_versions.Rd b/man/uis_get_versions.Rd index 36fe68d..1ff7af9 100644 --- a/man/uis_get_versions.Rd +++ b/man/uis_get_versions.Rd @@ -4,11 +4,11 @@ \alias{uis_get_versions} \title{Get available UIS API versions} \usage{ -uis_get_versions(default = FALSE) +uis_get_versions(default_only = FALSE) } \arguments{ -\item{default}{Logical. Indicates whether only the current default version -should be retrievend. Defaults to FALSE.} +\item{default_only}{Logical. Indicates whether only the current default +version should be retrievend. Defaults to FALSE.} } \value{ A data frame with the following columns: @@ -21,8 +21,7 @@ theme_last_update, theme_description} } \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. } \examples{ \dontshow{if (curl::has_internet()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} diff --git a/man/uisapi-package.Rd b/man/uisapi-package.Rd index 6fc7926..2351b41 100644 --- a/man/uisapi-package.Rd +++ b/man/uisapi-package.Rd @@ -6,7 +6,7 @@ \alias{uisapi-package} \title{uisapi: Access the UNESCO Institute for Statistics API} \description{ -Retrieve data from the UNESCO Institute for Statistics (UIS) API \url{https://api.uis.unesco.org/api/public/documentation/}. +Retrieve data from the UNESCO Institute for Statistics (UIS) API \url{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. } \seealso{ Useful links: diff --git a/tests/testthat/test-uis_bulk_files.R b/tests/testthat/test-uis_bulk_files.R index dcef6cc..5a648be 100644 --- a/tests/testthat/test-uis_bulk_files.R +++ b/tests/testthat/test-uis_bulk_files.R @@ -5,7 +5,7 @@ test_that("Get all files", { expect_s3_class(result, "data.frame") expect_true(all( - c("file_name", "file_url", "last_updated") %in% + c("file_name", "file_url", "last_updated_description") %in% colnames(result) )) }) diff --git a/tests/testthat/test-uis_get_versions.R b/tests/testthat/test-uis_get_versions.R index d9cd9b5..46912af 100644 --- a/tests/testthat/test-uis_get_versions.R +++ b/tests/testthat/test-uis_get_versions.R @@ -13,7 +13,7 @@ test_that("Get all versions", { test_that("Get default version", { skip_if_offline() - result <- uis_get_versions(default = TRUE) + result <- uis_get_versions(default_only = TRUE) expect_s3_class(result, "data.frame") expect_true(all(