rl_categories: Red List category assessment summary

Description

Return a list of the latest assessments for a given category (e.g., Not Evaluated, Data Deficient, Least Concern, Near Threatened, Vulnerable, Endangered, Critically Endangered, Extinct in the Wild and Extinct). This endpoint returns categories for the current IUCN Red List Categories and Criteria (v3.1) as well as older versions (i.e., v2.3). Note that a code may not be unique across Categories and Criteria versions. Therefore, codes like "EX" will return assessments for EX v3.1 and EX v2.3.

Usage

rl_categories(
  code = NULL,
  key = NULL,
  parse = TRUE,
  all = TRUE,
  page = 1,
  quiet = FALSE,
  ...
)
rl_categories_(
  code = NULL,
  key = NULL,
  all = TRUE,
  page = 1,
  quiet = FALSE,
  ...
)

Value

A list unless using a function with a trailing underscore, in which case json as character string is returned.

Arguments

code

(character) The code of the Red List category to look up. If not supplied, a list of all categories will be returned.

key

(character) An IUCN API token. See rl_use_iucn().

parse

(logical) Whether to parse the output to list (FALSE) or, where possible, data.frame (TRUE). Default: TRUE.

all

(logical) Whether to retrieve all results at once or not. If TRUE we do the paging internally for you and bind all of the results together. If FALSE, only a single page of results will be retrieved.

page

(integer/numeric) Page to get if all is FALSE. Default: 1. Each page returns up to 100 records. Paging is required because it's too much burden on a server to just "get all the data" in one request.

quiet

(logical) Whether to suppress progress for multi-page downloads or not. Default: FALSE (that is, give progress). Ignored if all = FALSE.

...

Includes the following filters that are supported by the API endpoint (refer to the API docs for more information):

year_published: (integer) Set this to return only assessments from a given year.
latest: (logical) Set this to TRUE to return only the latest assessment for each taxon.
scope_code: (integer) Set this to return only assessments from a particular scope (e.g., 1 for Global, 2 for Europe). This is similar to the region argument of the old Red List API and old versions of rredlist.

Also includes the following arguments related to the wait time between request retries if a "Too Many Requests" error is received from the API (see HttpClient()$retry() for more details):

pause_base, pause_cap, and pause_min: basis, maximum, and minimum for calculating wait time for retry
times: the maximum number of times to retry
onwait: a callback function if the request will be retried and a wait time is being applied

Also supports any curl options passed to the GET request via HttpClient.

References

API docs at https://api.iucnredlist.org/.

Examples

Run this code

if (FALSE) {
# Get all Red List categories
rl_categories()
# Get assessments for the Vulnerable category
rl_categories("VU")
}