iucnredlist

https://iucn-uk.github.io/iucnredlist/
Admin
iucnredlist is an R client library for the IUCN Red List API that enables researchers to...
Tokens:20,119
Snippets:186
Trust Score:9.7
Update:2 days ago
Show doc for...
Tokens:
Raw
### Example call to assessments_by_group()

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_group.html

Example usage of assessments_by_group() with a habitat group, code '1_1', year_published 2012, latest TRUE, scope_code 1, wait_time 0.5, and show_warnings TRUE. The example is wrapped in \dontrun{} and is not executed by default.

```r
if (FALSE) { # \dontrun{
assessments_by_group(api,
  group = "habitats",
  code = "1_1",
  year_published = 2012,
  latest = TRUE,
  scope_code = 1,
  wait_time = 0.5,
  show_warnings = TRUE)
} # }
```

--------------------------------

### Example of list_group_names()

Source: https://iucn-uk.github.io/iucnredlist/reference/element_names.html

Example usage wrapped in a dontrun block, showing a call to list_group_names(). This is not run by default.

```r
if (FALSE) { # \dontrun{
list_group_names()
} # }
```

--------------------------------

### init_api example with a Red List API key

Source: https://iucn-uk.github.io/iucnredlist/reference/init_api.html

Example of calling init_api with a placeholder API key. Wrapped in if (FALSE) and \dontrun to prevent execution during automated checks.

```r
if (FALSE) { # \dontrun{
api <- init_api("your_red_list_api_key")
} # }
```

--------------------------------

### Install development packages

Source: https://iucn-uk.github.io/iucnredlist/index.html

Run this R code to install the packages needed for development: devtools, roxygen2, testthat, and knitr. Requires the latest version of R.

```R
install.packages(c("devtools", "roxygen2", "testthat", "knitr"))
```

--------------------------------

### Example: extract_element() with element names

Source: https://iucn-uk.github.io/iucnredlist/reference/extract_element.html

Example calls to `extract_element()` for various element names. Wrapped in `if (FALSE)` and `\dontrun{}` to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
extract_element(assessments_list, "habitats")
extract_element(assessments_list, "biogeographical_realms")
extract_element(assessments_list, "taxon_synonyms")
extract_element(assessments_list, "threats")
} # }
```

--------------------------------

### Example: assessments_by_name(api, "panthera", "leo")

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_name.html

Example call wrapped in \dontrun{} to prevent execution. It returns a tibble with assessment_ids and sis_taxon_ids for the given species.

```r
if (FALSE) { # \dontrun{
assessments_by_name(api, "panthera", "leo")
} # }
```

--------------------------------

### Install iucnredlist from GitHub with devtools

Source: https://iucn-uk.github.io/iucnredlist/index.html

Install the development version of the iucnredlist package from GitHub using devtools::install_github(). Requires the devtools package (commented out install.packages line).

```r
# install.packages("devtools")
devtools::install_github("IUCN-UK/iucnredlist")
```

--------------------------------

### Example: calling rl_version

Source: https://iucn-uk.github.io/iucnredlist/reference/rl_version.html

Example usage of rl_version, wrapped in a dontrun block to prevent execution during package checks. It assigns the result to the variable 'api'.

```r
if (FALSE) { # \dontrun{
api <- rl_version(api)
} # }
```

--------------------------------

### list_codes example with threats group

Source: https://iucn-uk.github.io/iucnredlist/reference/list_codes.html

Example call to list_codes with the 'threats' endpoint group. Wrapped in if (FALSE) to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
list_codes(api, "threats")
} # }
```

--------------------------------

### Example: fetch assessment data for ID 266696959

Source: https://iucn-uk.github.io/iucnredlist/reference/assessment_data.html

Example call to assessment_data() with assessment_id = 266696959. Wrapped in if (FALSE) { # \dontrun{ ... } # } to prevent execution during package checks.

```R
if (FALSE) { # \dontrun{
assessment_data(api, assessment_id = 266696959)
} # }
```

--------------------------------

### Example: call assessment_data_many with two assessment IDs

Source: https://iucn-uk.github.io/iucnredlist/reference/assessment_data_many.html

Example call to assessment_data_many() with a vector of two assessment IDs and a wait_time of 0.5 seconds. Wrapped in \dontrun{} because it requires a valid API connection.

```r
if (FALSE) { # \dontrun{
assessment_data_many(api, assessment_ids = c(266696959, 152728945), wait_time = 0.5)
} # }
```

--------------------------------

### Example: parse_assessment_data call

Source: https://iucn-uk.github.io/iucnredlist/reference/parse_assessment_data.html

Example usage of parse_assessment_data, wrapped in a dontrun block to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
parse_assessment_data(raw_assessment_data)
} # }
```

--------------------------------

### parse_gss_data example

Source: https://iucn-uk.github.io/iucnredlist/reference/parse_gss_data.html

Example of calling parse_gss_data with raw_gss_data, wrapped in a dontrun block to prevent execution during package checks.

```r
if (FALSE) { # \dontrun{
parse_gss_data(raw_gss_data)
} # }
```

--------------------------------

### Example: gss_data_all(api) wrapped in dontrun

Source: https://iucn-uk.github.io/iucnredlist/reference/gss_data_all.html

Example call to gss_data_all(api) wrapped in if (FALSE) { # \dontrun{ ... } # } to prevent execution during package checks. The function returns an unprocessed named list of assessment data.

```r
if (FALSE) { # \dontrun{
gss_data_all(api)
} # }
```

--------------------------------

### Example: Call assessments_by_sis_id with SIS taxon ID 230

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_sis_id.html

Example call wrapped in \dontrun{} to prevent execution during package checks. It passes an api object and the integer 230 as the SIS taxon ID.

```R
if (FALSE) { # \dontrun{
assessments_by_sis_id(api, 230)
} # }
```

--------------------------------

### Gather full assessment data for many assessment IDs with assessment_data_many()

Source: https://iucn-uk.github.io/iucnredlist/index.html

Using the sturgeon assessment IDs from the previous example, fetch full assessment data for each ID and extract threats. Requires the sturgeon object from the previous example.

```r
# Using the sturgeon assessment IDs from above example, get full assessment data
sturgeon_all <- assessment_data_many(api, sturgeon$assessment_id)

# View theats
sturgeon_threats <- extract_element(sturgeon_all, "threats")
```

--------------------------------

### Example call to assessments_by_taxonomy for family Felidae

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_taxonomy.html

Example usage wrapped in \dontrun{} to prevent execution during package checks. It calls assessments_by_taxonomy() with level = "family", name = "felidae", year_published = 2022, latest = TRUE, scope_code = 1, and wait_time = 0.5.

```R
if (FALSE) { # \dontrun{
assessments_by_taxonomy(api,
  level = "family",
  name = "felidae",
  year_published = 2022,
  latest = TRUE,
  scope_code = 1,
  wait_time = 0.5
)
} # }
```

--------------------------------

### Fetch all assessments for an SIS taxon ID with assessments_by_sis_id()

Source: https://iucn-uk.github.io/iucnredlist/index.html

Initialize the API and get minimal assessment data for the European Sturgeon (SIS ID 230) using assessments_by_sis_id(). Requires a Red List API token.

```r
# Initialize the API with your API key
api <- init_api("your_red_list_api_key")

# Get 'minimal' assessment data for the European Sturgeon
sturgeon <- assessments_by_sis_id(api, 230)
```

--------------------------------

### Show threats for a taxonomic level with assessments_by_taxonomy() and extract_element()

Source: https://iucn-uk.github.io/iucnredlist/index.html

Step-by-step workflow: get assessment IDs for family Felidae, fetch full assessment data for each ID, extract habitats or threats, and list all extractable elements. Uses wait_time = 0.5 to avoid rate limits.

```r
# Initialize the API with your API key
api <- init_api("your_red_list_api_key")

# Step 1: Get all latest and global-scope assessment IDs for the family Felidae
felidae <- assessments_by_taxonomy(api,
  level = "family",
  name = "felidae",
  latest = TRUE,
  scope_code = 1,
  wait_time = 0.5
)

# Step 2: Fetch assessment data for each assessment ID
# Pass the assessment_id column to `assessment_data_many()` to grab
# full assessment data for each assessment_id
a_data <- assessment_data_many(api,
  felidae$assessment_id,
  wait_time = 0.5
)

# Step 3: Extract habitats from the assessment data
# This will iterate over each assessment in the list a_data
# and return a tidy `tibble()` for all habitats
habitats <- extract_element(a_data, "habitats")

# Alternatively, extract threats
threats <- extract_element(a_data, "threats")

# See all elements you can extract - use any of these with `extract_element()`
element_names()
```

--------------------------------

### Fetch all assessments for a Latin binomial name with assessments_by_name()

Source: https://iucn-uk.github.io/iucnredlist/index.html

Initialize the API and get all historic and latest assessments for Panthera leo (not case-sensitive) using assessments_by_name() with genus and species arguments. Requires a Red List API token.

```r
# Initialize the API with your API key
api <- init_api("your_red_list_api_key")

# Get all historic and latest assessments for Panthera leo (not case-sensitive)
lion <- assessments_by_name(api, genus = "panthera", species = "leo")
```

--------------------------------

### assessments_by_name()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Get minimal assessment data for a Latin binomial.

```APIDOC
## assessments_by_name()

### Description
Get minimal assessment data for a Latin binomial.

### Usage
assessments_by_name(name)

### Arguments
- **name** - The Latin binomial species name.

```

--------------------------------

### assessments_by_taxonomy()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Get minimal assessment data for a taxonomic level.

```APIDOC
## assessments_by_taxonomy()

### Description
Get minimal assessment data for a taxonomic level.

### Usage
assessments_by_taxonomy(taxonomy)

### Arguments
- **taxonomy** - The taxonomic level.

```

--------------------------------

### Usage of element_names()

Source: https://iucn-uk.github.io/iucnredlist/reference/element_names.html

Call element_names() with no arguments to get a character vector of valid element names.

```r
element_names()
```

--------------------------------

### Get global assessments published in 2008 for habitat code 1

Source: https://iucn-uk.github.io/iucnredlist/articles/assessment-data-responses.html

Calls assessments_by_group() with habitat code '1', year_published = 2008, and scope = 1 to return a tibble of 38 rows with columns including sis_taxon_id, assessment_id, latest, year_published, scopes_description_en, scopes_code, and url. The output shows the first 10 rows and notes that 28 more rows are available.

```R
assessments_by_group(api, "habitats", "1", year_published = 2008, scope = 1)
```

```output
# A tibble: 38 × 7
   sis_taxon_id assessment_id latest year_published scopes_description_en scopes_code url                                               
          <int>         <int> <lgl>  <chr>          <chr>                 <chr>       <chr>                                             
 1       133958       3881104 TRUE   2008           Global                1           https://www.iucnredlist.org/species/133958/3881104
 2       134059       3887925 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134059/3887925
 3       134019       3893117 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134019/3893117
 4       134151       3910739 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134151/3910739
 5       134199       3918266 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134199/3918266
 6       134378       3947233 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134378/3947233
 7       134409       3952097 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134409/3952097
 8       134409       3952097 TRUE   2008           Eastern Africa        18          https://www.iucnredlist.org/species/134409/3952097
 9       134409       3952097 TRUE   2008           Pan-Africa            10          https://www.iucnredlist.org/species/134409/3952097
10       134438       3956693 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134438/3956693
# ℹ 28 more rows
# ℹ Use `print(n = ...)` to see more rows
```

--------------------------------

### Get minimal assessment data for a single species

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Calls assessments_by_name() with the API object and the first species from the custom list to retrieve minimal assessment data. Useful for inspecting the structure before processing multiple species.

```r
assessments_by_name(api, 
                    genus = my_species$genus[1], 
                    species = my_species$species[1])
```

--------------------------------

### assessments_by_group(api, group, code, year_published = NULL, latest = TRUE, scope_code = NULL, wait_time = 0.5, show_warnings = TRUE)

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_group.html

Retrieves minimal assessment data for a specified API group and code. Returns a tibble with assessment_ids and sis_taxon_ids that can be used with assessment_data(), assessment_data_many(), and parse_assessment_data() to get full assessment data.

```APIDOC
## assessments_by_group(api, group, code, year_published = NULL, latest = TRUE, scope_code = NULL, wait_time = 0.5, show_warnings = TRUE)

### Description
Retrieves minimal assessment data for a specified API group and code. The returned tibble contains assessment_ids and sis_taxon_ids which can be used with assessment_data(), assessment_data_many(), and parse_assessment_data() to get full assessment data.

### Usage
```r
assessments_by_group(
  api,
  group,
  code,
  year_published = NULL,
  latest = TRUE,
  scope_code = NULL,
  wait_time = 0.5,
  show_warnings = TRUE
)
```

### Arguments
- **api** (httr2 response object) - Required - An httr2 response object created with init_api().
- **group** (string) - Required - A valid API group name. Valid names can be found by calling list_group_names().
- **code** (string) - Required - A valid group code. Valid codes for an API group can be found by calling e.g. list_codes(api, "habitats").
- **year_published** (integer) - Optional - The publication year you wish to filter.
- **latest** (boolean) - Optional - Return latest or historic assessments. Defaults to TRUE.
- **scope_code** (string) - Optional - A valid assessment scope. Defaults to NULL (i.e. returns assessments of all scopes). Valid scope codes can be found by calling list_codes(api, "scopes").
- **wait_time** (float) - Optional - Time in seconds to wait between API calls. A wait time of >=0.5s will avoid API rate limiting.
- **show_warnings** (boolean) - Optional - Whether to show a warning to the console if no assessments are found for your specified arguments. Defaults to TRUE.

### Value
Returns a tibble of minimal assessment data for your specified arguments. The minimal assessment data provides assessment_ids and sis_taxon_ids which can be used with assessment_data(), assessment_data_many(), and parse_assessment_data() to get full assessment data.

### Examples
```r
if (FALSE) { # \dontrun{
assessments_by_group(api,
  group = "habitats",
  code = "1_1",
  year_published = 2012,
  latest = TRUE,
  scope_code = 1,
  wait_time = 0.5,
  show_warnings = TRUE)
} # }
```
```

--------------------------------

### Load package and initialize API connection

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Loads the iucnredlist package and initializes a connection to the IUCN Red List API using a valid API token. Requires a token from https://api.iucnredlist.org.

```R
library(iucnredlist)
api <- init_api("your_api_token")
```

--------------------------------

### init_api()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Creates a request object for a valid red_list_api_key.

```APIDOC
## init_api()

### Description
Creates a request object for a valid red_list_api_key.

### Usage
init_api(red_list_api_key)

### Arguments
- **red_list_api_key** - A valid IUCN Red List API key.

```

--------------------------------

### init_api function usage

Source: https://iucn-uk.github.io/iucnredlist/reference/init_api.html

Shows the function signature for init_api, which takes a single argument red_list_api_key.

```r
init_api(red_list_api_key)
```

--------------------------------

### init_api(red_list_api_key)

Source: https://iucn-uk.github.io/iucnredlist/reference/init_api.html

Creates an httr2 request object for a valid Red List API key. The function accepts a Red List API token string and returns a request object for use with the IUCN Red List API.

```APIDOC
## init_api(red_list_api_key)

### Description
Creates a request object for a valid red_list_api_key.

### Usage
```r
init_api(red_list_api_key)
```

### Arguments
- **red_list_api_key** (character) - Required - A Red List API token string (alphanumeric)

### Value
An httr2 request object.

### Examples
```r
if (FALSE) { # \dontrun{
api <- init_api("your_red_list_api_key")
} # }
```
```

--------------------------------

### rl_version()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Display API and Red List versions.

```APIDOC
## rl_version()

### Description
Display API and Red List versions.

### Usage
rl_version()

```

--------------------------------

### rl_version(api)

Source: https://iucn-uk.github.io/iucnredlist/reference/rl_version.html

Displays the API and Red List versions. Accepts an httr2 response object created with init_api() and returns a list containing the API version and Red List version.

```APIDOC
## rl_version(api)

### Description
Displays the API and Red List versions.

### Usage
```r
rl_version(api)
```

### Arguments
- **api** (httr2 response object) - Required - A httr2 response object created with init_api().

### Value
A list containing the API version and Red List version.

### Examples
```r
if (FALSE) { # \dontrun{
api <- rl_version(api)
} # }
```
```

--------------------------------

### assessments_by_sis_id()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Get minimal assessment data for an SIS taxon ID.

```APIDOC
## assessments_by_sis_id()

### Description
Get minimal assessment data for an SIS taxon ID.

### Usage
assessments_by_sis_id(sis_id)

### Arguments
- **sis_id** - The SIS taxon ID.

```

--------------------------------

### Usage of list_group_names()

Source: https://iucn-uk.github.io/iucnredlist/reference/list_group_names.html

Shows the basic usage of the list_group_names() function with no arguments.

```r
list_group_names()
```

--------------------------------

### list_group_names()

Source: https://iucn-uk.github.io/iucnredlist/reference/list_group_names.html

Returns a list of API groups which have code/name parameters. These names can be passed to list_codes() to get a list of codes or names for an API group of interest.

```APIDOC
## list_group_names()

### Description
Returns a list of API groups which have code/name parameters. These names can be passed to `list_codes()` to get a list of codes or names for an API group of interest (e.g. `list_codes(api, "threats")`).

### Usage
```r
list_group_names()
```

### Value
A character vector of valid API group names.

### Examples
```r
if (FALSE) { # \dontrun{
list_group_names()
} # }
```
```

--------------------------------

### Get full assessment data for multiple assessment IDs

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Passes the unique assessment IDs from the filtered tibble to assessment_data_many() with a wait_time of 0.5 seconds to retrieve full assessment data for all species.

```r
full_data <- assessment_data_many(api, 
                                  unique(a$assessment_id),
                                  wait_time=0.5)
```

--------------------------------

### Fetch data for a single assessment with assessment_data()

Source: https://iucn-uk.github.io/iucnredlist/index.html

Initialize the API with your key, fetch raw assessment data for assessment_id 266696959 (Panthera leo), parse it to tidy tibbles, and view threats and habitats. Requires a Red List API token.

```r
# Initialize the API with your API key
api <- init_api("your_red_list_api_key")

# Fetch assessment data for assessment_id = 266696959 (Panthera leo)
# Returns a list containing all assessment data
assessment_raw <- assessment_data(api, 266696959)

# Parse the 'raw' assessment data to tidy tibbles
assessment <- parse_assessment_data(assessment_raw)

# View e.g. threats or habitats
# The result is a tidy 'tibble()` of data
assessment$threats
assessment$habitats
```

--------------------------------

### Get full assessment data for the black rhino

Source: https://iucn-uk.github.io/iucnredlist/articles/assessment-data-responses.html

Calls assessment_data() with the API object and species ID 152728945 to retrieve the full raw response from the API, with no transformations except coercing JSON to lists.

```R
a <- assessment_data(api, 152728945)
```

--------------------------------

### element_names()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Show element names.

```APIDOC
## element_names()

### Description
Show element names.

### Usage
element_names()

```

--------------------------------

### Get assessments by taxonomy for felidae

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Retrieves all latest assessments for species in the family felidae using the assessments_by_taxonomy() function. The output is a tibble with 52 rows and 7 columns, showing assessment details such as sis_taxon_id, assessment_id, and year_published.

```R
felidae <- assessments_by_taxonomy(api, level = "family", name = "felidae", latest = TRUE)

# A tibble: 52 × 7
   sis_taxon_id assessment_id latest year_published scopes_description_en scopes_code url                                              
          <int>         <int> <lgl>  <chr>          <chr>                 <chr>       <chr>                                            
 1        11638       3299247 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/11638/3299247
 2        12519       3350985 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/12519/3350985
 3        15951       5325996 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/15951/5325996
 4        15954       5328595 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/15954/5328595
 5        15955       5330476 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/15955/5330476
 6         3847      10121483 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/3847/10121483
 7         8540      12915840 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/8540/12915840
 8         8540      12916263 TRUE   2007           Europe                2           https://www.iucnredlist.org/species/8540/12916263
 9         8541      12916598 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/8541/12916598
10          219      13034035 TRUE   2010           Mediterranean         4           https://www.iucnredlist.org/species/219/13034035 
# ℹ 42 more rows
# ℹ Use `print(n = ...)` to see more rows
```

--------------------------------

### List element names from parsed assessment data

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Displays the element names available in a parsed assessment data object. The output shows all named elements such as 'assessment_date', 'red_list_category', and 'taxon'. These names can be passed to extract_element() to get tidy dataframes.

```r
element_names()

 [1] "assessment_date"               "assessment_id"                 "assessment_points"             "assessment_ranges"             "biogeographical_realms"        "citation"                     
 [7] "conservation_actions"          "conservation_actions_in_place" "credits"                       "criteria"                      "errata"                        "faos"                         
[13] "growth_forms"                  "habitats"                      "latest"                        "lmes"                          "locations"                     "population_trend"             
[19] "possibly_extinct"              "possibly_extinct_in_the_wild"  "red_list_category"             "references"                    "researches"                    "scopes"                       
[25] "sis_taxon_id"                  "stresses"                      "supplementary_info"            "systems"                       "taxon"                         "taxon_common_names"           
[31] "taxon_ssc_groups"              "taxon_synonyms"                "threats"                       "url"                           "use_and_trade"                 "year_published"      
```

--------------------------------

### rl_version function signature

Source: https://iucn-uk.github.io/iucnredlist/reference/rl_version.html

The usage signature for the rl_version function, showing it accepts a single argument 'api'.

```r
rl_version(api)
```

--------------------------------

### Loop to get latest global assessments for custom species list

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Iterates over each row in the custom species tibble, calls assessments_by_name() for each, binds results into a tibble, and filters for latest global assessments (latest == TRUE and scopes_code == 1).

```r
assessments <-list()

for(i in 1:nrow(my_species)){
  assessments[[i]] <- assessments_by_name(api, 
                                          genus = my_species$genus[i], 
                                          species = my_species$species[i])
}

# Unlist into a tibble
a <- dplyr::bind_rows(assessments)

# Filter on latest global assessments
a <- a %>% 
  dplyr::filter(latest == TRUE & scopes_code == 1)
```

--------------------------------

### gss_data_all()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Fetch all green status of species (gss) assessment data.

```APIDOC
## gss_data_all()

### Description
Fetch all green status of species (gss) assessment data.

### Usage
gss_data_all()

```

--------------------------------

### Usage: gss_data_all(api)

Source: https://iucn-uk.github.io/iucnredlist/reference/gss_data_all.html

Function signature for gss_data_all. The argument 'api' is an {httr2} response object created with init_api().

```r
gss_data_all(api)
```

--------------------------------

### Function usage: assessments_by_sis_id(api, sis_taxon_id)

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_sis_id.html

Shows the function signature for assessments_by_sis_id(). The api argument is an httr2 response object from init_api(), and sis_taxon_id is an integer SIS taxon ID.

```R
assessments_by_sis_id(api, sis_taxon_id)
```

--------------------------------

### Function usage signature for assessments_by_taxonomy

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_taxonomy.html

Shows the formal arguments of assessments_by_taxonomy(): api, level, name, year_published, latest, scope_code, and wait_time. Use this as a reference for calling the function.

```R
assessments_by_taxonomy(
  api,
  level,
  name,
  year_published = NULL,
  latest = TRUE,
  scope_code = NULL,
  wait_time = 0.5
)
```

--------------------------------

### list_codes()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

List group codes.

```APIDOC
## list_codes()

### Description
List group codes.

### Usage
list_codes()

```

--------------------------------

### Extract threats with extract_element()

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Shows how to extract threats from the felidae_full object using extract_element() and then view the resulting tibble. The output includes columns like scope, timing, internationalTrade, score, severity, and code, with 653 rows total.

```r
threats <- extract_element(felidae_full, "threats")

threats

# A tibble: 653 × 13
   index   assessment_id scope timing                   internationalTrade score         severity ancestry virus ias   text  description                                       code 
   <chr>   <chr>         <chr> <chr>                    <chr>              <chr>         <chr>    <chr>    <chr> <chr> <chr> <chr>                                             <chr>
 1 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Agro-industry farming                             2_1_3
 2 threats 3299247       NA    Past, Unlikely to Return NA                 Past Impact   NA       NA       NA    NA    NA    Scale Unknown/Unrecorded                          2_3_4
 3 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Nomadic grazing                                   2_3_1
 4 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Intentional use (species is the target)           5_1_1
 5 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Agro-industry grazing, ranching or farming        2_3_3
 6 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Problematic native species/diseases               8_2  
 7 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Persecution/control                               5_1_3
 8 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Unintentional effects (species is not the target) 5_1_2
 9 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Small-holder grazing, ranching or farming         2_3_2
10 threats 3299247       NA    Ongoing                  NA                 Low Impact: 3 NA       NA       NA    NA    NA    Trend Unknown/Unrecorded                          7_1_3
# ℹ 643 more rows
# ℹ Use `print(n = ...)` to see more rows
```

--------------------------------

### Run R CMD check via devtools

Source: https://iucn-uk.github.io/iucnredlist/index.html

Run this in the R console to execute R CMD check, a requirement for pull requests and CRAN submission. Uses devtools.

```R
check()
```

--------------------------------

### assessments_by_group() function signature

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_group.html

The usage block shows the formal arguments of assessments_by_group(). It requires an api object from init_api(), a group name, and a code. Optional arguments include year_published, latest (default TRUE), scope_code (default NULL), wait_time (default 0.5), and show_warnings (default TRUE).

```r
assessments_by_group(
  api,
  group,
  code,
  year_published = NULL,
  latest = TRUE,
  scope_code = NULL,
  wait_time = 0.5,
  show_warnings = TRUE
)
```

--------------------------------

### Query assessments by habitat group

Source: https://iucn-uk.github.io/iucnredlist/articles/assessment-data-responses.html

Returns a minimal tibble of assessments matching habitat code 1. The output shows 114 rows with columns including sis_taxon_id, assessment_id, latest, year_published, scopes_description_en, scopes_code, and url. Use print(n = ...) to see more rows.

```R
a <- assessments_by_group(api, "habitats", "1")

# A tibble: 114 × 7
   sis_taxon_id assessment_id latest year_published scopes_description_en scopes_code url                                               
          <int>         <int> <lgl>  <chr>          <chr>                 <chr>       <chr>                                             
 1       133958       3881104 TRUE   2008           Global                1           https://www.iucnredlist.org/species/133958/3881104
 2       134059       3887925 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134059/3887925
 3       134019       3893117 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134019/3893117
 4       134151       3910739 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134151/3910739
 5       134199       3918266 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134199/3918266
 6       134378       3947233 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134378/3947233
 7       134409       3952097 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134409/3952097
 8       134409       3952097 TRUE   2008           Eastern Africa        18          https://www.iucnredlist.org/species/134409/3952097
 9       134409       3952097 TRUE   2008           Pan-Africa            10          https://www.iucnredlist.org/species/134409/3952097
10       134438       3956693 TRUE   2008           Global                1           https://www.iucnredlist.org/species/134438/3956693
# ℹ 104 more rows
# ℹ Use `print(n = ...)` to see more rows
```

--------------------------------

### gss_data_all(api)

Source: https://iucn-uk.github.io/iucnredlist/reference/gss_data_all.html

Returns full assessment data for all green status of species assessments. The function accepts an httr2 response object created with init_api() and returns an unprocessed named list of assessment data.

```APIDOC
## gss_data_all(api)

### Description
Returns full assessment data for all green status of species assessments.

### Usage
```r
gss_data_all(api)
```

### Arguments
- **api** - An `{httr2}` response object created with `init_api()`.

### Value
Returns an unprocessed named list of assessment data for all green status of species assessments. The raw JSON from the gss endpoint has been coerced to a list but is otherwise an exact representation of the response from the assessment endpoint.

### Examples
```r
if (FALSE) { # \dontrun{
gss_data_all(api)
} # }
```
```

--------------------------------

### Fetch full assessment data for multiple assessments

Source: https://iucn-uk.github.io/iucnredlist/articles/assessment-data-responses.html

Loops over each assessment ID in the filtered minimal dataframe to gather full assessment data for each assessment using assessment_data_many().

```R
all_data <- assessment_data_many(api, ea$assessment_id)
```

--------------------------------

### Create custom species tibble

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Builds a tibble with genus and species columns for a custom list of species. Used as input for gathering assessment data by name.

```r
my_species <- dplyr::tibble(genus = c("Panthera", "Diceros", "Cyclura"), 
                            species = c("leo", "bicornis", "pinguis"))
```

--------------------------------

### assessments_by_name(api, genus, species)

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_name.html

Returns minimal assessment data for a supplied Latin binomial. The genus and species arguments are not case sensitive.

```APIDOC
## assessments_by_name(api, genus, species)

### Description
Returns minimal assessment data for a supplied Latin binomial. The genus and species arguments are not case sensitive.

### Usage
assessments_by_name(api, genus, species)

### Arguments
- **api** (httr2 response object) - Required - An httr2 response object created with init_api().
- **genus** (string) - Required - A genus name.
- **species** (string) - Required - A species name.

### Value
Returns a tibble() of minimal assessment data for the supplied genus and species name. The minimal assessment data provides assessment_ids and sis_taxon_ids which can then be used with assessment_data(), assessment_data_many() and parse_assessment_data() to get full assessment data.

### Example
```r
if (FALSE) { # \dontrun{
assessments_by_name(api, "panthera", "leo")
} # }
```
```

--------------------------------

### View habitats tibble output

Source: https://iucn-uk.github.io/iucnredlist/articles/gather-common-data.html

Displays the first 10 rows of the habitats tibble for the Felidae assessment, showing columns like assessment_id, majorImportance, season, suitability, description, and code. The output is truncated with 442 more rows.

```r
habitats

# A tibble: 452 × 7
   index    assessment_id majorImportance season suitability description                                                               code 
   <chr>    <chr>         <chr>           <chr>  <chr>       <chr>                                                                     <chr>
 1 habitats 3299247       NA              NA     Suitable    Wetlands (inland) - Shrub Dominated Wetlands                              5_3  
 2 habitats 3299247       NA              NA     Suitable    Grassland - Subtropical/Tropical High Altitude                            4_7  
 3 habitats 3299247       NA              NA     Suitable    Wetlands (inland) - Permanent Rivers/Streams/Creeks (includes waterfalls) 5_1  
 4 habitats 3299247       NA              NA     Suitable    Forest - Subtropical/Tropical Dry                                         1_5  
 5 habitats 3299247       NA              NA     Suitable    Savanna - Dry                                                             2_1  
 6 habitats 3299247       NA              NA     Suitable    Grassland - Subtropical/Tropical Dry                                      4_5  
 7 habitats 3299247       NA              NA     Suitable    Grassland - Subtropical/Tropical Seasonally Wet/Flooded                   4_6  
 8 habitats 3350985       NA              NA     Suitable    Shrubland - Boreal                                                        3_3  
 9 habitats 3350985       NA              NA     Suitable    Shrubland - Subtropical/Tropical Dry                                      3_5  
10 habitats 3350985       NA              NA     Suitable    Shrubland - Temperate                                                     3_4  
# ℹ 442 more rows
# ℹ Use `print(n = ...)` to see more rows
```

--------------------------------

### assessments_by_sis_id(api, sis_taxon_id)

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_sis_id.html

Returns minimal assessment data for a supplied SIS taxon ID. The function takes an httr2 response object created with init_api() and an integer SIS taxon ID, and returns a tibble of assessment_ids for that taxon.

```APIDOC
## Function: assessments_by_sis_id(api, sis_taxon_id)

### Description
Returns minimal assessment data for a supplied SIS taxon ID. The minimal assessment data provides assessment_ids and sis_taxon_ids (as a tibble) which can be used with assessment_data(), assessment_data_many(), and parse_assessment_data() to get full assessment data.

### Usage
```r
assessments_by_sis_id(api, sis_taxon_id)
```

### Arguments
- **api** (httr2 response object) - Required - An httr2 response object created with init_api().
- **sis_taxon_id** (integer) - Required - A valid SIS taxon ID.

### Value
Returns a tibble() of minimal assessment data for the supplied SIS taxon ID. The minimal assessment data shows assessment_ids for the supplied SIS taxon ID which can then be used with assessment_data(), assessment_data_many(), and parse_assessment_data() to get full assessment data.

### Example
```r
if (FALSE) { # \dontrun{
assessments_by_sis_id(api, 230)
} # }
```
```

--------------------------------

### Usage: assessments_by_name(api, genus, species)

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_name.html

The function signature for assessments_by_name(). It takes an httr2 response object from init_api(), a genus string, and a species string.

```r
assessments_by_name(api, genus, species)
```

--------------------------------

### list_group_names()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Show API endpoint groups.

```APIDOC
## list_group_names()

### Description
Show API endpoint groups.

### Usage
list_group_names()

```

--------------------------------

### Function usage signature

Source: https://iucn-uk.github.io/iucnredlist/reference/assessment_data_many.html

Shows the usage signature for assessment_data_many(). The function takes an api object, a vector of assessment_ids, and an optional wait_time (default 0.5 seconds) to avoid hitting the IUCN Red List API rate limit.

```r
assessment_data_many(api, assessment_ids, wait_time = 0.5)
```

--------------------------------

### list_codes(api, endpoint_group)

Source: https://iucn-uk.github.io/iucnredlist/reference/list_codes.html

Returns a tibble of all codes (or names) for a specified API group. The function requires an httr2 response object from init_api() and a valid endpoint group name from list_group_names().

```APIDOC
## list_codes(api, endpoint_group)

### Description
Returns a `tibble()` of all codes (or names) for a specified API group.

### Usage
```r
list_codes(api, endpoint_group)
```

### Arguments
- **api** (httr2 response object) - Required - An httr2 response object created with `init_api()`.
- **endpoint_group** (string) - Required - A valid API group name which can be found by calling `list_group_names()`.

### Value
A tibble of codes or, in the case of Comprehensive Groups, names.

### Examples
```r
if (FALSE) { # \dontrun{
list_codes(api, "threats")
} # }
```
```

--------------------------------

### parse_gss_data()

Source: https://iucn-uk.github.io/iucnredlist/reference/index.html

Parse raw green status of species (gss) assessment data.

```APIDOC
## parse_gss_data()

### Description
Parse raw green status of species (gss) assessment data.

### Usage
parse_gss_data(raw_data)

### Arguments
- **raw_data** - Raw gss assessment data to parse.

```

--------------------------------

### assessments_by_taxonomy(api, level, name, year_published, latest, scope_code, wait_time)

Source: https://iucn-uk.github.io/iucnredlist/reference/assessments_by_taxonomy.html

Returns minimal assessment data for a given taxonomic hierarchy name. The function takes an API response object, a taxonomic level, a name, and optional filters for publication year, latest/historic status, scope code, and wait time. It returns a tibble with assessment_ids and sis_taxon_ids.

```APIDOC
## assessments_by_taxonomy(api, level, name, year_published, latest, scope_code, wait_time)

### Description
Returns minimal assessment data for a given taxonomic hierarchy name. The minimal assessment data provides assessment_ids and sis_taxon_ids which can be used with assessment_data(), assessment_data_many(), and parse_assessment_data() to get full assessment data.

### Usage
```r
assessments_by_taxonomy(
  api,
  level,
  name,
  year_published = NULL,
  latest = TRUE,
  scope_code = NULL,
  wait_time = 0.5
)
```

### Arguments
- **api** (httr2 response object) - Required - An httr2 response object created with init_api().
- **level** (string) - Required - The level of taxonomic hierarchy. Must be one of: kingdom, phylum, class, order, or family.
- **name** (string) - Required - The name of the taxonomic hierarchy.
- **year_published** (integer) - Optional - The publication year you wish to filter.
- **latest** (boolean) - Optional - Return latest or historic assessments. Defaults to TRUE.
- **scope_code** (string) - Optional - A valid assessment scope. Defaults to NULL (i.e., returns assessments of all scopes). Valid scope codes can be found by calling list_codes(api, "scopes").
- **wait_time** (numeric) - Optional - Time in seconds to wait between API calls. A wait of 0.5 seconds or greater will ensure you won't hit the IUCN Red List API rate limit. Defaults to 0.5.

### Value
Returns a tibble of minimal assessment data for the specified arguments. The minimal assessment data provides assessment_ids and sis_taxon_ids which can be used with assessment_data(), assessment_data_many(), and parse_assessment_data() to get full assessment data.

### Examples
```r
if (FALSE) { # \dontrun{
assessments_by_taxonomy(api,
  level = "family",
  name = "felidae",
  year_published = 2022,
  latest = TRUE,
  scope_code = 1,
  wait_time = 0.5
)
} # }
```
```
Tokens:
Raw