fix #21 finish off new natserv API search fxns, add tests

R/ns_search_comb.R

@@ -1,14 +1,20 @@
 #' Combined search
 #'
 #' @export
-#' @param text (character) xxxx
-#' @param text_adv (list) xxxx
+#' @param text (character) basic text search, equiavalent to `text_adv`
+#' with `matchAgainst="allNames"` and `operator="similarTo"`
+#' @param text_adv (list) advanced search, must specify the following three
+#' elements: `searchToken`, `matchAgainst`, and `operator`. see 
+#' https://explorer.natureserve.org/api-docs/#_advanced_text_search_parameter
 #' @param status (character) conservation status, one of G1, G2, G3, G4,
 #' G5, GH, GX, GNR, GNA, GU. case insensitive
-#' @param location (list) location, country and sub-country
+#' @param location (list) location, country and sub-country. specify either
+#' `nation` OR `nation` and `subnation`. each expects a two-letter ISO code
 #' @param record_type (character) limit results by record type, one of
-#' species or ecosystem
-#' @param record_subtype (character) limit results by record sub-type
+#' "species" or "ecosystem"
+#' @param record_subtype (character) limit results by record sub-type, one of:
+#' "class", "subclass", "formation", "division", "macrogroup", "group",
+#' "alliance", "association", "terrestrial_ecological_system"
 #' @param modified_since (character) search for records modified since a
 #' given time. value must be a date and time with a UTC offset in ISO 8601
 #' format. optional
@@ -18,8 +24,8 @@
 #' @family search
 #' @examples \dontrun{
 #' ns_search_comb(text = "robin")
-#' ns_search_comb(text_adv = list(searchToken = "bird",
-#'   matchAgainst = "allNames", operator="similarTo"))
+#' ns_search_comb(text_adv = list(searchToken = "western",
+#'   matchAgainst="allScientificNames", operator="startsWith"))
 #' ns_search_comb(status = "G1")
 #' ns_search_comb(location = list(nation = "US"))
 #' ns_search_comb(location = list(nation = "US", subnation = "VA"))
@@ -52,18 +58,5 @@ ns_search_comb <- function(text = NULL, text_adv = NULL, status = NULL,
     ),
     ...
   )
-  tt <- jsonlite::fromJSON(res)
-  tt$results <- tibble::as_tibble(tt$results)
-  tt$resultsSummary <- ns_sum(tt$resultsSummary)
-  attr(tt$resultsSummary, "search_criteria") <- tt$searchCriteria
-  tt$searchCriteria <- NULL
-  return(tt)
-}
-
-ns_sum <- function(x) {
-  x$species_total <- x$speciesResults$total
-  x$speciesResults <- NULL
-  eco <- x$ecosystemResults
-  x$ecosystemResults <- NULL
-  data.frame(tibble::enframe(c(x, eco)))
+  parse_search(res)
 }

R/ns_search_eco.R

@@ -1,17 +1,11 @@
 #' Ecosystem search
 #'
 #' @export
-#' @param text (character) xxxx
-#' @param text_adv (list) xxxx
-#' @param status (character) conservation status
-#' @param location (list) location, country and sub-country
-#' @param ecosystem_taxonomy (character) ecosystem taxonomy
-#' @param record_subtype (character) limit results by record sub-type
-#' @param modified_since (character) search for records modified since a
-#' given time. value must be a date and time with a UTC offset in ISO 8601
-#' format. optional
-#' @param page (integer) Zero-indexed page number; default: 0. optional
-#' @param per_page (integer) Records per page; default: 20. optional
+#' @inheritParams ns_search_comb
+#' @param ecosystem_taxonomy (character) the classification code of the
+#' higher level (ancestor) ecosystem. E.g.'s: "1" (Class code),
+#' "1.B" (Subclass code), "1.B.2" (Formation code), "1.B.2.Nd" (Division code),
+#' "M886" (Macrogroup key), "G206" (Group key), "A3328" (Alliance Key)
 #' @template ns
 #' @family search
 #' @examples \dontrun{
@@ -36,6 +30,7 @@ ns_search_eco <- function(text = NULL, text_adv = NULL, status = NULL,
   location <- handle_location(location)
   ecosystem_taxonomy <- handle_ecotax(ecosystem_taxonomy)
   record_subtype <- handle_subtype(record_subtype)
+  assert(modified_since, "character")
   res <- ns_POST(
     url = file.path(ns_base(), 'api/data/ecosystemsSearch'),
     body = list(criteriaType = "ecosystems",
@@ -49,5 +44,5 @@ ns_search_eco <- function(text = NULL, text_adv = NULL, status = NULL,
     ),
     ...
   )
-  jsonlite::fromJSON(res)
+  parse_search(res)
 }

R/ns_search_spp.R

@@ -1,17 +1,11 @@
 #' Species search
 #'
 #' @export
-#' @param text (character) xxxx
-#' @param text_adv (list) xxxx
-#' @param status (character) conservation status
-#' @param location (list) location, country and sub-country
-#' @param species_taxonomy (character) species taxonomy
-#' @param record_subtype (character) limit results by record sub-type
-#' @param modified_since (character) search for records modified since a
-#' given time. value must be a date and time with a UTC offset in ISO 8601
-#' format. optional
-#' @param page (integer) Zero-indexed page number; default: 0. optional
-#' @param per_page (integer) Records per page; default: 20. optional
+#' @inheritParams ns_search_comb
+#' @param species_taxonomy (list) species taxonomy. either a list with
+#' `level` and `scientificTaxonomy` (a scientific name), or with just
+#' `informalTaxonomy` (a vernacular name). possible `level` values:
+#' "kingdom", "phylum", "class", "order", "family", "genus" 
 #' @template ns
 #' @family search
 #' @examples \dontrun{
@@ -21,7 +15,7 @@
 #' ns_search_spp(status = "G1")
 #' ns_search_spp(location = list(nation = "US"))
 #' ns_search_spp(location = list(nation = "US", subnation = "VA"))
-#' ns_search_spp(species_taxonomy = list(speciesTaxonomy = "Animalia", level = "kingdom"))
+#' ns_search_spp(species_taxonomy = list(scientificTaxonomy = "Animalia", level = "kingdom"))
 #' ns_search_spp(species_taxonomy = list(informalTaxonomy = "birds"))
 #' ns_search_spp(record_subtype = "macrogroup")
 #' ns_search_spp(modified_since = "2020-04-30T00:00:00+0000")
@@ -37,6 +31,7 @@ ns_search_spp <- function(text = NULL, text_adv = NULL, status = NULL,
   location <- handle_location(location)
   species_taxonomy <- handle_sptax(species_taxonomy)
   record_subtype <- handle_subtype(record_subtype)
+  assert(modified_since, "character")
   res <- ns_POST(
     url = file.path(ns_base(), 'api/data/speciesSearch'),
     body = list(criteriaType = "species",
@@ -50,6 +45,5 @@ ns_search_spp <- function(text = NULL, text_adv = NULL, status = NULL,
     ),
     ...
   )
-  jsonlite::fromJSON(res)
+  parse_search(res)
 }
-

R/search_helpers.R

@@ -71,15 +71,45 @@ handle_subtype <- function(record_subtype) {
   return(record_subtype)
 }
 handle_sptax <- function(st) {
+  assert(st, "list")
   if (!is.null(st)) {
-    pt <- if ("informalTaxonomy" %in% names(st)) "informalTaxonomy" else "scientificTaxonomy"
+    if (
+      !all(names(st) %in% 
+        c("level", "scientificTaxonomy", "informalTaxonomy"))
+    ) {
+      stop("`species_taxonomy` must be a list w/ 'informalTaxonomy' ",
+        "or 'level' and 'scientificTaxonomy'",
+        call. = FALSE)
+    }
+    pt <- if ("informalTaxonomy" %in% names(st)) 
+      "informalTaxonomy" 
+    else
+      "scientificTaxonomy"
     st <- c(paramType=pt, st)
   }
   return(st)
 }
 handle_ecotax <- function(x) {
+  assert(x, "character")
   if (!is.null(x)) {
     return(list(paramType="ecosystemHierarchyAncestor", classificationCode=x))
   }
   return(x)
 }
+
+parse_search <- function(x) {
+  tt <- jsonlite::fromJSON(x)
+  tt$results <- tibble::as_tibble(tt$results)
+  tt$resultsSummary <- ns_sum(tt$resultsSummary)
+  attr(tt$resultsSummary, "search_criteria") <- tt$searchCriteria
+  tt$searchCriteria <- NULL
+  return(tt)
+}
+
+ns_sum <- function(x) {
+  x$species_total <- x$speciesResults$total
+  x$speciesResults <- NULL
+  eco <- x$ecosystemResults
+  x$ecosystemResults <- NULL
+  data.frame(tibble::enframe(c(x, eco)))
+}

man-roxygen/ns.R

@@ -1,3 +1,2 @@
-#' @param ... Curl options passed on to \code{\link[crul]{HttpClient}}
-#'
+#' @param ... Curl options passed on to \code{\link[crul]{verb-GET}}
 #' @references https://explorer.natureserve.org/api-docs/