rredlist is an R client for the IUCN Red List (https://apiv3.iucnredlist.org/api/v3/docs). The IUCN Red List is a global list of threatened and endangered species.
IUCN Red List docs: http://apiv3.iucnredlist.org/api/v3/docs The web API needs authentication.
What rredlist is not: [redlistr][] is a different package - not working with the IUCN Red List API; Furthermore, rredlist does not include support for the spatial API, described at https://apiv3.iucnredlist.org/spatial.
Installation
CRAN
install.packages("rredlist")Development version
remotes::install_github("ropensci/rredlist")
# OR
install.packages("rredlist", repos="https://dev.ropensci.org")Authentication
IUCN requires you to get your own API key, an alphanumeric string that you need to send in every request. There’s an helper function in the package helping you getting it at https://apiv3.iucnredlist.org/api/v3/token and storing it.
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.
High level interface
High level functions do the HTTP request and parse data to a data.frame for ease of downstream use. The high level functions have no underscore on the end of the function name, e.g., rl_search()
rl_search('Fratercula arctica')
#> $name
#> [1] "Fratercula arctica"
#>
#> $result
#> taxonid scientific_name kingdom phylum class order family
#> 1 22694927 Fratercula arctica ANIMALIA CHORDATA AVES CHARADRIIFORMES ALCIDAE
#> genus main_common_name authority published_year assessment_date
#> 1 Fratercula Atlantic Puffin (Linnaeus, 1758) 2018 2018-08-07
#> category criteria population_trend marine_system freshwater_system
#> 1 VU A4abcde Decreasing TRUE FALSE
#> terrestrial_system assessor reviewer aoo_km2 eoo_km2
#> 1 TRUE BirdLife International Westrip, J.R.S. NA 20800000
#> elevation_upper elevation_lower depth_upper depth_lower errata_flag
#> 1 NA NA NA NA NA
#> errata_reason amended_flag amended_reason
#> 1 NA NA NANote: there can sometimes be a discrepancy between what you get on the IUCN website and what you get with this package; we don’t know why, the IUCN API is not an open book.
Likely a bit faster is to parse to a list only, and not take the extra data.frame parsing time
rl_search('Fratercula arctica', parse = FALSE)
#> $name
#> [1] "Fratercula arctica"
#>
#> $result
#> $result[[1]]
#> $result[[1]]$taxonid
#> [1] 22694927
#>
#> $result[[1]]$scientific_name
#> [1] "Fratercula arctica"
...For even more speed, use the low level package interface.
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_search_()
rl_search_('Fratercula arctica')
#> [1] "{\"name\":\"Fratercula arctica\",\"result\":[{\"taxonid\":22694927,\"scientific_name\":\"Fratercula arctica\",\"kingdom\":\"ANIMALIA\",\"phylum\":\"CHORDATA\",\"class\":\"AVES\",\"order\":\"CHARADRIIFORMES\",\"family\":\"ALCIDAE\",\"genus\":\"Fratercula\",\"main_common_name\":\"Atlantic Puffin\",\"authority\":\"(Linnaeus, 1758)\",\"published_year\":2018,\"assessment_date\":\"2018-08-07\",\"category\":\"VU\",\"criteria\":\"A4abcde\",\"population_trend\":\"Decreasing\",\"marine_system\":true,\"freshwater_system\":false,\"terrestrial_system\":true,\"assessor\":\"BirdLife International\",\"reviewer\":\"Westrip, J.R.S.\",\"aoo_km2\":null,\"eoo_km2\":\"20800000\",\"elevation_upper\":null,\"elevation_lower\":null,\"depth_upper\":null,\"depth_lower\":null,\"errata_flag\":null,\"errata_reason\":null,\"amended_flag\":null,\"amended_reason\":null}]}"To consume this JSON, you can use jsonlite
library("jsonlite")
jsonlite::fromJSON(rl_search_('Fratercula arctica'))
#> $name
#> [1] "Fratercula arctica"
#>
#> $result
#> taxonid scientific_name kingdom phylum class order family
#> 1 22694927 Fratercula arctica ANIMALIA CHORDATA AVES CHARADRIIFORMES ALCIDAE
#> genus main_common_name authority published_year assessment_date
#> 1 Fratercula Atlantic Puffin (Linnaeus, 1758) 2018 2018-08-07
#> category criteria population_trend marine_system freshwater_system
#> 1 VU A4abcde Decreasing TRUE FALSE
#> terrestrial_system assessor reviewer aoo_km2 eoo_km2
#> 1 TRUE BirdLife International Westrip, J.R.S. NA 20800000
#> elevation_upper elevation_lower depth_upper depth_lower errata_flag
#> 1 NA NA NA NA NA
#> errata_reason amended_flag amended_reason
#> 1 NA NA NAOr other tools, e.g., jq via the jqr R client
# remotes::install_github("ropensci/jqr")
library("jqr")
rl_search_('Fratercula arctica') %>% dot()
#> $data
#> [1] "{\"name\":\"Fratercula arctica\",\"result\":[{\"taxonid\":22694927,\"scientific_name\":\"Fratercula arctica\",\"kingdom\":\"ANIMALIA\",\"phylum\":\"CHORDATA\",\"class\":\"AVES\",\"order\":\"CHARADRIIFORMES\",\"family\":\"ALCIDAE\",\"genus\":\"Fratercula\",\"main_common_name\":\"Atlantic Puffin\",\"authority\":\"(Linnaeus, 1758)\",\"published_year\":2018,\"assessment_date\":\"2018-08-07\",\"category\":\"VU\",\"criteria\":\"A4abcde\",\"population_trend\":\"Decreasing\",\"marine_system\":true,\"freshwater_system\":false,\"terrestrial_system\":true,\"assessor\":\"BirdLife International\",\"reviewer\":\"Westrip, J.R.S.\",\"aoo_km2\":null,\"eoo_km2\":\"20800000\",\"elevation_upper\":null,\"elevation_lower\":null,\"depth_upper\":null,\"depth_lower\":null,\"errata_flag\":null,\"errata_reason\":null,\"amended_flag\":null,\"amended_reason\":null}]}"
#>
#> $args
#> $args[[1]]
#> [1] "."
#> attr(,"type")
#> [1] "dot"
#>
#>
#> attr(,"class")
#> [1] "jqr"Usage best practice
Citing the IUCN Red List API
Use the function rl_citation():
rl_citation()
#> [1] "IUCN 2015. IUCN Red List of Threatened Species. Version 2020-2 <www.iucnredlist.org>"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.”