Package 'redlist'

Title: Interface to the IUCN Red List Data
Description: Provides an interface to access data from the International Union for Conservation of Nature (IUCN) Red List <https://api.iucnredlist.org/api-docs/index.html>. It allows users to retrieve up-to-date information on species' conservation status, supporting biodiversity research and conservation efforts.
Authors: Stanislas Mahussi Gandaho [aut, cre] (ORCID: <https://orcid.org/0009-0003-4969-1252>)
Maintainer: Stanislas Mahussi Gandaho <[email protected]>
License: MIT + file LICENSE
Version: 0.2.0
Built: 2026-05-24 08:58:45 UTC
Source: https://github.com/stangandaho/redlist

Help Index

IUCN Red List assessment

Description

Retrieves an assessment

Usage

rl_assessment_id(assessment_id = 1425064)

Arguments

assessment_id

Assessment ID

Value

A tibble where each column represents a unique API response JSON key for the supplied assessment_id. The columns include key information about the Red List assessment, such as taxon details, category, year, and other relevant metadata.

Examples

## Not run: 
rl_assessment_id(1425064)

## End(Not run)

IUCN Red List biogeographical realms

Description

Retrieve available biogeographical realms or detailed species assessments for one or more realms.

Usage

rl_biogeographical_realms(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Numeric or Character. One or more biogeographical realm codes (e.g. 0 or "0"). Use rl_biogeographical_realms() to list available realms.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Details

This function has two modes:

  • If code = NULL, it returns a list of available biogeographical realms.

  • If code is provided, it retrieves assessments for the specified realm(s), optionally filtered by year, extinction status, scope, and page(s).

If page is not specified, the function will automatically paginate over all available pages for each parameter combination.

Value

A tibble (class ⁠tbl_df``, ⁠tbl⁠, ⁠data.frame⁠) where each column represents a unique API response JSON key. If ⁠code = NULL⁠, the tibble contains available biogeographical realms with columns such as realm code and name. If ⁠code' is provided, the tibble contains assessment data for the specified realm(s), including taxon details, red list category, year, and other relevant metadata.

Examples

## Not run: 
# List all available biogeographical realms
rl_biogeographical_realms()

# Retrieve all assessments for realm code 0
rl_biogeographical_realms(code = 0)

# Get latest assessments from multiple pages with filters
rl_biogeographical_realms(
  code = 0,
  year_published = c(2020, 2021),
  page = c(1, 2)
)

## End(Not run)

Check IUCN Red List API Status

Description

Verifies whether the IUCN Red List API is accessible and the provided API key is valid.

Usage

rl_check_api()

Value

Invisibly returns TRUE if the API is working properly. If not, the function will abort with an appropriate error message.

See Also

rl_set_api()

Examples

## Not run: 
# Check if API is properly set up
rl_check_api()

## End(Not run)

IUCN Red List taxa by class

Description

Retrieve species assessments by taxonomic class. If class_name = NULL, it returns a list of available classes. If class_name is provided, it retrieves assessments for species in the specified class.

Usage

rl_classes(
  class_name = NULL,
  year_published = NULL,
  latest = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

class_name

Character. The class name (e.g., "Mammalia"). Use rl_classes() to list available classes.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If class_name = NULL, the tibble contains available taxonomic classes with a column for class names. If class_name is provided, the tibble contains assessment data for the specified class, including taxon details, red list category, year, and other relevant metadata.

Examples

## Not run: 
# List all available classes
rl_classes()

# Get assessments for Mammalia class
rl_classes(class_name = "Mammalia")

# Get latest Aves assessments published since 2024
rl_classes(
  class_name = "Aves",
  year_published = 2024:2025,
  latest = TRUE
)

## End(Not run)

IUCN Red List Comprehensive groups

Description

Get assessment data by comprehensive group name (e.g amphibians, mammals, birds, blennies, mangrove_plants, reptiles, insects, fishes, etc). See name argument for available group names.

Usage

rl_comprehensive_groups(
  name = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

name

Character. One or more group names. Use rl_comprehensive_groups() to list available group names.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If name = NULL, the tibble contains available comprehensive group names. If name is provided, the tibble contains assessment data for the specified group(s), including taxon details, red list category, year, and other relevant metadata.

Examples

## Not run: 
rl_comprehensive_groups(name = "amphibians",
                        year_published = 2024:2025,
                        page = 1:3)

## End(Not run)

IUCN Red List conservation action

Description

Get assessment data by conservation action See actions argument for available action codes

Usage

rl_conservation_actions(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more action codes Use rl_conservation_actions() to list available action codes.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available conservation action codes. If code is provided, the tibble contains assessment data for the specified action code(s), including taxon details, red list category, year, and other relevant metadata.

Examples

## Not run: 
rl_conservation_actions(code = 1,
                        year_published = 2024:2025,
                        page = 1:3)

## End(Not run)

Retrieve IUCN Red List assessments by country

Description

Retrieves the species assessed by the IUCN for a specified countries. See code argument for available countries codes

Usage

rl_countries(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more countries ISO alpha-2 code. Use rl_countries() to list available countries codes.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available country codes. If code is provided, the tibble contains assessment data for the specified country code(s), including taxon details, red list category, year, and other relevant metadata

Examples

## Not run: 
  # Retrieve assessments for Benin (country code "BJ") for the year 2020
  rl_countries("BJ", year = 2020)

  # Retrieve all assessments for Brazil (country code "BR")
  rl_countries("BR", page = 2)

  # Retrieve assessments for Canada (country code "CA") on specific pages
  rl_countries("CA", page = c(1, 2))

## End(Not run)

IUCN Red List taxa by family

Description

Retrieve species assessments by taxonomic family. If family_name = NULL, it returns a list of available families. If family_name is provided, it retrieves assessments for species in the specified family.

Usage

rl_family(
  family_name = NULL,
  year_published = NULL,
  latest = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

family_name

Character. The family name (e.g., "Felidae"). Use rl_family() to list available families.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If family_name = NULL, the tibble contains available family names. If family_name is provided, the tibble contains assessment data for the specified family, including taxon details, red list category, year, and other relevant metadata.

Examples

## Not run: 
# List all available families
rl_family()

# Get assessments for Felidae family
rl_family(family_name = "Felidae")

# Get latest Canidae assessments published from 2019 to 2022
rl_family(
  family_name = "Canidae",
  year_published = 2019:2022,
  latest = TRUE
)

## End(Not run)

FAO marine fishing areas

Description

List or retrieve IUCN Red List assessments for FAO Marine Fishing Areas.

Usage

rl_faos(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more FAO region codes (e.g. "21", "27"). Use rl_faos() with no arguments to list available FAO region codes.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Details

If code is NULL, this returns the available FAO region codes and their descriptions. If a code (or multiple codes) is provided, retrieves the IUCN assessments for those regions.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available FAO region codes and their descriptions. If code is provided, the tibble contains assessment data for the specified FAO region(s), including description, taxon details, red list category, year, and other relevant metadata.

Examples

## Not run: 
# List available FAO regions
rl_faos()

# Get assessments for FAO region 27
rl_faos(code = "27")

# Get assessments for regions 21 and 27 on page 1
rl_faos(code = c("21", "27"), page = 1)

## End(Not run)

Green status

Description

Retrieve all IUCN Green Status assessments.

Usage

rl_green_status()

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. The columns include key information about the Green Status assessment, such as year, weights, justification, and other relevant metadata.

Examples

## Not run: 
rl_green_status()

## End(Not run)

Growth forms

Description

Retrieve IUCN Red List assessments by growth form.

Usage

rl_growth_forms(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more growth form codes (e.g. "TREE", "SHRUB"). Use rl_growth_forms() with no arguments to list available growth form codes.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Details

If code is NULL, this returns the available growth form codes and their descriptions. If a code (or multiple codes) is provided, retrieves the IUCN assessments for those growth forms.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available growth form codes and their descriptions. If code is provided, the tibble contains assessment data for the specified growth form(s), including year, taxon details, and other relevant metadata.

Examples

## Not run: 
# List available growth form codes
rl_growth_forms()

# Get assessments for tree growth form (e.g Geophyte)
rl_growth_forms(code = "GE")

# Get assessments for multiple growth forms (e.g Hydrophyte, Lithophyte)
rl_growth_forms(code = c("H", "L"), page = c(1, 2))

## End(Not run)

Habitats

Description

Retrieve IUCN Red List assessments by habitat classification.

Usage

rl_habitats(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more habitat classification codes. Use rl_habitats() with no arguments to list available habitat codes.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available habitat codes and their descriptions. If code is provided, the tibble contains assessment data for the specified habitat(s), including taxon details, description, red list category, year, assessment id, and other relevant metadata.

Examples

## Not run: 
# Retrieve available habitat codes
rl_habitats()

# Retrieve assessments for the Desert
rl_habitats(code = 8)

## End(Not run)

IUCN Red List taxa by kingdom

Description

Retrieve species assessments by kingdom. If kingdom_name = NULL, it returns a list of available kingdoms. If kingdom_name is provided, it retrieves assessments for species in the specified kingdom.

Usage

rl_kingdoms(
  kingdom_name = NULL,
  year_published = NULL,
  latest = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

kingdom_name

Character. The kingdom name (e.g., "Animalia"). Use rl_kingdoms() to list available kingdoms.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If kingdom_name = NULL, the tibble contains available kingdom names. If kingdom_name is provided, the tibble contains assessment data for the specified kingdom, including taxon details, red list category, year, and other relevant metadata.

Examples

## Not run: 
# List all available kingdoms
rl_kingdoms()

# Get assessments for species in Animalia kingdom
rl_kingdoms(kingdom_name = "Animalia")

# Get latest assessments for Plantae published in 2021
rl_kingdoms(
  kingdom_name = "Plantae",
  year_published = 2021,
  latest = TRUE
)

## End(Not run)

Open file for editing

Description

Opens a specified file for editing in the system's default editor (as configured by R).

Usage

rl_open_file(path = NULL, scope = c("user", "project"))

Arguments

path

Optional character string specifying the path to the file to open. If NULL (default), a .Renviron file is opened based on the value of scope.
scope

Character string indicating which .Renviron file to open when path = NULL:

  • user: Opens the user-level .Renviron

  • project: Opens or creates a .Renviron file in the current working directory

Value

(Invisibly) returns the path to the file opened.

Examples

## Not run: 
# Open user-level .Renviron
open_file()

## End(Not run)

IUCN Red List taxa by order

Description

Retrieve species assessments by taxonomic order. If order_name = NULL, it returns a list of available orders. If order_name is provided, it retrieves assessments for species in the specified order.

Usage

rl_orders(
  order_name = NULL,
  year_published = NULL,
  latest = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

order_name

Character. The order name (e.g., "Carnivora"). Use rl_orders() to list available orders.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If order_name = NULL, the tibble contains available taxonomic orders with a column for order names. If order_name is provided, the tibble contains assessment data for the specified order, including year, taxon details, criteria, and other relevant metadata.

Examples

## Not run: 
# List all available orders
rl_orders()

# Get assessments for Carnivora order
rl_orders(order_name = "Carnivora")

# Get latest Primates assessments published in 2022
rl_orders(
  order_name = "Primates",
  year_published = 2022,
  latest = TRUE
)

## End(Not run)

IUCN Red List taxa by phylum

Description

Retrieve species assessments by phylum. If phylum_name = NULL, it returns a list of available phyla. If phylum_name is provided, it retrieves assessments for species in the specified phylum.

Usage

rl_phylum(
  phylum_name = NULL,
  year_published = NULL,
  latest = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

phylum_name

Character. The phylum name (e.g., "Chordata"). Use rl_phylum() to list available phyla.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If phylum_name = NULL, the tibble contains available phylum names. If phylum_name is provided, the tibble contains assessment data for the specified phylum, year, latest, possibly extincts, and other relevant metadata.

Examples

## Not run: 
# List all available phyla
rl_phylum()

# Get assessments for species in Chordata phylum
rl_phylum(phylum_name = "Chordata")

# Get latest assessments for Arthropoda published in 2020
rl_phylum(
  phylum_name = "Arthropoda",
  year_published = 2020,
  latest = TRUE
)

## End(Not run)

IUCN Red List population trends

Description

Retrieve available population trend categories or species assessments for one or more trends.

Usage

rl_population_trends(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character or Numeric. One or more population trend codes (0-3). Use rl_population_trends() to list available trend codes and definition.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Details

This function has two modes:

  • If code = NULL, it returns a list of available population trend categories.

  • If code is provided, it retrieves assessments for the specified trend(s), optionally filtered by year, extinction status, scope, and page(s).

Population trends include: Increasing, Decreasing, Stable, or Unknown.

If page is not specified, the function will automatically paginate over all available pages for each parameter combination.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available population trend categories with columns such as code and description. If code is provided, the tibble contains assessment data for the specified trend(s), including population trend description, population trend code, year, latest, and other relevant metadata.

Examples

## Not run: 
# List all available population trend categories
rl_population_trends()

# Retrieve assessments for species with decreasing populations
rl_population_trends(code = "1")

# Get latest decreasing population assessments from 2020
rl_population_trends(
  code = 2,
  year_published = 2020,
  latest = TRUE
)

## End(Not run)

IUCN Red List possibly extinct taxa

Description

Retrieve species assessments flagged as possibly extinct. Returns all latest global assessments for taxa that are possibly extinct.

Usage

rl_possibly_extinct()

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. Columns include year, latest, possibly extinct, possibly extinct in the wild, sis taxon id, url, taxon scientific name, red list category, assessment id, scopes description, and scopes code

Examples

## Not run: 
# Get all possibly extinct species
rl_possibly_extinct()

## End(Not run)

IUCN Red List possibly extinct in the wild taxa

Description

Retrieve species assessments flagged as possibly extinct in the wild. Returns all latest global assessments for taxa that are possibly extinct in the wild.

Usage

rl_possibly_extinct_in_wild()

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. Columns include year, latest, possibly extinct, possibly extinct in the wild, sis taxon id, url, taxon scientific name, red list category, assessment id, scopes description, and scopes code

Examples

## Not run: 
# Get all possibly extinct in the wild species
rl_possibly_extinct_in_wild()

## End(Not run)

IUCN Red List Categories

Description

Retrieve species assessments based on their Red List threat categories. If code = NULL, it returns a list of available Red List categories. If code is provided, it retrieves assessments for species in the specified category(ies).

Usage

rl_red_list_categories(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more Red List category codes (e.g., "CR", "EN"). Use rl_red_list_categories() to list available categories.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available Red List categories with columns such as code and description. If code is provided, the tibble contains assessment data for the specified category(ies), including year, taxon details, and other relevant metadata.

Examples

## Not run: 
# List all Red List categories
rl_red_list_categories()

# Get Critically Endangered species assessments
rl_red_list_categories(code = "CR")

# Get Vulnerable species assessments published in 2020
rl_red_list_categories(
  code = "VU",
  year_published = 2020
)

## End(Not run)

IUCN Red List research categories

Description

Retrieve species assessments based on their research needs categories. If code = NULL, it returns a list of available research categories. If code is provided, it retrieves assessments for species with the specified research need(s).

Usage

rl_research(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character Or Numeric. One or more research category codes (e.g., "1", "2"). Use rl_research() to list available research categories.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available research categories with columns such as code and description. If code is provided, the tibble contains assessment data for the specified research need(s), including description, research code, year, taxon details, and other relevant metadata.

Examples

## Not run: 
# List all research categories
rl_research()

# Get species needing population trends research (code 3_1)
rl_research(code = "3_1")

# Get species needing life history & ecology research published since 2019
rl_research(
  code = "1_3",
  year_published = 2019:2023
)

## End(Not run)

IUCN Red List taxa by scientific name

Description

Retrieve species assessments using scientific names (Latin binomials). Returns summary assessment data including both latest and historic assessments.

Usage

rl_scientific_name(
  genus_name,
  species_name,
  infra_name = NULL,
  subpopulation_name = NULL
)

Arguments

genus_name

Character. The genus name (required).
species_name

Character. The species name (required).
infra_name

Character. The infraspecific name (optional).
subpopulation_name

Character. The subpopulation name (optional).

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. The tibble contains assessment data for the specified taxon, including taxon details.

Examples

## Not run: 
# Get assessments for Panthera leo (lion)
rl_scientific_name(genus_name = "Panthera", species_name = "leo")

## End(Not run)

IUCN Red List assessment scopes

Description

Retrieve species assessments based on their geographic assessment scopes. If code = NULL, it returns a list of available assessment scopes. If code is provided, it retrieves assessments for the specified scope(s).

Usage

rl_scopes(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = scope_code %||% NA,
  page = 1
)

Arguments

code

Character or Numeric. One or more scope codes (e.g., "1", "2"). Use rl_scopes() to list available scope categories.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available assessment scopes with columns such as code and description. If code is provided, the tibble contains assessment data for the specified scope(s), including, description, year, latest, taxon details, and other relevant metadata.

Examples

## Not run: 
# List all assessment scopes
rl_scopes()

# Get globally assessed species (code 1)
rl_scopes(code = "1")

# Get Pan-Africa species assessed species published since 2020
rl_scopes(
  code = "2",
  year_published = 2020:2023
)

## End(Not run)

Set the IUCN Red List API key

Description

The function provide steps to set the IUCN Red List API key.

Usage

rl_set_api(api_key)

Arguments

api_key

Character. The API key provided by the IUCN Red List to authenticate requests, obtainable at IUCN Red List API website.

Value

Invisibly returns NULL after setting the API key.

Examples

## Not run: 
# Set the API key for the IUCN Red List
rl_set_api("your_api_key")

## End(Not run)

IUCN Red List taxa by SIS ID

Description

Retrieve species assessments using the Species Information Service (SIS) identifier. Returns summary assessment data including both latest and historic assessments.

Usage

rl_sis(sis_id = 179359)

Arguments

sis_id

Numeric. One or more SIS identifiers for taxa.

Value

A tibble (class tbl_df, tbl, data.frame) containing assessment data for the specified SIS ID(s).

Examples

## Not run: 
# Get assessments for species with SIS ID 179359
rl_sis(179359)

## End(Not run)

IUCN Red List statistics

Description

Retrieve count of species with assessments. This endpoint returns the total number of assessed species on the IUCN Red List.

Usage

rl_statistics()

Value

A tibble (class tbl_df, tbl, data.frame) containing count and date of access.

Examples

## Not run: 
# Get total count of assessed species
rl_statistics()

## End(Not run)

IUCN Red List stress categories

Description

Retrieve species assessments based on stress categories affecting species. If code = NULL, it returns a list of available stress categories. If code is provided, it retrieves assessments for species affected by the specified stress(es).

Usage

rl_stresses(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character or Numeric. One or more stress codes (e.g., "1", "2_1"). Use rl_stresses() to list available stress categories.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) containing stress categories or species assessments. If code = NULL, the tibble contains available stress categories with columns such as code and description. If code is provided, the tibble contains assessment data for the specified stress(es), including year, taxon details, and other relevant metadata.

Examples

## Not run: 
# List all stress categories
rl_stresses()

# Get species affected by ecosystem stresses (code 1)
rl_stresses(code = "1") # or code = 1

# Get species affected by competition stresses published since 2020
rl_stresses(
  code = "2_3_2",
  year_published = 2020:2023
)

## End(Not run)

IUCN Red List ecological systems

Description

Retrieve species assessments based on their ecological systems. If code = NULL, it returns a list of available ecological systems. If code is provided, it retrieves assessments for species in the specified system(s).

Usage

rl_systems(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character or Numeric. One or more system codes (e.g., "0", "1", "2"). Use rl_systems() to list available ecological systems.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available ecological systems with columns such as code and description. If code is provided, the tibble contains assessment data for the specified system(s), including description, possible extinct in the wild, scientific name, latest, taxon details, and other relevant metadata.

Examples

## Not run: 
# List all ecological systems
rl_systems()

# Get terrestrial species assessments (code 0)
rl_systems(code = 0)

# Get marine species assessments published since 2021
rl_systems(
  code = "2",
  year_published = 2021:2023
)

## End(Not run)

IUCN Red List threat categories

Description

Retrieve species assessments based on threat categories. If code = NULL, it returns a list of available threat categories. If code is provided, it retrieves assessments for species affected by the specified threat(s).

Usage

rl_threats(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more threat codes (e.g., "1"). Use rl_threats() to list available threat categories.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available threat categories with columns such as code and description. If code is provided, the tibble contains assessment data for the specified threat(s), including threat description, threat code and year.

Examples

## Not run: 
# List all threat categories
rl_threats()

# Get species affected by agriculture & aquaculture threats (code 2)
rl_threats(code = 2)

# Get species affected by Climate change & severe weather threats published in 2025
rl_threats(
  code = "11",
  year_published = 2025
)

## End(Not run)

IUCN Red List use and trade categories

Description

Retrieve species assessments based on use and trade categories. If code = NULL, it returns a list of available use and trade categories. If code is provided, it retrieves assessments for species affected by the specified use/trade category(ies).

Usage

rl_use_and_trade(
  code = NULL,
  year_published = NULL,
  latest = NULL,
  possibly_extinct = NULL,
  possibly_extinct_in_the_wild = NULL,
  scope_code = NULL,
  page = 1
)

Arguments

code

Character. One or more use/trade codes (e.g., "1", "5_2"). Use rl_use_and_trade() to list available categories.
year_published

Optional. Single or numeric vector of years to filter assessments by publication year.
latest

Optional. Logical. If TRUE, return only the latest assessment per species.
possibly_extinct

Optional. Logical. Filter for species flagged as possibly extinct.
possibly_extinct_in_the_wild

Optional. Logical. Filter for species possibly extinct in the wild.
scope_code

Optional. Integer One or more scope codes to filter assessments.
page

Optional. Integer vector. Specify one or more page numbers to fetch. If NULL or NA, all pages will be fetched automatically.

Value

A tibble (class tbl_df, tbl, data.frame) where each column represents a unique API response JSON key. If code = NULL, the tibble contains available use and trade categories with columns such as code and description. If code is provided, the tibble contains assessment data for the specified use/trade category(ies), including description, code, year, latest, and other relevant metatdata.

Examples

## Not run: 
# List all use and trade categories
rl_use_and_trade()

# Get species used for food - human (code 1)
rl_use_and_trade(code = "1")

# Get species hunted for Sport hunting/specimen collecting published in 2024
rl_use_and_trade(
  code = "15",
  year_published = 2024
)

## End(Not run)

IUCN Red List and API version

Description

Print the current version of the IUCN Red List of Threatened Species and API

Usage

rl_version()

Value

Invisibly returns NULL after printing the Red List and API versions.

Examples

## Not run: 
rl_version()

## End(Not run)