'IUCN' Red List (< http://apiv3.iucnredlist.org/api/v3/docs>) client. The 'IUCN' Red List is a global list of threatened and endangered species. Functions cover all of the Red List 'API' routes. An 'API' key is required.
rredlist
is an R client for the IUCN Red List (http://apiv3.iucnredlist.org/api/v3/docs).
The IUCN Red List is a global list of threatened and endangered species.
See http://apiv3.iucnredlist.org/about
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 http://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 API
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
Low level API
The parsing to data.frame in the high level API does take extra time. The low
level API only does the HTTP request, and gives 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_
This package does not include support for the spatial API, described at http://apiv3.iucnredlist.org/spatial.
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."
use the function rl_citation()
rl_citation()#> [1] "IUCN 2015. IUCN Red List of Threatened Species. Version 2018-1 <www.iucnredlist.org>"
CRAN
install.packages("rredlist")
Development version
devtools::install_github("ropensci/rredlist")
library("rredlist")
High level functions do the HTTP request and parse to data to a data.frame for ease of downstream use.
rl_search('Fratercula arctica')#> $name#> [1] "Fratercula arctica"#> #> $result#> taxonid scientific_name kingdom phylum class order#> 1 22694927 Fratercula arctica ANIMALIA CHORDATA AVES CHARADRIIFORMES#> family genus main_common_name authority published_year#> 1 ALCIDAE Fratercula Atlantic Puffin (Linnaeus, 1758) 2017#> category criteria marine_system freshwater_system terrestrial_system#> 1 VU A4abcde TRUE FALSE TRUE#> assessor reviewer aoo_km2 eoo_km2 elevation_upper#> 1 BirdLife International Symes, A. NA 20800000 NA#> elevation_lower depth_upper depth_lower errata_flag errata_reason#> 1 NA NA NA NA NA#> amended_flag amended_reason#> 1 NA NA
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"...
The parsing to data.frame in the high level API does take extra time. The low level API only does the HTTP request, and gives back JSON without doing any more parsing
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\":2017,\"category\":\"VU\",\"criteria\":\"A4abcde\",\"marine_system\":true,\"freshwater_system\":false,\"terrestrial_system\":true,\"assessor\":\"BirdLife International\",\"reviewer\":\"Symes, A.\",\"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#> 1 22694927 Fratercula arctica ANIMALIA CHORDATA AVES CHARADRIIFORMES#> family genus main_common_name authority published_year#> 1 ALCIDAE Fratercula Atlantic Puffin (Linnaeus, 1758) 2017#> category criteria marine_system freshwater_system terrestrial_system#> 1 VU A4abcde TRUE FALSE TRUE#> assessor reviewer aoo_km2 eoo_km2 elevation_upper#> 1 BirdLife International Symes, A. NA 20800000 NA#> elevation_lower depth_upper depth_lower errata_flag errata_reason#> 1 NA NA NA NA NA#> amended_flag amended_reason#> 1 NA NA
Or other tools, e.g., jq
via the jqr
R client
# devtools::install_github("ropensci/jqr")library("jqr")rl_search_('Fratercula arctica') %>% dot()#> {#> "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": 2017,#> "category": "VU",#> "criteria": "A4abcde",#> "marine_system": true,#> "freshwater_system": false,#> "terrestrial_system": true,...
rredlist
in R doing citation(package = 'rredlist')
rl_use_iucn
to help with API key setup (#31) by @maellerl_comp_groups
and rl_comp_groups_
to interface with the comprehensive groups API route (#26)rl_sp
gains two new parameters: all
(logical) to toggle getting all results or not, if selected we do paging internally; quiet
parameter (logical) suppresses progress (#29)redlistr
package in README to help users decide which package to use for which use cases (#30)webmockr
and vcr
to do unit test caching (#33) (#34)rl_growth_forms()
and rl_growth_forms_()
. added
tests for them as well (#20) thanks @stevenpbachmanregion
parameter described
requiring a taxonomic name - fixed to describe accurately. Also
improved docs in general (#21)category
parameter in rl_sp_category()
functionrl_sp_country
how to get acceptable country codes to
pass to country
parameter?rredlist-package
a note from the
IUCN Redlist API documentation about that they suggest using taxonomic
names instead of IDs because IDs can change through timerl_occ_country
and rl_occ_country_
for
getting country occurrences by species name or ID (#13)httr
with crul
. Please note this only affects use
of curl options. See crul
docs for how to use curl options (#14)r-curl/2.3 crul/0.2.0 rOpenSci(rredlist/0.3.0)
sent in all requests now to help IUCN API maintainers know
how often requests come from R and this package (#19)rl_threats
- we didn't do
anything in the package - the API now gives the names back and
adds them in a column (#10)key
parameter from rl_version()
and rl_citation()
as
API key not required for those methodsrl_history()
and rl_history_()
(#8)rl_common_names
does. In addition,
clarified descriptino of what other functions do as well, whenever
it was unclear (#12)