Getting Started with iucnr

Introduction

The iucnr package provides high-performance, offline tools for querying and integrating data from the IUCN Red List of Threatened Species directly within R workflows.

By pairing with the local data provider package iucnrdata, iucnr enables researchers, ecologists, and conservationists to perform exact and fuzzy taxonomic matching, retrieve conservation statuses, and fetch preferred vernacular (common) names for both flora and fauna—without requiring API keys or an active internet connection.

Key Features

  • ⚡ Ultra-Fast Performance: Sub-2ms median query times via pre-indexed in-memory data tables and \(O(1)\) Fast-Path binary key lookup.
  • 🌐 100% Offline Execution: Query IUCN data anywhere in the field without internet dependencies, API quotas, or network latency.
  • 🔀 Fuzzy Taxonomic Matching: Automatically resolves typographical errors in genus and specific epithet names.
  • 🌿 Comprehensive Coverage: Fully supports both flora (plants, trees, fungi) and fauna (mammals, birds, amphibians, reptiles, fish, invertebrates).
  • 🧹 Silent Output by Default: verbose = FALSE by default ensures clean pipeline integration with dplyr and tidyverse.

Installation

To access the complete offline IUCN Red List database snapshot, install the iucnrdata data package from R-Universe:

install.packages(
  "iucnrdata",
  repos = c("https://paulesantos.r-universe.dev", "https://cloud.r-project.org")
)

Next, install iucnr:

# install.packages("pak")
pak::pak("PaulESantos/iucnr")

Core Workflows

library(iucnr)
#> ── Attaching iucnr ─────────────────────────────────────────────────── v0.0.3 ──
#> ✔ Compatible with IUCN Red List version 2026-1
#> ℹ Source: GBIF dataset (https://www.gbif.org/dataset/19491596-35ae-4a91-9a98-85cf505f1bd3)

1. Fauna Conservation Status & Common Names

Query iconic wild fauna species across various taxonomic classes:

fauna <- c(
  "Panthera onca",        # Jaguar
  "Tremarctos ornatus",   # Andean Bear
  "Vultur gryphus",       # Andean Condor
  "Spheniscus humboldti", # Humboldt Penguin
  "Ambystoma mexicanum"  # Axolotl
)

# Retrieve conservation status as a tibble
get_iucn_status(splist = fauna, format = "tbl")
#> # A tibble: 5 × 4
#>      id submitted_name       matched_species      redlist_category     
#>   <int> <chr>                <chr>                <chr>                
#> 1     1 Panthera onca        Panthera onca        Near Threatened      
#> 2     2 Tremarctos ornatus   Tremarctos ornatus   Vulnerable           
#> 3     3 Vultur gryphus       Vultur gryphus       Vulnerable           
#> 4     4 Spheniscus humboldti Spheniscus humboldti Vulnerable           
#> 5     5 Ambystoma mexicanum  Ambystoma mexicanum  Critically Endangered

Retrieve common names:

get_iucn_common_name(splist = fauna, format = "tbl")
#> # A tibble: 5 × 4
#>      id submitted_name       matched_species      common_name     
#>   <int> <chr>                <chr>                <chr>           
#> 1     1 Panthera onca        Panthera onca        Jaguar          
#> 2     2 Tremarctos ornatus   Tremarctos ornatus   Andean Bear     
#> 3     3 Vultur gryphus       Vultur gryphus       Andean Condor   
#> 4     4 Spheniscus humboldti Spheniscus humboldti Humboldt Penguin
#> 5     5 Ambystoma mexicanum  Ambystoma mexicanum  Axolotl

2. Flora Conservation Status

Retrieve conservation categories for threatened Andean and tropical tree/plant species:

flora <- c(
  "Swietenia macrophylla",  # Big-leaf Mahogany
  "Puya raimondii",        # Queen of the Andes
  "Cedrela odorata",       # Spanish Cedar
  "Polylepis racemosa"     # Quenoa Tree
)

get_iucn_status(splist = flora, format = "tbl")
#> # A tibble: 4 × 4
#>      id submitted_name        matched_species       redlist_category
#>   <int> <chr>                 <chr>                 <chr>           
#> 1     1 Swietenia macrophylla Swietenia macrophylla Endangered      
#> 2     2 Puya raimondii        Puya raimondii        Endangered      
#> 3     3 Cedrela odorata       Cedrela odorata       Vulnerable      
#> 4     4 Polylepis racemosa    Polylepis racemosa    Data Deficient

3. Automatic Fuzzy Matching for Typos

iucnr automatically detects and corrects typographical errors in genus or species names:

splist_typos <- c(
  "Pantera onca",          # Typo in genus: Panthera -> Pantera
  "Puya raimondi",         # Typo in epithet: raimondii -> raimondi
  "Escallonia ressinosa"   # Typo in epithet: resinosa -> ressinosa
)

get_iucn_status(splist = splist_typos, format = "tbl")
#> # A tibble: 3 × 4
#>      id submitted_name       matched_species     redlist_category
#>   <int> <chr>                <chr>               <chr>           
#> 1     1 Pantera onca         Panthera onca       Near Threatened 
#> 2     2 Puya raimondi        Puya raimondii      Endangered      
#> 3     3 Escallonia ressinosa Escallonia resinosa Near Threatened

4. Direct Filtering by Threat Category

Extract all species registered under a specific IUCN Red List category (e.g., CR for Critically Endangered, EN for Endangered, VU for Vulnerable):

cr_species <- get_iucn_by_category("CR")
head(cr_species)
#> # A tibble: 6 × 10
#>   taxonID   scientificName               kingdom phylum class order family genus
#>   <chr>     <chr>                        <chr>   <chr>  <chr> <chr> <chr>  <chr>
#> 1 10041     Heosemys annandalii (Boulen… ANIMAL… CHORD… REPT… TEST… GEOEM… Heos…
#> 2 100682075 Wollastonaria klausgrohi De… ANIMAL… MOLLU… GAST… STYL… GEOMI… Woll…
#> 3 10138     Hipposideros hypophyllus Ko… ANIMAL… CHORD… MAMM… CHIR… HIPPO… Hipp…
#> 4 10141     Hipposideros lamottei Bross… ANIMAL… CHORD… MAMM… CHIR… HIPPO… Hipp…
#> 5 101526168 Solanum fernandezianum Phil. PLANTAE TRACH… MAGN… SOLA… SOLAN… Sola…
#> 6 101529185 Solanum ruvu Vorontsova      PLANTAE TRACH… MAGN… SOLA… SOLAN… Sola…
#> # ℹ 2 more variables: redlist_category <chr>, taxonomicStatus <chr>

5. Higher Taxonomy & Dataset Version Metadata

Filter by higher taxonomic ranks (Kingdom, Phylum, Class, Order, Family):

pinaceae_species <- get_iucn_by_taxonomy(family = "Pinaceae")
head(pinaceae_species)
#> # A tibble: 6 × 10
#>   taxonID   scientificName               kingdom phylum class order family genus
#>   <chr>     <chr>                        <chr>   <chr>  <chr> <chr> <chr>  <chr>
#> 1 124561040 Pinus vallartensis Pérez de… PLANTAE TRACH… PINO… PINA… PINAC… Pinus
#> 2 18153818  Pinus elliottii var. densa … PLANTAE TRACH… PINO… PINA… PINAC… Pinus
#> 3 18153856  Pinus mugo subsp. rotundata… PLANTAE TRACH… PINO… PINA… PINAC… Pinus
#> 4 191552    Abies chensiensis subsp. sa… PLANTAE TRACH… PINO… PINA… PINAC… Abies
#> 5 191553    Abies delavayi var. delavayi PLANTAE TRACH… PINO… PINA… PINAC… Abies
#> 6 191554    Abies delavayi var. motuoen… PLANTAE TRACH… PINO… PINA… PINAC… Abies
#> # ℹ 2 more variables: redlist_category <chr>, taxonomicStatus <chr>

Check the packaged IUCN snapshot version details:

iucn_data_version()
#> [1] "Version 2026-1"

Integration with Tidyverse Workflows

iucnr functions return vector output when format = "vect", enabling seamless integration with dplyr::mutate():

library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

survey_data <- tibble::tibble(
  species = c("Panthera onca", "Swietenia macrophylla", "Vultur gryphus")
)

survey_data %>%
  mutate(
    status = get_iucn_status(species, format = "vect"),
    common_name = get_iucn_common_name(species, format = "vect")
  )
#> # A tibble: 3 × 3
#>   species               status          common_name      
#>   <chr>                 <chr>           <chr>            
#> 1 Panthera onca         Near Threatened Jaguar           
#> 2 Swietenia macrophylla Endangered      Big Leaf Mahogany
#> 3 Vultur gryphus        Vulnerable      Andean Condor

Performance Benchmark

Below is a median query execution time comparison between iucnr (offline) and online API R packages (iucnredlist and redlist):

Package / Mode Execution Time (Median) Acceleration vs Online API
redlist (Online API) 996.7 ms 1.0x (Baseline)
iucnredlist (Online API) 418.6 ms 2.4x
iucnr (Offline Fast-Path) 1.45 ms >680x Faster

Citation

When using iucnr in scientific publications, please cite both the package and the underlying IUCN Red List dataset:

citation("iucnr")
#> To cite iucnr in publications use:
#> 
#>   Santos-Andrade Paul E. (2026). iucnr: IUCN Red List Data.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     author = {Paul E. Santos Andrade},
#>     title = {iucnr: IUCN Red List Data},
#>     year = {2026},
#>     url = {https://paulesantos.github.io/iucnr/},
#>   }
#> 
#> To cite the IUCN dataset, please use: IUCN. 2026. The IUCN Red List of
#> Threatened Species. Version 2026-1. Data retrieved from GBIF
#> (https://www.gbif.org/dataset/19491596-35ae-4a91-9a98-85cf505f1bd3).

IUCN. 2026. The IUCN Red List of Threatened Species. Version 2026-1. Data retrieved via GBIF (https://www.gbif.org/dataset/19491596-35ae-4a91-9a98-85cf505f1bd3).