diff --git a/.Rhistory b/.Rhistory deleted file mode 100644 index 6e55fed..0000000 --- a/.Rhistory +++ /dev/null @@ -1,498 +0,0 @@ -hello <- function() { -print("Hello, world!") -} -hello() -View(hello) -get_all_countries() -get_all_countries() -df = get_all_countries() -df = get_all_countries() -View(df) -operations = get_all_operations() -library(dtmapi) -operations = get_all_operations() -operations = get_all_operations() -devtools::build() -devtools::check() -operations = get_all_operations() -View(operations) -devtools::load_all(".") -devtools::load_all(".") -devtools::load_all(".") -check() -library(devtools) -check() -devtools::load_all(".") ---- -title: "dtmapi document" -knitr::opts_chunk$set( -collapse = TRUE, -comment = "#>" -) -knitr::opts_chunk$set( -collapse = TRUE, -comment = "#>" -) -plot(1:10) -plot(10:1) -knitr::kable(head(mtcars, 10)) -knitr::opts_chunk$set( -collapse = TRUE, -comment = "#>" -) -plot(1:10) -plot(10:1) -knitr::kable(head(mtcars, 10)) -devtools::check() -devtools::build() -data = get_idp_admin0_data(CountryName = "Ethiopia") -View(data) -data = get_idp_admin0_data() -devtools::check() -devtools::build() -lt = get_idp_admin1_data() -lt = get_idp_admin1_data(Admin0Pcode = "ETH") -View(lt) -View(lt) -devtools::check() -devtools::build() -df = get_idp_admin2_data(Admin0Pcode = "ETH") -View(df) -df = get_idp_admin2_data(Admin0Pcode = "ETH", FromRoundNumber = "2", ToRoundNumber = "2") -nn = get_all_countries() -View(nn) -kj = get_all_operations() -View(kj) -library(roxygen2) -roxygen2::roxygenise() -devtools::document() -?get_all_countries -?get_all_operations -?get_all_countries -?get_idp_admin0_data -?get_idp_admin1_data -?get_idp_admin2_data -devtools::check() -devtools::build() -get_all_countries() -install.packages("config") -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -library(dtmapi) -get_all_countries() -devtools::load_all(".") -get_all_countries() -library(dtmapi) -get_all_countries() -get_all_countries() -get_all_countries() -exit -clear -get_all_countries() -devtools::load_all(".") -get_all_countries() -devtools::load_all(".") -get_all_countries() -devtools::load_all(".") -get_all_countries() -devtools::check() -get_all_countries() -getdy = get_idp_admin0_data() -getdy = get_idp_admin0_data(CountryName = "Sudan") -View(getdy) -devtools::check() -devtools::check() -getdy = get_idp_admin0_data(CountryName = "Sudan") -View(getdy) -getdy = get_idp_admin0_data(CountryName = "Sudan") -devtools::check() -getdy = get_idp_admin0_data(CountryName = "Sudan") -View(getdy) -t = get_all_countries() -View(t) -?get_all_countries -?get_idp_admin0_data -?get_idp_admin0_data -?get_idp_admin0_data -devtools::document() -?get_idp_admin0_data -devtools::document() -?get_idp_admin0_data -?get_idp_admin0_data -?get_idp_admin0_data -devtools::document() -?get_idp_admin0_data -devtools::document() -?get_idp_admin1_data -devtools::load_all(".") -devtools::check() -devtools::build() -R CMD check --as-cran . -check --as-cran . -CMD check --as-cran . -R -devtools::check() -devtools::build() -devtools::check() -devtools::build() -g = get_idp_admin2_data() -g = get_idp_admin2_data(CountryName = "Ethiopia") -g -devtools::check() -devtools::check() -devtools::use_vignette("introduction") -install.packages("usethis") -library(usethis) -devtools::use_vignette("introduction") -library(usethis) -library(usethis) -usethis::use_vignette("introduction") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -get_all_countries() -get_all_operations() -get_idp_admin0_data(Admin0Pcode = "AFG") -get_idp_admin1_data(Admin0Pcode = "ETH") -get_idp_admin2_data(Admin0Pcode = "ETH") -install.packages("testthat") -library(testthat) -test_dir("tests/testthat") -devtools::test() -devtools::document() -devtools::document() -devtools::document() -? get_all_operations -?get_idp_admin0_data -?get_idp_admin0_data -devtools::document() -?get_idp_admin2_data -devtools::build_vignettes() -devtools::build_vignettes() -?get_idp_admin0_data -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::document() -?get_all_countries -abc = get_all_countries() -View(abc) -devtools::build() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -library(dtmapi) -install.packages("devtools") -devtools::install_github("Displacement-Tracking-Matrix/dtmapi-R") -devtools::install_github("Displacement-Tracking-Matrix/dtmapi-R") -devtools::install_github("Displacement-Tracking-Matrix/dtmapi-R") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -install.packages("tinytex") -tinytex::install_tinytex() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::build() -devtools::check() -# Install released version from CRAN -install.packages("pkgdown") -install.packages("pkgdown") -getwd() -install.packages("pkgdown") -install.packages("devtools") -library(dtmapi) -get_all_countries() -install.packages("devtools") -install.packages("pkgdown") -git push --force -devtools::build_vignettes() -devtools::check() -pkgdown::build_site() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -devtools::build() -pkgdown::build_site() -devtools::check() -devtools::build() -devtools::check() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -devtools::build_vignettes() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -pkgdown::build_site() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -devtools::check() -pkgdown::build_site() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -devtools::check() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -library(dtmapi) -install.packages("dtmapi") -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -devtools::build_vignettes() -devtools::check() -library(dtmapi) -abc <- get_idp_admin0_data(Operation = "abc") -#' @param ToRoundNumber Optional; Ending round number for the data collection range. -#' @return A data frame containing the IDP Admin0 data matching the specified criteria. -#' @export -#' @examples -#' # Fetch IDP data at Admin Level 0 -#' idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) -#' head(idp_admin0_df) -#' @importFrom httr GET status_code content -#' @importFrom jsonlite fromJSON -#' @importFrom config get -get_idp_admin0_data <- function( -Operation = NULL, -CountryName = NULL, -Admin0Pcode = NULL, -FromReportingDate = NULL, -ToReportingDate = NULL, -FromRoundNumber = 0, -ToRoundNumber = 0 -) { -# Retrieve the API URL from the configuration file -# Load configuration -api_url <- "https://dtmapi.iom.int/api/idpAdmin0Data/GetAdmin0Datav2" -# Set up query parameters -params <- list( -Operation = Operation, -CountryName = CountryName, -Admin0Pcode = Admin0Pcode, -FromReportingDate = FromReportingDate, -ToReportingDate = ToReportingDate, -FromRoundNumber = FromRoundNumber, -ToRoundNumber = ToRoundNumber -) -tryCatch({ -# Send GET request to the API with parameters -response <- GET(api_url, query = params) -# Check if the request was successful -if (status_code(response) != 200) { -stop("Failed to fetch data. Status code: ", status_code(response)) -} -# Parse the JSON content -data <- content(response, "text", encoding = "UTF-8") -json_data <- fromJSON(data, flatten = TRUE) -# Check if the request was successful and extract the result -if (json_data$isSuccess) { -# Return the result as a data frame -return(as.data.frame(json_data$result)) -} else { -# Handle API-specific errors -stop("API error: ", json_data$errorMessages[1]) -} -}, error = function(e) { -# Handle and report errors -stop("API request failed: ", e$message) -}) -} -@importFrom config get -#' -#' @return A data frame containing the list of all countries. -#' @export -#' @examples -#' # Fetch all countries -#' countries_df <- get_all_countries() -#' head(countries_df) -#' @importFrom httr GET status_code content -#' @importFrom jsonlite fromJSON -#' @importFrom config get -get_all_countries <- function() { -tryCatch({ -# Retrieve the API URL from the configuration file -api_url <- "https://dtmapi.iom.int/api/Common/GetAllCountryList" -# Send GET request to the API -response <- GET(api_url) -# Check if the request was successful -if (status_code(response) != 200) { -stop("Failed to fetch data. Status code: ", status_code(response)) -} -# Parse the JSON content and extract the result as a data frame -data <- content(response, "text") -df <- fromJSON(data, flatten = TRUE)$result -# Return the data frame -return(df) -}, error = function(e) { -# Handle and report errors -stop("API request failed: ", e$message) -}) -} -abc <- get_idp_admin0_data(Operation = "abc") -abc <- get_idp_admin0_data(CountryName = ) -abc <- get_idp_admin0_data(CountryName = "Ethiopia", FromRoundNumber = 7, ToRoundNumber = 5) -remove.packages("dtmapi") -library(dtmapi) -get_all_countries() -library(dtmapi) -get_all_countries() -remove.packages("dtmapi") -devtools::check() -devtools::check() -devtools::check() -install.packages("httr2") -devtools::check() -devtools::build_vignettes() -devtools::build() -install.packages("magrittr") -install.packages("dplyr") -devtools::build() -install.packages("magrittr") -install.packages("dplyr") -devtools::build() -devtools::build() -install.packages("magrittr") -install.packages("dplyr") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -install.packages("httr2") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build() -devtools::install("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz") -library(dtmapi) -install.packages("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz", repos = NULL, type = "source") -library(dtmapi) -abc = get_all_countries() -install.packages("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz") -library(dtmapi) -abc = get_all_countries() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::build() -install.packages("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz") -library(dtmapi) -abc = get_all_countries() -abc -a = get_idp_admin0_data(CountryName = "Ehiopia") -a = get_idp_admin0_data(CountryName = "Ethiopia") -a -a = get_idp_admin1_data(CountryName = "Ethiopia") -View(a) -a = get_idp_admin2_data(CountryName = "Ethiopia", FromRoundNumber = 1, ToRoundNumber = 2) -pkgdown::build_site() -pkgdown::build_site() -devtools::build_vignettes() -pkgdown::build_site() -devtools::check() -devtools::check() -devtools::build() -pkgdown::build_site() -devtools::build_vignettes() -pkgdown::build_site() -git status -devtools::build() -devtools::build() -devtools::check() -devtools::check() -devtools::build() -devtools::check() -devtools::build() -devtools::check() -devtools::document() -devtools::build() -devtools::check() -devtools::document() -devtools::document() -devtools::build_vignettes() -devtools::build() -devtools::check() -devtools::document() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build() -devtools::check() -unlink("doc", recursive = TRUE) # Delete old doc/ folder -unlink("vignettes/*.html") # Remove old vignette HTML files -unlink("vignettes/*.R") # Remove old vignette R scripts -devtools::build_vignettes() -vignette(package = "dtmapi") -devtools::document() -devtools::build_vignettes() -devtools::check() -devtools::document() -devtools::build_vignettes() -devtools::build() -devtools::check() -devtools::check() -pkgdown::build_site() -devtools::build() -devtools::release() -devtools::release() -check_rhub() -devtools::check_rhub() -devtools::check_rhub() -devtools::check_rhubv2() -devtools::check() -devtools::release() -use_cran_comments() -usethis::use_cran_comments() -usethis::use_cran_comments() -devtools::submit_cran() -git status diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml new file mode 100644 index 0000000..fdb499f --- /dev/null +++ b/.github/workflows/R-CMD-check.yaml @@ -0,0 +1,52 @@ +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +on: + push: + branches: [main, master] + pull_request: + +name: R-CMD-check.yaml + +permissions: read-all + +jobs: + R-CMD-check: + runs-on: ${{ matrix.config.os }} + + name: ${{ matrix.config.os }} (${{ matrix.config.r }}) + + strategy: + fail-fast: false + matrix: + config: + - {os: macos-latest, r: 'release'} + - {os: windows-latest, r: 'release'} + - {os: ubuntu-latest, r: 'devel', http-user-agent: 'release'} + - {os: ubuntu-latest, r: 'release'} + - {os: ubuntu-latest, r: 'oldrel-1'} + + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + R_KEEP_PKG_SOURCE: yes + DTMAPIR_KEY: ${{ secrets.DTMAPIR_KEY}} + + steps: + - uses: actions/checkout@v4 + + - uses: r-lib/actions/setup-pandoc@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + r-version: ${{ matrix.config.r }} + http-user-agent: ${{ matrix.config.http-user-agent }} + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + extra-packages: any::rcmdcheck + needs: check + + - uses: r-lib/actions/check-r-package@v2 + with: + upload-snapshots: true + build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")' diff --git a/.gitignore b/.gitignore index c48f0ba..f234b92 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,5 @@ inst/doc /doc/ /Meta/ +.Renviron +.Rhistory \ No newline at end of file diff --git a/DESCRIPTION b/DESCRIPTION index eb1d067..af4b884 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,10 @@ Package: dtmapi Title: Fetching Data from the 'Displacement Tracking Matrix' -Version: 0.0.3 -Authors@R: - person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut", "cre")) +Version: 0.1.0 +Authors@R: c( + person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut", "cre")), + person("Assad", "Asil Companioni", email = "aasil@iom.int", role = c("aut")) + ) Description: Allows humanitarian community, academia, media, government, and non-governmental organizations to utilize the data collected by the 'Displacement Tracking Matrix' (), a unit in the International Organization for Migration. This also provides non-sensitive Internally Displaced Person figures, aggregated at the country, Admin 1 (states, provinces, or equivalent), and Admin 2 (smaller administrative areas) levels. URL: https://github.com/Displacement-Tracking-Matrix/dtmapi-R, https://displacement-tracking-matrix.github.io/dtmapi-R/ License: MIT + file LICENSE @@ -11,10 +13,10 @@ Roxygen: list(markdown = TRUE) RoxygenNote: 7.3.2 Imports: httr2, - jsonlite, - magrittr + testthat (>= 3.1.0), + askpass Suggests: knitr, rmarkdown, - testthat (>= 3.1.0) + withr VignetteBuilder: knitr diff --git a/NAMESPACE b/NAMESPACE index f70c760..2975198 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -5,10 +5,15 @@ export(get_all_operations) export(get_idp_admin0_data) export(get_idp_admin1_data) export(get_idp_admin2_data) +export(get_subscription_key) +export(set_subscription_key) +importFrom(askpass,askpass) +importFrom(httr2,req_headers_redacted) importFrom(httr2,req_perform) importFrom(httr2,req_url_query) importFrom(httr2,request) +importFrom(httr2,resp_body_json) importFrom(httr2,resp_body_string) importFrom(httr2,resp_status) -importFrom(jsonlite,fromJSON) -importFrom(magrittr,"%>%") +importFrom(httr2,secret_decrypt) +importFrom(testthat,is_testing) diff --git a/R/get_all_countries.R b/R/get_all_countries.R index b5167b9..a1338d6 100644 --- a/R/get_all_countries.R +++ b/R/get_all_countries.R @@ -1,7 +1,3 @@ -library(httr2) -library(jsonlite) -library(magrittr) # For the `%>%` operator - #' Fetch All Countries #' #' Retrieve all countries for which DTM data is publicly available through the API. @@ -9,31 +5,32 @@ library(magrittr) # For the `%>%` operator #' @return A data frame containing the list of all countries. #' @export #' @examples -#' # Fetch all countries +#' \dontrun{ #' countries_df <- get_all_countries() #' head(countries_df) -#' @importFrom httr2 request req_perform resp_status resp_body_string -#' @importFrom magrittr %>% -#' @importFrom jsonlite fromJSON +#' } +#' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted + get_all_countries <- function() { tryCatch({ - # Retrieve the API URL - api_url <- "https://dtmapi.iom.int/api/Common/GetAllCountryList" + api_url <- "https://dtm-apim.iom.int/v3/CountryList" - # Send GET request to the API using httr2 - response <- request(api_url) %>% req_perform() + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> + req_perform() # Check if the request was successful if (resp_status(response) != 200) { stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content and extract the result as a data frame - data <- resp_body_string(response) - df <- fromJSON(data, flatten = TRUE)$result + json_data <- resp_body_json(response, simplifyVector = TRUE) + df <- as.data.frame(json_data$result) # as.data.frame() for consistency's sake. - # Return the data frame return(df) }, error = function(e) { diff --git a/R/get_all_operations.R b/R/get_all_operations.R index 4b64dde..9db8310 100644 --- a/R/get_all_operations.R +++ b/R/get_all_operations.R @@ -1,7 +1,3 @@ -library(httr2) -library(jsonlite) -library(magrittr) # For the `%>%` operator - #' Fetch All Operations #' #' Retrieve all operations for which DTM data is publicly available through the API. @@ -9,20 +5,24 @@ library(magrittr) # For the `%>%` operator #' @return A data frame containing the list of all operations. #' @export #' @examples +#' \dontrun{ #' # Fetch all operations #' operations_df <- get_all_operations() #' head(operations_df) -#' @importFrom httr2 request req_perform resp_status resp_body_string -#' @importFrom magrittr %>% -#' @importFrom jsonlite fromJSON +#' } +#' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted + get_all_operations <- function() { tryCatch({ - # Load configuration - api_url <- "https://dtmapi.iom.int/api/Common/GetAllOperationList" + api_url <- "https://dtm-apim.iom.int/v3/OperationList" - # Send GET request to the API using httr2 - response <- request(api_url) %>% req_perform() + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> + req_perform() # Check if the request was successful if (resp_status(response) != 200) { @@ -30,8 +30,8 @@ get_all_operations <- function() { } # Parse the JSON content and extract the result as a data frame - data <- resp_body_string(response) - df <- fromJSON(data, flatten = TRUE)$result + json_data <- resp_body_json(response, simplifyVector = TRUE) + df <- as.data.frame(json_data$result) # as.data.frame() for consistency's sake. # Return the data frame return(df) diff --git a/R/get_idp_admin0_data.R b/R/get_idp_admin0_data.R index 777fa5a..2f9cb5f 100644 --- a/R/get_idp_admin0_data.R +++ b/R/get_idp_admin0_data.R @@ -1,7 +1,3 @@ -library(httr2) -library(jsonlite) -library(magrittr) # For the `%>%` operator - #' Fetch IDP Admin0 Data #' #' Retrieve IDP data at Admin 0 level based on specified parameters. @@ -17,12 +13,15 @@ library(magrittr) # For the `%>%` operator #' @return A data frame containing the IDP Admin0 data matching the specified criteria. #' @export #' @examples +#' \dontrun{ #' # Fetch IDP data at Admin Level 0 -#' idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) +#' idp_admin0_df <- get_idp_admin0_data(CountryName = "Ethiopia", +#' FromRoundNumber = 1, +#' ToRoundNumber = 10) #' head(idp_admin0_df) -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom magrittr %>% -#' @importFrom jsonlite fromJSON +#' } +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json req_headers_redacted + get_idp_admin0_data <- function( Operation = NULL, CountryName = NULL, @@ -32,11 +31,9 @@ get_idp_admin0_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - # Retrieve the API URL - api_url <- "https://dtmapi.iom.int/api/idpAdmin0Data/GetAdmin0Datav2" + api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin0Data" - # Set up query parameters - params <- list( + query_params <- list( Operation = Operation, CountryName = CountryName, Admin0Pcode = Admin0Pcode, @@ -47,23 +44,22 @@ get_idp_admin0_data <- function( ) tryCatch({ - # Send GET request to the API with parameters using httr2 - response <- request(api_url) %>% - req_url_query(!!!params) %>% + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> + req_url_query(!!!query_params) |> req_perform() - # Check if the request was successful if (resp_status(response) != 200) { stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content - data <- resp_body_string(response, encoding = "UTF-8") - json_data <- fromJSON(data, flatten = TRUE) + # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. + json_data <- resp_body_json(response, simplifyVector = TRUE) - # Check if the request was successful and extract the result if (json_data$isSuccess) { - # Return the result as a data frame return(as.data.frame(json_data$result)) } else { # Handle API-specific errors diff --git a/R/get_idp_admin1_data.R b/R/get_idp_admin1_data.R index 35e5f08..fd959ab 100644 --- a/R/get_idp_admin1_data.R +++ b/R/get_idp_admin1_data.R @@ -1,7 +1,3 @@ -library(httr2) -library(jsonlite) -library(magrittr) # For the `%>%` operator - #' Fetch IDP Admin1 Data #' #' Retrieve IDP data at Admin 1 level based on specified parameters. @@ -19,12 +15,13 @@ library(magrittr) # For the `%>%` operator #' @return A data frame containing the IDP Admin1 data matching the specified criteria. #' @export #' @examples +#' \dontrun{ #' # Fetch IDP data at Admin Level 1 -#' idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile") +#' idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan", Admin1Name = "Blue Nile") #' head(idp_admin1_df) -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom magrittr %>% -#' @importFrom jsonlite fromJSON +#' } +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json req_headers_redacted + get_idp_admin1_data <- function( Operation = NULL, CountryName = NULL, @@ -36,11 +33,9 @@ get_idp_admin1_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - # Retrieve the API URL - api_url <- "https://dtmapi.iom.int/api/idpAdmin1Data/GetAdmin1Datav2" + api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin1Data" - # Set up query parameters - params <- list( + query_params <- list( Operation = Operation, CountryName = CountryName, Admin0Pcode = Admin0Pcode, @@ -53,23 +48,22 @@ get_idp_admin1_data <- function( ) tryCatch({ - # Send GET request to the API with parameters using httr2 - response <- request(api_url) %>% - req_url_query(!!!params) %>% + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> + req_url_query(!!!query_params) |> req_perform() - # Check if the request was successful if (resp_status(response) != 200) { stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content - data <- resp_body_string(response, encoding = "UTF-8") - json_data <- fromJSON(data, flatten = TRUE) + # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. + json_data <- resp_body_json(response, simplifyVector = TRUE) - # Check if the request was successful and extract the result if (json_data$isSuccess) { - # Return the result as a data frame return(as.data.frame(json_data$result)) } else { # Handle API-specific errors diff --git a/R/get_idp_admin2_data.R b/R/get_idp_admin2_data.R index b2749ff..9c653fa 100644 --- a/R/get_idp_admin2_data.R +++ b/R/get_idp_admin2_data.R @@ -1,7 +1,3 @@ -library(httr2) -library(jsonlite) -library(magrittr) # For the `%>%` operator - #' Fetch IDP Admin2 Data #' #' Retrieve IDP data at Admin 2 level based on specified parameters. @@ -23,12 +19,11 @@ library(magrittr) # For the `%>%` operator #' @examples #' \dontrun{ #' # Fetch IDP data at Admin Level 2 -#' idp_admin2_df <- get_idp_admin2_data(Operation='Yemen conflict', CountryName="Yemen") +#' idp_admin2_df <- get_idp_admin2_data(Operation = "Yemen conflict", CountryName = "Yemen") #' head(idp_admin2_df) #' } -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom magrittr %>% -#' @importFrom jsonlite fromJSON +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string req_headers_redacted + get_idp_admin2_data <- function( Operation = NULL, CountryName = NULL, @@ -42,11 +37,9 @@ get_idp_admin2_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - # Retrieve the API URL - api_url <- "https://dtmapi.iom.int/api/idpAdmin2Data/GetAdmin2Datav2" + api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin2Data" - # Set up query parameters - params <- list( + query_params <- list( Operation = Operation, CountryName = CountryName, Admin0Pcode = Admin0Pcode, @@ -61,9 +54,12 @@ get_idp_admin2_data <- function( ) tryCatch({ - # Send GET request to the API with parameters using httr2 - response <- request(api_url) %>% - req_url_query(!!!params) %>% + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> + req_url_query(!!!query_params) |> req_perform() # Check if the request was successful @@ -71,13 +67,10 @@ get_idp_admin2_data <- function( stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content - data <- resp_body_string(response, encoding = "UTF-8") - json_data <- fromJSON(data, flatten = TRUE) + # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. + json_data <- resp_body_json(response, simplifyVector = TRUE) - # Check if the request was successful and extract the result if (json_data$isSuccess) { - # Return the result as a data frame return(as.data.frame(json_data$result)) } else { # Handle API-specific errors diff --git a/R/get_subscription_key.R b/R/get_subscription_key.R new file mode 100644 index 0000000..833c178 --- /dev/null +++ b/R/get_subscription_key.R @@ -0,0 +1,44 @@ +#' Retrieval of an API subscription key from the environment. +#' +#' The DTM API subscription key is returned, provided that it is available in +#' the R session as an environment variable. Users will usually need to set +#' the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file or +#' by calling `set_subscription_key()`. +#' +#' On the other hand, if the TESTTHAT environment variable is true, indicating +#' that unit tests are being run by the package maintainers, then the +#' subscription key is returned through different means. +#' @return A string representing a given subscription key for the DTM API. +#' @export +#' @examples +#' \dontrun{ +#' # Generally, calling set_subscription_key() without the key as an argument is best, +#' # as the user can then be prompted to input the key without typing it directly +#' # into the console, making it more secure and less likely to exposed. +#' set_subscription_key() +#' } +#' @importFrom httr2 secret_decrypt +#' @importFrom testthat is_testing +get_subscription_key <- function() { + key <- Sys.getenv("DTM_SUBSCRIPTION_KEY") + if (!identical(key, "")) { + return(key) + } + + if (is_testing()) { + return(testing_key()) + } else { + stop( + paste("No API key found, please supply with set_subscription_key() or", + "otherwise specifying the DTM_SUBSCRIPTION_KEY environment variable.") + ) + } +} + +testing_key_encrypted <- "gs-XVH-qdoewh5zjCEMPXrrrKDHqs5L-3X43yAPEY0rqBcwEGa2p_mTo89Ki5HqZ" + +testing_key <- function() { + secret_decrypt(encrypted = testing_key_encrypted, + key = "DTMAPIR_KEY" # Environment variable name as a string + ) +} \ No newline at end of file diff --git a/R/set_subscription_key.R b/R/set_subscription_key.R new file mode 100644 index 0000000..a1fbde5 --- /dev/null +++ b/R/set_subscription_key.R @@ -0,0 +1,25 @@ +#' Set the user's API subscription key in order to make the API calls. +#' +#' The API will be stored as an environmental variable named "DTM_API_KEY". +#' @param key +#' Either NULL or a string representing the key. NULL is preferable: using it +#' will prompt the user to type the subscription key in a graphical user +#' interface that masks it. +#' @return Nothing. Creates / overwrites an environmental variable as a side effect. +#' @export +#' @examples +#' \dontrun{ +#' # Generally, calling set_subscription_key() without the key as an argument is best, +#' # as the user can then be prompted to input the key without typing it directly +#' # into the console, making it more secure and less likely to exposed. +#' set_subscription_key() +#' } +#' @importFrom askpass askpass + +set_subscription_key <- function(key = NULL) { + if (is.null(key)) { + Sys.setenv("DTM_SUBSCRIPTION_KEY" = askpass("Please enter your subscription key.")) + } else { + Sys.setenv("DTM_SUBSCRIPTION_KEY" = key) + } +} \ No newline at end of file diff --git a/README.md b/README.md index 0532063..bfbbd6e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,12 @@ + +[![R-CMD-check](https://github.com/a-asil-companioni/dtmapi-R/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/a-asil-companioni/dtmapi-R/actions/workflows/R-CMD-check.yaml) + +

DTM Logo

- ----------------- ## About @@ -18,37 +21,8 @@ The `dtmapi` package is available on [CRAN](https://CRAN.R-project.org/package=d install.packages("dtmapi") ``` -## Load Package -After installation, load the package using library(): -```sh -library(dtmapi) -``` - -## Usage -Here's a quick example to get you started: -```R -# Get all countries for which DTM data is publicly available through the API. -countries_df <- get_all_countries() -head(countries_df) - -# Get all operations for which DTM data is publicly available through the API. -operations_df <- get_all_operations() -head(operations_df) - -# Get IDP Admin 0 Data for Ethiopia from Round 1 to Round 10 -idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) -head(idp_admin0_df) - -# Get IDP Admin 1 Data for Sudan from reporting date 2020-01-01 to 2024-08-15 -idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile", FromReportingDate='2020-01-01', ToReportingDate='2024-08-15') -head(idp_admin1_df) - -# Get IDP Admin 2 Data for Lebanon -idp_admin2_df <- get_idp_admin2_data(Operation="Displacement due to conflict", CountryName='Lebanon') -head(idp_admin2_df) -``` -## Documentation -Comprehensive documentation is available at [github.io](https://displacement-tracking-matrix.github.io/dtmapi-R/). +## User Guide +A user guide to getting started with `dtmapi` is available [here](https://displacement-tracking-matrix.github.io/dtmapi-R/). ## Source Code The source code for `dtmapi` is available on [GitHub](https://github.com/Displacement-tracking-Matrix/dtmapi-R). diff --git a/_pkgdown.yml b/_pkgdown.yml index 1547801..691cdb8 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -11,8 +11,8 @@ navbar: - Reference components: home: - text: Quick Start - href: articles/introduction.html + text: User Guide + href: articles/user_guide.html Reference: text: Reference href: reference/index.html diff --git a/docs/404.html b/docs/404.html index 5806ed7..f90922a 100644 --- a/docs/404.html +++ b/docs/404.html @@ -8,46 +8,59 @@ Page not found (404) • dtmapi - - - + + + + Skip to contents + - -