Added search functionality to get_publications() (#67)

* Added search functionality to get_publications()

* Updated news.md with development updates

* Added no rows returned warning function

* Added test for warning_no_rows

* Added clean up to remove spaces from search string in get_publications

* Updates to get publications tests

* Update tests/testthat/test-get_publication.R

Co-authored-by: Cam Race <52536248+cjrace@users.noreply.github.com>

* Adjusting publication search tests based on PR comments

* Redoing a bit I accidentally undid on the publication search testing

---------

Co-authored-by: Cam Race <52536248+cjrace@users.noreply.github.com>

NEWS.md

@@ -1,5 +1,10 @@
 # eesyapi (development version)
 
+* Added `search` parameter to `get_publications()` to allow filtering on publication title text.
+* Cleaned up behaviour of `query_dataset()` to only use geographies as a parameter, rather than 
+geographies, locations and geographic_levels.
+* Moved all background functions to be internal.
+
 # eesyapi 0.4.0
 
 * Optimisation to parsing of JSON responses in `query_dataset()`

R/api_url.R

@@ -14,6 +14,8 @@
 #'
 #' @param endpoint Name of endpoint, can be "get-publications", "get-data-catalogue",
 #' "get-summary", "get-meta", "get-csv", "get-data" or "post-data"
+#' @param search String for filtering the publication list for publication titles and summaries
+#' containing the search string provided (strings separated by spaces are combined with OR logic).
 #' @param publication_id ID of the publication to be connected to. This is required if the
 #' endpoint is "get-data-catalogue"
 #' @param dataset_id ID of data set to be connected to. This is required if the endpoint is one
@@ -50,6 +52,7 @@
 #' )
 api_url <- function(
     endpoint = "get-publications",
+    search = NULL,
     publication_id = NULL,
     dataset_id = NULL,
     indicators = NULL,
@@ -124,7 +127,12 @@ api_url <- function(
     url <- paste0(
       endpoint_base_version,
       "publications?",
-      api_url_pages(page_size = page_size, page = page)
+      api_url_pages(page_size = page_size, page = page),
+      ifelse(
+        !is.null(search),
+        paste0("&search=", search),
+        ""
+      )
     )
   } else if (endpoint == "get-data-catalogue") {
     url <- paste0(

R/get_publications.R

@@ -7,17 +7,43 @@
 #'
 #' @examples
 #' get_publications()
+#' get_publications(search = "attendance")
 get_publications <- function(
     ees_environment = NULL,
     api_version = NULL,
+    search = NULL,
     page_size = 40,
     page = NULL,
     verbose = FALSE) {
   validate_page_size(page_size)
+  if (!is.null(search)) {
+    # Replacing any spaces with dashes, this will combine separate strings as an OR query.
+    search <- stringr::str_replace_all(search, " ", "-")
+    search_substr <- search |>
+      strsplit("-") |>
+      magrittr::extract2(1)
+    search_substr_lengths <- search_substr |>
+      stringr::str_length()
+    # Check for any of the search strings being shorten than 3 characters.
+    if (all(search_substr_lengths < 3)) {
+      stop(
+        "Individual search string(s) must be 3 characters or longer: \"",
+        paste0(search_substr[search_substr_lengths < 3], collapse = "\", \""),
+        "\"."
+      )
+    } else if (any(search_substr_lengths < 3)) {
+      warning(
+        "The API search will ignore any search strings less than 3 chars in length: \"",
+        paste0(search_substr[search_substr_lengths < 3], collapse = "\", \""),
+        "\"."
+      )
+    }
+  }
   response <- httr::GET(
     api_url(
       ees_environment = ees_environment,
       api_version = api_version,
+      search = search,
       page_size = page_size,
       page = page,
       verbose = verbose
@@ -33,6 +59,7 @@ get_publications <- function(
           api_url(
             ees_environment = ees_environment,
             api_version = api_version,
+            search = search,
             page_size = page_size,
             page = page,
             verbose = verbose
@@ -45,6 +72,8 @@ get_publications <- function(
       }
     }
   }
-  response |> warning_max_pages()
+  response |>
+    warning_max_pages() |>
+    warning_no_rows()
   return(response$results)
 }

R/http_request_error.R

@@ -57,11 +57,13 @@ http_request_error <- function(
           error_message,
           ifelse(
             "items" %in% names(error_detail),
-            paste0("\n     Error items: ",error_detail |>
-              dplyr::pull("items") |>
-              unlist() |>
-              paste0(collapse = ", ")
-              ),
+            paste0(
+              "\n     Error items: ",
+              error_detail |>
+                dplyr::pull("items") |>
+                unlist() |>
+                paste0(collapse = ", ")
+            ),
             ""
           ),
           ifelse(

R/warning_max_pages.R

@@ -2,7 +2,7 @@
 #'
 #' @param api_result Output from an API get query
 #'
-#' @return NULL
+#' @return Original input (api_result) unchanged
 #'
 #' @keywords internal
 #'
@@ -23,4 +23,5 @@ warning_max_pages <- function(api_result) {
       )
     )
   }
+  return(api_result)
 }

R/warning_no_rows.R

@@ -0,0 +1,23 @@
+#' Warn on zero rows returned
+#'
+#' @param api_result Output from an API get query
+#'
+#' @return Original input (api_result) unchanged
+#'
+#' @keywords internal
+#'
+#' @examples
+#' response_page <- httr::GET(api_url("get-publications", search = "bob")) |>
+#'   httr::content("text") |>
+#'   jsonlite::fromJSON() |>
+#'   eesyapi:::warning_no_rows()
+warning_no_rows <- function(api_result) {
+  if (api_result$paging$totalResults == 0) {
+    warning(
+      paste0(
+        "Your query returned zero rows."
+      )
+    )
+  }
+  return(api_result)
+}

tests/testthat/test-get_publication.R

@@ -1,10 +1,8 @@
 # Check the get_publication_catalogue() function returns the expected data
-# WARNING: This depends on live data, so may fail due to real-life changes.
-#          If that's the case, take a new snapshot by running seed_tests()
 test_that("Retrieve publication list", {
-  expect_equal(
-    get_publications(),
-    readRDS("testdata/example_publication_catalogue.rds")
+  expect_gt(
+    get_publications() |> nrow(),
+    0
   )
 })
 
@@ -17,3 +15,41 @@ test_that("Retrieve data set list for publication", {
     readRDS("testdata/example_publication_datasets.rds")
   )
 })
+
+test_that("Search doesn't return anything it shouldn't", {
+  expect_equal(
+    get_publications(search = "attendance") |>
+      dplyr::filter(
+        !grepl("attendance", title, ignore.case = TRUE),
+        !grepl("attendance", summary, ignore.case = TRUE)
+      ) |>
+      nrow(),
+    0
+  )
+})
+
+
+test_that("Search doesn't return anything it shouldn't", {
+  result <- get_publications(search = "attendance")
+  expect_equal(
+    result |>
+      dplyr::mutate(title_summary = paste(title, summary)) |>
+      dplyr::filter(
+        grepl("attendance", title_summary, ignore.case = TRUE)
+      ) |>
+      nrow(),
+    nrow(result)
+  )
+})
+
+test_that("Search throws an error if all search terms are less than 3 characters", {
+  expect_error(
+    get_publications(search = "AP")
+  )
+})
+
+test_that("Search throws a warning if any search term is less than 3 characters", {
+  expect_warning(
+    get_publications(search = "api d")
+  )
+})

tests/testthat/test-query_dataset.R

@@ -157,7 +157,10 @@ test_that("Test filter-combinations POST dataset query", {
 test_that("Indicators not found in data set", {
   expect_error(
     query_dataset(example_id(), indicators = c("uywet", "uywed")),
-    "\nHTTP connection error: 400\nOne or more indicators could not be found.\n     Error items: uywet, uywed"
+    paste0(
+      "\nHTTP connection error: 400\nOne or more indicators could not be found.",
+      "\n     Error items: uywet, uywed"
+    )
   )
 })
 

tests/testthat/test-warning_no_rows.R

@@ -0,0 +1,6 @@
+test_that("Get publications returns warning when no rows returned", {
+  expect_warning(
+    x <- get_publications(search = "z3x4c5v6b7"),
+    "Your query returned zero rows."
+  )
+})