IUCN requires you to get your own API key, an alphanumeric string that you
need to send in every request. Get it at http://apiv3.iucnredlist.org/api/v3/token.
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
suggest 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.
use the function rl_citation()
rl_citation()
#> [1] "IUCN 2015. IUCN Red List of Threatened Species. Version 2015-4 <www.iucnredlist.org>"
CRAN
install.packages("rredlist")
Development version
devtools::install_github("ropenscilabs/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) 2015
#> category criteria marine_system freshwater_system terrestrial_system
#> 1 VU A4abcde TRUE FALSE TRUE
#> assessor reviewer
#> 1 BirdLife International Symes, A.
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\":2015,\"category\":\"VU\",\"criteria\":\"A4abcde\",\"marine_system\":true,\"freshwater_system\":false,\"terrestrial_system\":true,\"assessor\":\"BirdLife International\",\"reviewer\":\"Symes, A.\"}]}"
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) 2015
#> category criteria marine_system freshwater_system terrestrial_system
#> 1 VU A4abcde TRUE FALSE TRUE
#> assessor reviewer
#> 1 BirdLife International Symes, A.
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": 2015,
#> "category": "VU",
#> "criteria": "A4abcde",
#> "marine_system": true,
#> "freshwater_system": false,
#> "terrestrial_system": true,
...
- Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.