Add final functions; fix up documentation

NAMESPACE

@@ -22,6 +22,8 @@ export(rl_family)
 export(rl_family_)
 export(rl_faos)
 export(rl_faos_)
+export(rl_green)
+export(rl_green_)
 export(rl_growth_forms)
 export(rl_growth_forms_)
 export(rl_habitats)
@@ -32,6 +34,8 @@ export(rl_order)
 export(rl_order_)
 export(rl_phylum)
 export(rl_phylum_)
+export(rl_pop_trends)
+export(rl_pop_trends_)
 export(rl_realms)
 export(rl_realms_)
 export(rl_research)

R/rl_assessment.R

@@ -5,7 +5,7 @@
 #' @export
 #' @param id (integer) The unique identifier of the assessment.
 #' @template all
-#' @template info_new
+#' @template info
 #' @examples \dontrun{
 #' # Get assessment details for Fratercula arctica
 #' ex1 <- rl_assessment(id = 166290968)

R/rl_categories.R

@@ -12,7 +12,7 @@
 #' @param code (character) The code of the Red List category to look up. If not
 #'   supplied, a list of all categories will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @examples \dontrun{
 #' # Get all Red List categories
@@ -52,3 +52,28 @@ rl_categories_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
     rr_GET(path, key, query = list(page = page), ...)
   }
 }
+
+#' Green Status assessment summary
+#'
+#' List all Green Status assessments.
+#'
+#' @export
+#' @template all
+#' @template info
+#' @examples \dontrun{
+#' # Get list of Green Status assessments
+#' rl_green()
+#' }
+rl_green <- function(key = NULL, parse = TRUE, ...) {
+  assert_is(parse, 'logical')
+
+  rl_parse(rl_green_(key, ...), parse)
+}
+
+#' @export
+#' @rdname rl_green
+rl_green_ <- function(key = NULL, ...) {
+  assert_is(key, 'character')
+
+  rr_GET("green_status/all", key, ...)
+}

R/rl_comp_groups.R

@@ -6,7 +6,7 @@
 #' @param name (character) The code of the comprehensive group to look up. If
 #'   not supplied, a list of all comprehensive groups will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @examples \dontrun{
 #' # Get list of all comprehensive groups

R/rl_conservation.R

@@ -1,4 +1,4 @@
-#' Conservations actions needed assessment summary
+#' Conservation actions needed assessment summary
 #'
 #' Return the latest assessments with a given conservation action needed (e.g.,
 #' Land/water management or Species recovery). These conservation action codes
@@ -9,7 +9,7 @@
 #' @param code (character) The code of the conservation action to look up. If
 #'   not supplied, a list of all conservation actions will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family conservation
 #' @examples \dontrun{
@@ -61,7 +61,7 @@ rl_actions_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
 #' @param code (character) The code of the research type to look up. If not
 #'   supplied, a list of all research types will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family conservation
 #' @examples \dontrun{

R/rl_countries.R

@@ -6,7 +6,7 @@
 #' @param code (character) The ISO alpha-2 code of the country to look up. If
 #'   not supplied, a list of all countries will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family geo
 #' @examples \dontrun{

R/rl_growth_forms.R

@@ -6,7 +6,7 @@
 #' @param code (character) The code of the growth form to look up. If not
 #'   supplied, a list of all growth forms will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @examples \dontrun{
 #' # Get list of all growth forms

R/rl_habitats.R

@@ -8,7 +8,7 @@
 #' @param code (character) The code of the habitat to look up. If not supplied,
 #'   a list of all habitats will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family habitat
 #' @examples \dontrun{
@@ -59,7 +59,7 @@ rl_habitats_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
 #' @param code (character) The code of the system to look up. If not supplied, a
 #'   list of all systems will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family habitat
 #' @examples \dontrun{

R/rl_realms.R

@@ -7,7 +7,7 @@
 #' @param code (character) The code of the biogeographical realm to look up. If
 #'   not supplied, a list of all biogeographical realms will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family geo
 #' @examples \dontrun{
@@ -58,7 +58,7 @@ rl_realms_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
 #' @param code (character) The code of the scope to look up. If not supplied, a
 #'   list of all scopes will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family geo
 #' @examples \dontrun{
@@ -111,7 +111,7 @@ rl_scopes_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
 #' @param code (character) The code of the FAO region to look up. If not
 #'   supplied, a list of all FAO regions will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family geo
 #' @examples \dontrun{

R/rl_sp_count.R

@@ -3,10 +3,12 @@
 #' Returns a count of the number of unique species which have assessments
 #'
 #' @export
-#' @template all
-#' @template info_new
+#' @param key (character) An IUCN API token. See \code{\link{rl_use_iucn}}.
+#' @param ... Curl options passed to \code{\link[crul]{HttpClient}}
+#' @template info
 #' @family stats
 #' @examples \dontrun{
+#' # Get count of species with assessments
 #' rl_sp_count()
 #' }
 rl_sp_count <- function(key = NULL, ...) {

R/rl_taxa.R

@@ -24,7 +24,7 @@
 #'   Infraspecific ranks such as formas, subvarieties, cultivars, etc are not
 #'   included in the Red List.
 #' @template all
-#' @template info_new
+#' @template info
 #' @family taxa
 #' @examples \dontrun{
 #' # Get assessment summary for species
@@ -67,7 +67,7 @@ rl_species_ <- function(genus, species, infra = NULL, subpopulation = NULL,
 #' @param family (character) The name of the family to look up. If not supplied,
 #'   a list of all family names will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family taxa
 #' @examples \dontrun{
@@ -116,7 +116,7 @@ rl_family_ <- function(family = NULL, key = NULL, all = TRUE, page = 1,
 #' @param order (character) The name of the order to look up. If not supplied, a
 #'   list of all order names will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family taxa
 #' @examples \dontrun{
@@ -165,7 +165,7 @@ rl_order_ <- function(order = NULL, key = NULL, all = TRUE, page = 1,
 #' @param class (character) The name of the class to look up. If not supplied, a
 #'   list of all class names will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family taxa
 #' @examples \dontrun{
@@ -214,7 +214,7 @@ rl_class_ <- function(class = NULL, key = NULL, all = TRUE, page = 1,
 #' @param phylum (character) The name of the phylum to look up. If not supplied,
 #'   a list of all phylum names will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family taxa
 #' @examples \dontrun{
@@ -263,7 +263,7 @@ rl_phylum_ <- function(phylum = NULL, key = NULL, all = TRUE, page = 1,
 #' @param kingdom (character) The name of the kingdom to look up. If not
 #'   supplied, a list of all kingdom names will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family taxa
 #' @examples \dontrun{
@@ -295,7 +295,7 @@ rl_kingdom_ <- function(kingdom = NULL, key = NULL, all = TRUE, page = 1,
   assert_is(all, 'logical')
   assert_is(quiet, 'logical')
 
-  path <- paste("taxa/kingdom", phylum, sep = "/")
+  path <- paste("taxa/kingdom", kingdom, sep = "/")
 
   if (all) {
     page_assessments(path, key, quiet, ...)
@@ -310,7 +310,7 @@ rl_kingdom_ <- function(kingdom = NULL, key = NULL, all = TRUE, page = 1,
 #'
 #' @export
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family taxa
 #' @examples \dontrun{
@@ -353,7 +353,7 @@ rl_extinct_ <- function(key = NULL, all = TRUE, page = 1, quiet = FALSE, ...) {
 #'
 #' @export
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family taxa
 #' @examples \dontrun{

R/rl_threats.R

@@ -10,7 +10,7 @@
 #' @param code (character) The code of the threat to look up. If not supplied, a
 #'   list of all threats will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family threats
 #' @examples \dontrun{
@@ -61,7 +61,7 @@ rl_threats_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
 #' @param code (character) The code of the stress to look up. If not supplied, a
 #'   list of all stresses will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family threats
 #' @examples \dontrun{
@@ -112,7 +112,7 @@ rl_stresses_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
 #' @param code (character) The code of the use and trade to look up. If not
 #'   supplied, a list of all uses and trades will be returned.
 #' @template all
-#' @template info_new
+#' @template info
 #' @template page
 #' @family threats
 #' @examples \dontrun{

R/rl_trends.R

@@ -0,0 +1,49 @@
+#' Population trend assessment summary
+#'
+#' Return a list of the latest assessments based on a population trend (i.e.
+#' increasing, decreasing, stable or unknown).
+#'
+#' @export
+#' @param code (character) The code of the growth form to look up. If not
+#'   supplied, a list of all growth forms will be returned.
+#' @template all
+#' @template info
+#' @template page
+#' @examples \dontrun{
+#' # Get list of all population trends
+#' rl_pop_trends()
+#' # Get assessment summary for stable population trends
+#' rl_pop_trends("2")
+#' }
+rl_pop_trends <- function(code = NULL, key = NULL, parse = TRUE, all = TRUE,
+                          page = 1, quiet = FALSE,...) {
+  assert_is(parse, 'logical')
+  assert_is(all, 'logical')
+
+  res <- rl_pop_trends_(code, key, all, page, quiet, ...)
+  if (all) {
+    combine_assessments(res, parse)
+  } else {
+    rl_parse(res, parse)
+  }
+}
+
+#' @export
+#' @rdname rl_pop_trends
+rl_pop_trends_ <- function(code = NULL, key = NULL, all = TRUE, page = 1,
+                           quiet = FALSE, ...) {
+  assert_is(key, 'character')
+  assert_is(code, 'character')
+  assert_is(page, c('integer', 'numeric'))
+  assert_n(page, 1)
+  assert_is(all, 'logical')
+  assert_is(quiet, 'logical')
+
+  path <- paste("population_trends", code, sep = "/")
+
+  if (all) {
+    page_assessments(path, key, quiet, ...)
+  } else {
+    rr_GET(path, key, query = list(page = page), ...)
+  }
+}

R/rredlist-package.R

@@ -2,17 +2,11 @@
 "_PACKAGE"
 
 #' @title rredlist
-#' @section Taxonomic Names vs. IUCN IDs:
-#' From the documentation (quoting): "It is advisable wherever possible to use
-#' the taxon name (species name) to make your API calls, rather than using IDs.
-#' IDs are not immovable are expected to be used mainly by organizations
-#' that work closely with the IUCN Red List."
-#'
 #' @section Authentication:
 #' IUCN requires you to get your own API key, an alphanumeric string that you
 #' need to send in every request. See key A IUCN API token. See [rl_use_iucn()]
 #' for help getting and storing it. Get it at
-#' https://apiv3.iucnredlist.org/api/v3/token
+#' https://api.iucnredlist.org/users/sign_up
 #' Keep this key private. You can pass the key in to each function via the
 #' `key` parameter, but it's better to store the key either as a
 #' environment variable (`IUCN_REDLIST_KEY`) or an R option
@@ -22,13 +16,13 @@
 #' **High level API**
 #' High level functions do the HTTP request and parse data to a data.frame for
 #' ease of downstream use. The high level functions have no underscore on
-#' the end of the function name, e.g., [rl_search()]
+#' the end of the function name, e.g., [rl_species()]
 #'
 #' **Low level API**
 #' The parsing to data.frame in the high level API does take extra time.
 #' The low level API only does the HTTP request, and gives back JSON without
 #' doing any more parsing. The low level functions DO have an underscore on
-#' the end of the function name, e.g., [rl_search_()]
+#' the end of the function name, e.g., [rl_species_()]
 #'
 #' @section No Spatial:
 #' This package does not include support for the spatial API, described at

man-roxygen/info.R

@@ -1,4 +1,3 @@
-#' @return A list, with the data in the \code{result} slot, unless using
-#' a function with a trailing underscore, in which case json as character
-#' string is returned.
-#' @references API docs at https://apiv3.iucnredlist.org/api/v3/docs.
+#' @return A list unless using a function with a trailing underscore, in which
+#'   case json as character string is returned.
+#' @references API docs at <https://api.iucnredlist.org/>.