---
# Generated by vignettes/precompile.R: do not edit by hand.
# Please edit source in vignettes/source/_rredlist.Rmd
title: "Introduction to rredlist"
author: "William Gearty"
date: "2025-01-27"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to rredlist}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---



`rredlist` is an R client for the [IUCN Red List API](https://api.iucnredlist.org/).
The [IUCN Red List](https://www.iucnredlist.org/) 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.

Documentation for the IUCN Red List API is available at https://api.iucnredlist.org/api-docs. **Note that use of the web API, and therefore this package, [requires authentication](#authentication).**

#### What `rredlist` is not:

1. [`redlistr`](https://cran.r-project.org/package=redlistr) is a different package for contributors to the IUCN Red List - not working with the IUCN Red List API.
2. `rredlist` does not include support for the spatial API, described at https://apiv3.iucnredlist.org/spatial.

## Installation

CRAN


``` r
install.packages("rredlist")
```

Development version


``` r
# 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](https://api.iucnredlist.org/users/sign_up) and storing it locally. Once you store this key, the functions in `rredlist` will always default to using this key.


``` r
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

``` r
library("rredlist")
```

### Search for assessments for a particular species

``` r
rl_species("Gorilla", "gorilla")$assessments
#>    year_published latest possibly_extinct possibly_extinct_in_the_wild sis_taxon_id                                                url assessment_id    scopes
#> 1            2016  FALSE            FALSE                        FALSE         9404 https://www.iucnredlist.org/species/9404/102330408     102330408 Global, 1
#> 2            2018   TRUE            FALSE                        FALSE         9404 https://www.iucnredlist.org/species/9404/136250858     136250858 Global, 1
#> 3            2016  FALSE            FALSE                        FALSE         9404  https://www.iucnredlist.org/species/9404/17963949      17963949 Global, 1
#> 4            2008  FALSE            FALSE                        FALSE         9404  https://www.iucnredlist.org/species/9404/12983787      12983787 Global, 1
#> 5            2007  FALSE            FALSE                        FALSE         9404  https://www.iucnredlist.org/species/9404/12983966      12983966 Global, 1
#> 6            2000  FALSE            FALSE                        FALSE         9404  https://www.iucnredlist.org/species/9404/12983737      12983737 Global, 1
#> 7            1996  FALSE            FALSE                        FALSE         9404  https://www.iucnredlist.org/species/9404/12983764      12983764 Global, 1
#> 8            1994  FALSE            FALSE                        FALSE         9404  https://www.iucnredlist.org/species/9404/12984167      12984167 Global, 1
#> 9            1990  FALSE            FALSE                        FALSE         9404  https://www.iucnredlist.org/species/9404/12984186      12984186 Global, 1
...
```

### Search for assessments that recommend particular conservation actions

#### Get a list of all conservation actions

``` r
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

``` r
rl_actions("2_2", all = FALSE)$assessments
#>     year_published latest possibly_extinct possibly_extinct_in_the_wild sis_taxon_id                                                   url assessment_id code           code_type
#> 1             2019   TRUE            FALSE                        FALSE    132523146  https://www.iucnredlist.org/species/132523146/497499        497499  2_2 conservation_action
#> 2             2019   TRUE            FALSE                        FALSE        10767      https://www.iucnredlist.org/species/10767/498370        498370  2_2 conservation_action
#> 3             2013   TRUE            FALSE                        FALSE         1078       https://www.iucnredlist.org/species/1078/498639        498639  2_2 conservation_action
#> 4             2019   TRUE            FALSE                        FALSE    132521900  https://www.iucnredlist.org/species/132521900/498826        498826  2_2 conservation_action
#> 5             2020  FALSE            FALSE                        FALSE         1086       https://www.iucnredlist.org/species/1086/499235        499235  2_2 conservation_action
#> 6             2019   TRUE            FALSE                        FALSE         1117       https://www.iucnredlist.org/species/1117/500918        500918  2_2 conservation_action
#> 7             2019   TRUE            FALSE                        FALSE        11797      https://www.iucnredlist.org/species/11797/503908        503908  2_2 conservation_action
#> 8             2021   TRUE            FALSE                        FALSE        12124      https://www.iucnredlist.org/species/12124/505402        505402  2_2 conservation_action
#> 9             2019   TRUE            FALSE                        FALSE        12695      https://www.iucnredlist.org/species/12695/507698        507698  2_2 conservation_action
...
```

## Advanced usage

For a more in-depth walkthrough of how to integrate `rredlist` into research workflows, check out [the vignette](research_workflows.html).

## High level vs. low level interfaces

### High level interface


``` r
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:


``` r
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:


``` r
rl_species("Fratercula", "arctica")$assessments
#>    year_published latest possibly_extinct possibly_extinct_in_the_wild sis_taxon_id                                                    url assessment_id    scopes
#> 1            2021   TRUE            FALSE                        FALSE     22694927 https://www.iucnredlist.org/species/22694927/166290968     166290968 Europe, 2
#> 2            2018   TRUE            FALSE                        FALSE     22694927 https://www.iucnredlist.org/species/22694927/132581443     132581443 Global, 1
#> 3            2017  FALSE            FALSE                        FALSE     22694927 https://www.iucnredlist.org/species/22694927/117606911     117606911 Global, 1
#> 4            2017  FALSE            FALSE                        FALSE     22694927 https://www.iucnredlist.org/species/22694927/110638141     110638141 Global, 1
#> 5            2016  FALSE            FALSE                        FALSE     22694927  https://www.iucnredlist.org/species/22694927/93477427      93477427 Global, 1
#> 6            2015  FALSE            FALSE                        FALSE     22694927  https://www.iucnredlist.org/species/22694927/82593109      82593109 Global, 1
#> 7            2015  FALSE            FALSE                        FALSE     22694927  https://www.iucnredlist.org/species/22694927/60110592      60110592 Europe, 2
#> 8            2012  FALSE            FALSE                        FALSE     22694927  https://www.iucnredlist.org/species/22694927/38908739      38908739 Global, 1
#> 9            2009  FALSE            FALSE                        FALSE     22694927  https://www.iucnredlist.org/species/22694927/28178290      28178290 Global, 1
...
```

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


``` r
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](benchmarks.html) 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_()`:


``` r
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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"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\",\"assessment_id\":28184380,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]}],\"params\":{\"genus_name\":\"Fratercula\",\"species_name\":\"arctica\"}}"
```

To consume this JSON, you can use [`jsonlite`](https://jeroen.r-universe.dev/jsonlite):


``` r
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()`:


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

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


``` r
citation("rredlist")
#> To cite package 'rredlist' in publications use:
#> 
#>   Gearty W, Chamberlain S (2024). _rredlist: 'IUCN' Red List Client_. doi:10.32614/CRAN.package.rredlist <https://doi.org/10.32614/CRAN.package.rredlist>, R package
#>   version 0.7.1.9000, <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 = {2024},
#>     note = {R package version 0.7.1.9000},
#>     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 [version 3](https://apiv3.iucnredlist.org/) 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:


``` r
# 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](https://github.com/ropensci/rredlist/issues/52) for possible solutions if you need to use version 3 of the API.