Accessing IUCN redlist data via API by Gordon Blasco (NCEAS)
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:
You’ll also need this test API key: “9bb4facb6d23f48efbf424bb05c0c1ef1cf6f468393bc745d42179ac4aca5fee”
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
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
# 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")
##  "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 ##  "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!