rredlist
is an R client for the IUCN Red List API (https://api.iucnredlist.org/). The IUCN Red List 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 are available at https://api.iucnredlist.org/api-docs. Note that use of the web API, and therefore this package, requires authentication.
What rredlist
is not:
-
redlistr
is a different package for contributors to the IUCN Red List - not working with the IUCN Red List API. -
rredlist
does not include support for the spatial API, described at https://apiv3.iucnredlist.org/spatial.
Installation
CRAN
install.packages("rredlist")
Development version
# From GitHub
remotes::install_github("ropensci/rredlist")
# From r-universe
install.packages("rredlist", repos = "https://ropensci.r-universe.dev/")
API Versioning
rredlist
versions ≤ 0.7.1 tracked version 3 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:
# 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/")
Authentication
IUCN requires you to get your own API key, an alphanumeric string
that you need to send in every request. There’s a helper function in the
package helping you getting it at https://api.iucnredlist.org/users/sign_up and storing
it. Once you store this key, the functions in rredlist
will
always default to using this key.
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.
Note that you can no longer generate a new API key for version 3 of the API.
High level interface
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:
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:
rl_species("Fratercula", "arctica")$assessments
#> year_published latest sis_taxon_id url assessment_id
#> 1 2021 TRUE 22694927 https://www.iucnredlist.org/species/22694927/166290968 166290968
#> 2 2018 TRUE 22694927 https://www.iucnredlist.org/species/22694927/132581443 132581443
#> 3 2017 FALSE 22694927 https://www.iucnredlist.org/species/22694927/117606911 117606911
#> 4 2016 FALSE 22694927 https://www.iucnredlist.org/species/22694927/93477427 93477427
#> 5 2017 FALSE 22694927 https://www.iucnredlist.org/species/22694927/110638141 110638141
#> 6 2015 FALSE 22694927 https://www.iucnredlist.org/species/22694927/82593109 82593109
#> 7 2015 FALSE 22694927 https://www.iucnredlist.org/species/22694927/60110592 60110592
#> 8 2012 FALSE 22694927 https://www.iucnredlist.org/species/22694927/38908739 38908739
#> 9 2009 FALSE 22694927 https://www.iucnredlist.org/species/22694927/28178290 28178290
...
Likely a bit faster is to parse to a list only, and not take the extra data.frame parsing time:
rl_species("Fratercula", "arctica", parse = FALSE)$assessments
#> [[1]]
#> [[1]]$year_published
#> [1] "2021"
#>
#> [[1]]$latest
#> [1] TRUE
#>
#> [[1]]$sis_taxon_id
#> [1] 22694927
#>
...
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_species_()
:
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\":{\"code\":\"eng\",\"description\":{\"en\":\"English\"}}},{\"main\":true,\"name\":\"Atlantic Puffin\",\"language\":{\"code\":\"eng\",\"description\":{\"en\":\"English\"}}}],\"synonyms\":[]},\"assessments\":[{\"year_published\":\"2021\",\"latest\":true,\"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,\"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,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/117606911\",\"assessment_id\":117606911,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2016\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/93477427\",\"assessment_id\":93477427,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2017\",\"latest\":false,\"sis_taxon_id\":22694927,\"url\":\"https://www.iucnredlist.org/species/22694927/110638141\",\"assessment_id\":110638141,\"scopes\":[{\"description\":{\"en\":\"Global\"},\"code\":\"1\"}]},{\"year_published\":\"2015\",\"latest\":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,\"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,\"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,\"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,\"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,\"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,\"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,\"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,\"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
:
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()
:
rl_citation()
#> [1] "IUCN 2024. IUCN Red List of Threatened Species. Version 2024-1 <www.iucnredlist.org>"
We’d also really appreciate it if you could cite your use of this package:
citation("rredlist")
#> To cite package 'rredlist' in publications use:
#>
#> Gearty W, Chamberlain S (????). _rredlist: 'IUCN' Red List Client_. R package version 0.7.1.9000,
#> https://github.com/ropensci/rredlist, <https://docs.ropensci.org/rredlist/>.
#>
#> A BibTeX entry for LaTeX users is
#>
#> @Manual{,
#> title = {rredlist: 'IUCN' Red List Client},
#> author = {William Gearty and Scott Chamberlain},
#> note = {R package version 0.7.1.9000,
#> https://github.com/ropensci/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.”