Introduction to rredlist

rredlist is an R client for the IUCN Red List API. The IUCN Red List is the world’s most comprehensive information source on the global extinction risk status of animal, fungus and plant species. This package provides access via R to the various data contained within this database which span range details, population size, habitat and ecology, use and/or trade, threats, and conservation actions.

What `rredlist` is not:

redlistr is a different package for contributors to the IUCN Red List - not working with the IUCN Red List API.
rredlist does not include support for spatial data from the IUCN Red List. IUCN Red List Spatial data can be downloaded from the IUCN website.

Installation

CRAN

install.packages("rredlist")

Development version

# From GitHub
remotes::install_github("ropensci/rredlist")

# From r-universe
install.packages("rredlist", repos = "https://ropensci.r-universe.dev/")

Authentication

IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. The rl_use_iucn() function in the package can walk you through getting your own key and storing it locally. Once you store this key, the functions in rredlist will always default to using this key.

rredlist::rl_use_iucn()

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 (iucn_redlist_key) - we recommend using the former option.

Overview of available features

Query assessments by taxa (e.g., rl_species() and rl_family())
Query assessments by habitats (e.g., rl_habitats() and rl_systems())
Query assessments by geography (e.g., rl_countries() and rl_realms())
Query assessments by actions needed (e.g., rl_actions() and rl_research())
Query assessments by threat details (e.g., rl_threats() and rl_pop_trends())
Query assessments for specific sets of taxa (e.g., rl_extinct() and rl_growth_forms())
Get all details for a single assessment (e.g., rl_species_latest() and rl_assessment())
Red List information and statistics (e.g., rl_sp_count() and rl_version())

Example usage

Loading the package

library("rredlist")

Search for assessments for a particular species

rl_species("Gorilla", "gorilla")$assessments
#>    year_published latest possibly_extinct possibly_extinct_in_the_wild sis_taxon_id
#> 1            2016  FALSE            FALSE                        FALSE         9404
#> 2            2018   TRUE            FALSE                        FALSE         9404
#> 3            2016  FALSE            FALSE                        FALSE         9404
#> 4            2008  FALSE            FALSE                        FALSE         9404
#> 5            2007  FALSE            FALSE                        FALSE         9404
#> 6            2000  FALSE            FALSE                        FALSE         9404
#> 7            1996  FALSE            FALSE                        FALSE         9404
#> 8            1994  FALSE            FALSE                        FALSE         9404
#> 9            1990  FALSE            FALSE                        FALSE         9404
...

Search for assessments that recommend particular conservation actions

Get a list of all conservation actions

rl_actions()
#> $conservation_actions
#>                                              en  code
#> 1                         Land/water protection     1
#> 2                          Site/area protection   1_1
#> 3                 Resource & habitat protection   1_2
#> 4                         Land/water management     2
#> 5                          Site/area management   2_1
#> 6          Invasive/problematic species control   2_2
#> 7         Habitat & natural process restoration   2_3
#> 8                            Species management     3
...

Return assessments with a particular conservation action

rl_actions("2_2", all = FALSE)$assessments
#>    year_published latest possibly_extinct possibly_extinct_in_the_wild sis_taxon_id
#> 1            2019   TRUE            FALSE                        FALSE    132523146
#> 2            2019   TRUE            FALSE                        FALSE        10767
#> 3            2013   TRUE            FALSE                        FALSE         1078
#> 4            2019   TRUE            FALSE                        FALSE    132521900
#> 5            2020  FALSE            FALSE                        FALSE         1086
#> 6            2019   TRUE            FALSE                        FALSE         1117
#> 7            2019  FALSE            FALSE                        FALSE        11797
#> 8            2021   TRUE            FALSE                        FALSE        12124
#> 9            2025   TRUE            FALSE                        FALSE    232775771
...

Advanced usage

For a more in-depth walkthrough of how to integrate rredlist into research workflows, check out the vignette.

High level vs. low level interfaces

High level interface

library("rredlist")

High level functions do the HTTP request and parse data to a list for ease of downstream use. The high level functions have no underscore on the end of the function name, e.g., rl_species(). Most of them return long lists containing lots of different information:

rl_species("Fratercula", "arctica")
#> $taxon
#> $taxon$sis_id
#> [1] 22694927
#> 
#> $taxon$scientific_name
#> [1] "Fratercula arctica"
#> 
#> $taxon$species_taxa
#> list()
#> 
...

By default, these high level functions will also parse the data to a data.frame, when possible:

rl_species("Fratercula", "arctica")$assessments
#>    year_published latest possibly_extinct possibly_extinct_in_the_wild sis_taxon_id
#> 1            2021   TRUE            FALSE                        FALSE     22694927
#> 2            2018   TRUE            FALSE                        FALSE     22694927
#> 3            2017  FALSE            FALSE                        FALSE     22694927
#> 4            2017  FALSE            FALSE                        FALSE     22694927
#> 5            2016  FALSE            FALSE                        FALSE     22694927
#> 6            2015  FALSE            FALSE                        FALSE     22694927
#> 7            2015  FALSE            FALSE                        FALSE     22694927
#> 8            2012  FALSE            FALSE                        FALSE     22694927
#> 9            2009  FALSE            FALSE                        FALSE     22694927
...

Likely a bit faster is to parse to a list only, and not take the extra data.frame parsing time:

rl_species("Fratercula", "arctica", parse = FALSE)$assessments
#> [[1]]
#> [[1]]$year_published
#> [1] "2021"
#> 
#> [[1]]$latest
#> [1] TRUE
#> 
#> [[1]]$possibly_extinct
#> [1] FALSE
#> 
...

For even more speed, you can use the low level package interface (although see the benchmarking vignette for specifics).

Low level interface

The parsing to data.frame in the high level functions does take extra time. The low level functions only do the HTTP request, and give 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_species_():

rl_species_("Fratercula", "arctica")
#> [1] "{\"taxon\":{\"sis_id\":22694927,\"scientific_name\":\"Fratercula arctica\",\"species_taxa\":[],\"subpopulation_taxa\":[],\"infrarank_taxa\":[],\"kingdom_name\":\"ANIMALIA\",\"phylum_name\":\"CHORDATA\",\"class_name\":\"AVES\",\"order_name\":\"CHARADRIIFORMES\",\"family_name\":\"ALCIDAE\",\"genus_name\":\"Fratercula\",\"species_name\":\"arctica\",\"subpopulation_name\":null,\"infra_name\":null,\"authority\":\"(Linnaeus, 1758)\",\"species\":true,\"subpopulation\":false,\"infrarank\":false,\"ssc_groups\":[{\"name\":\"IUCN SSC Bird Red List Authority (BirdLife International)\",\"url\":\"https://www.birdlife.org/\",\"description\":\"Red List Authority Coordinator: Ian Burfield (ian.burfield@birdlife.org)\"}],\"common_names\":[{\"main\":false,\"name\":\"Puffin\",\"language\":\"eng\"},{\"main\":true,\"name\":\"Atlantic Puffin\",\"language\":\"eng\"}],\"synonyms\":[]},\"assessments\":[{\"year_published\":\"2021\",\"latest\":true,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/166290968\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"EN\",\"assessment_id\":166290968,\"scopes\":[{\"description\":{\"en\":\"Europe\"},\"code\":\"2\"}]},{\"year_published\":\"2018\",\"latest\":true,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/132581443\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"VU\",\"assessment_id\":132581443,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2017\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/117606911\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"VU\",\"assessment_id\":117606911,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2017\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/110638141\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"VU\",\"assessment_id\":110638141,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2016\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/93477427\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"VU\",\"assessment_id\":93477427,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2015\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/82593109\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"VU\",\"assessment_id\":82593109,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2015\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/60110592\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"EN\",\"assessment_id\":60110592,\"scopes\":[{\"description\":{\"en\":\"Europe\"},\"code\":\"2\"}]},{\"year_published\":\"2012\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/38908739\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"LC\",\"assessment_id\":38908739,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2009\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28178290\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"LC\",\"assessment_id\":28178290,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2008\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28179292\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"LC\",\"assessment_id\":28179292,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2004\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28180639\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"LC\",\"assessment_id\":28180639,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2000\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28181882\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"LR/lc\",\"assessment_id\":28181882,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"1994\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28183212\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"LR/lc\",\"assessment_id\":28183212,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"1988\",\"latest\":false,\"possibly_extinct\":false,\"possibly_extinct_in_the_wild\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/28184380\",\"taxon_scientific_name\":\"Fratercula arctica\",\"red_list_category_code\":\"LR/lc\",\"assessment_id\":28184380,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]}],\"params\":{\"genus_name\":\"Fratercula\",\"species_name\":\"arctica\"}}"

To consume this JSON, you can use jsonlite:

library("jsonlite")
fromJSON(rl_species_("Fratercula", "arctica"))
#> $taxon
#> $taxon$sis_id
#> [1] 22694927
#> 
#> $taxon$scientific_name
#> [1] "Fratercula arctica"
#> 
#> $taxon$species_taxa
#> list()
#> 
...

Usage best practice

Citing the IUCN Red List API

Use the function rl_citation():

rl_citation()
#> To cite the IUCN API in publications, use the following citation:
#> 
#>   IUCN (2025). "IUCN Red List of Threatened Species." <https://www.iucnredlist.org>. Accessed on 25 July
#>   2025.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Misc{IUCN2025,
#>     author = {{IUCN}},
#>     title = {IUCN Red List of Threatened Species},
#>     year = {2025},
#>     edition = {Version 2025-1},
#>     howpublished = {\url{https://www.iucnredlist.org}},
#>     note = {Accessed on 25 July 2025},
#>   }

We’d also really appreciate it if you could cite your use of this package:

citation("rredlist")
#> To cite package 'rredlist' in publications use:
#> 
#>   Gearty W, Chamberlain S (2025). _rredlist: 'IUCN' Red List Client_. doi:10.32614/CRAN.package.rredlist
#>   <https://doi.org/10.32614/CRAN.package.rredlist>, R package version 1.0.0,
#>   <https://docs.ropensci.org/rredlist/>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{rredlist,
#>     title = {rredlist: 'IUCN' Red List Client},
#>     author = {William Gearty and Scott Chamberlain},
#>     year = {2025},
#>     note = {R package version 1.0.0},
#>     doi = {10.32614/CRAN.package.rredlist},
#>     url = {https://docs.ropensci.org/rredlist/},
#>   }

Rate Limiting

From the IUCN folks: “Too many frequent calls, or too many calls per day might get your access blocked temporarily. If you’re a heavy API user, the Red List Unit asked that you contact them, as there might be better options. They suggest a 2-second delay between your calls if you plan to make a lot of calls.”

API Versioning

rredlist versions ≤ 0.7.1 tracked the now-defunct version 3 of the IUCN Red List API. rredlist versions ≥ 1.0.0 track version 4 of the IUCN Red List API. If you need to use version 3 of the API–and it is still functioning–you can install an old version of rredlist using the remotes package:

# From CRAN archive
remotes::install_version("rredlist", version = "0.7.1")

# From r-universe
remotes::install_version("rredlist", version = "0.7.1",
                         repos = "https://ropensci.r-universe.dev/")

Note, however, that you can no longer generate a new API key for version 3 of the API. See the discussion here for possible solutions if you need to use version 3 of the API.