Accessing IUCN redlist data via API by Gordon Blasco (NCEAS)

About Gordon

Gordon Blasco is a data analyst at the National Center for Ecological Analysis and Synthesis and a total R enthusiast. He works on trends in food systems and the mapping of human impacts on the marine environment.


IUCN Redlist API demo

In this session, I show how to use the IUCN’s redlists API to get the current conservation status for a number of species, using some help from the purrr package to keep it tidy.

Set-up to follow along:

To follow along, you’ll need to install the rredlist package in R: install.packages("rredlist")

You’ll also need this test API key: “9bb4facb6d23f48efbf424bb05c0c1ef1cf6f468393bc745d42179ac4aca5fee”

Packages required: rredlist and tidyverse

suppressMessages(library(rredlist))
suppressMessages(library(tidyverse))

Safety first!

API keys are sensitive and should not be saved in your R scripts if you are going to push them to github. Treat them like a password. To keep them safe, save them to your computer as “environmental variables” that can only be seen from your device. This is easy to do in R using the base r Sys.setenv() and Sys.getenv() functions.

You can use Sys.setenv() to save a string as an environmental variable, meaning it will not be populated into your R environment, instead it will live in the environment of your computer’s hard drive. Once you set the system variable be sure to delete the line where you set the variable. You now can use the Sys.getenv() function to call that environmental variable. That variable will exist in your computer until you delete it using Sys.unsetenv().

# set your api key as an environmental variable so you do not upload
Sys.setenv(IUCN_KEY = "9bb4facb6d23f48efbf424bb05c0c1ef1cf6f468393bc745d42179ac4aca5fee")

# now call the variable that you set
Sys.getenv("IUCN_KEY")
## [1] "9bb4facb6d23f48efbf424bb05c0c1ef1cf6f468393bc745d42179ac4aca5fee"
# if this returns the token key then you can delete the Sys.setenv line. This does not need to be in your code anymore,

# and you can save that as a R variable 
apikey <- Sys.getenv("IUCN_KEY")

Now that we have a way to access the api and keep our precious api key is safe, lets look at what the api returns for the species Gorilla gorilla. To ping the API we will use the rredlist::rl_search to get the information for a given species.

test <- rl_search("Gorilla gorilla", key = apikey)

test
## $name
## [1] "Gorilla gorilla"
## 
## $result
##   taxonid scientific_name  kingdom   phylum    class    order    family   genus
## 1    9404 Gorilla gorilla ANIMALIA CHORDATA MAMMALIA PRIMATES HOMINIDAE Gorilla
##   main_common_name      authority published_year assessment_date category
## 1  Western Gorilla (Savage, 1847)           2018      2016-04-01       CR
##   criteria population_trend marine_system freshwater_system terrestrial_system
## 1   A4bcde       Decreasing         FALSE             FALSE               TRUE
##                                      assessor                          reviewer
## 1 Maisels, F., Bergl, R.A. & Williamson, E.A. Mittermeier, R.A. & Rylands, A.B.
##   aoo_km2 eoo_km2 elevation_upper elevation_lower depth_upper depth_lower
## 1      NA      NA            1900               0          NA          NA
##   errata_flag errata_reason amended_flag
## 1          NA            NA         TRUE
##                                                                                                                                     amended_reason
## 1 This amended version of the 2016 assessment was created to update population and reduction estimates based on Strindberg <em>et al</em>. (2018).

So… this is a bit of a mess, but you can see the category column returning a “CR” for critically endangered (total bummer). Awful reminder of the biodiversity crisis aside, our code is working and we are able to pull the information we want from the IUCN. However, we can clean this workflow up a bit using the purrr package. Let’s use purrr::map() to iterate over a list of species, and purrr::pluck() to extract just the category and return it as a column.

# make a data frame of the species you want to iterate over
df <- tribble(
  ~species_names, 
  "Pan paniscus",
  "Gorilla gorilla",
  "Chiroxiphia linearis",
  "Lemur catta"
) %>% # now apply the rl_search function to each species using purrr::map()
  mutate(iucn_pull = map(species_names, rl_search, key = apikey)) 

# if you look at the df object the iucn_pull column is a list with a lot of information that we are not interested in. So we can use purr::pluck to get the elements we want!

# we will need to look at the list format to see what elements of the api we are interested in are named. In this case we want to go into the "result" list and pull out the value from "category." 

api_clean <- df %>% 
  mutate(category = map_chr(iucn_pull, pluck, "result", "category")) %>% 
  select(species_names, category)

api_clean
## # A tibble: 4 x 2
##   species_names        category
##   <chr>                <chr>   
## 1 Pan paniscus         EN      
## 2 Gorilla gorilla      CR      
## 3 Chiroxiphia linearis LC      
## 4 Lemur catta          EN

There we go much cleaner. Thanks TidyTuesday crew!

Related