19

rredlist

'IUCN' Red List Client

'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.

cran checks Build Status codecov.io rstudio mirror downloads cran version

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.

IUCN Red List docs

See http://apiv3.iucnredlist.org/about

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 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 vs. Low level package APIs

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_

No Spatial

This package does not include support for the spatial API, described at http://apiv3.iucnredlist.org/spatial.

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."

Citing IUCN API

use the function rl_citation()

rl_citation()
#> [1] "IUCN 2015. IUCN Red List of Threatened Species. Version 2018-1 <www.iucnredlist.org>"

Install

CRAN

install.packages("rredlist")

Development version

devtools::install_github("ropensci/rredlist")
library("rredlist")

High level API

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"
...

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

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,
...

Meta

  • Please report any issues or bugs.
  • License: MIT
  • Get citation information for rredlist in R doing citation(package = 'rredlist')
  • 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.

rofooter

News

rredlist 0.5.0

NEW FEATURES

  • gains new function rl_use_iucn to help with API key setup (#31) by @maelle
  • gains new functions rl_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)

MINOR IMPROVEMENTS

  • mention redlistr package in README to help users decide which package to use for which use cases (#30)
  • now using webmockr and vcr to do unit test caching (#33) (#34)

rredlist 0.4.0

NEW FEATURES

  • Gains new functions rl_growth_forms() and rl_growth_forms_(). added tests for them as well (#20) thanks @stevenpbachman

MINOR IMPROVEMENTS

  • Now using markdown documentation (#22)
  • Fixed many man files which for region parameter described requiring a taxonomic name - fixed to describe accurately. Also improved docs in general (#21)
  • Added the options for category parameter in rl_sp_category() function
  • Added in docs for rl_sp_country how to get acceptable country codes to pass to country parameter
  • Added to package level manual file ?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 time

rredlist 0.3.0

NEW FEATURES

  • New functions rl_occ_country and rl_occ_country_ for getting country occurrences by species name or ID (#13)
  • Replaced httr with crul. Please note this only affects use of curl options. See crul docs for how to use curl options (#14)

MINOR IMPROVEMENTS

  • User agent string like 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)
  • Taxon names are now given back in rl_threats - we didn't do anything in the package - the API now gives the names back and adds them in a column (#10)
  • Type checking all parameter inputs now both in terms of class and length - with helpful error messages on fail (#17)
  • Simplify package codebase by having single internal function for a suite of half a dozen or so functions that have similar pattern (#18)
  • Removed key parameter from rl_version() and rl_citation() as API key not required for those methods
  • More thorough test suite

rredlist 0.2.0

NEW FEATURES

  • New methods added to get historical assessments: rl_history() and rl_history_() (#8)

MINOR IMPROVEMENTS

  • Fixed description of what rl_common_names does. In addition, clarified descriptino of what other functions do as well, whenever it was unclear (#12)

BUG FIXES

  • Some API tokens were being blocked, fixed now (#7)
  • On some operating systems (at least some versions of Windows), queries that included taxonomic names weren't being processed correctly. It is fixed now (#11)

rredlist 0.1.0

NEW FEATURES

  • Released to CRAN.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("rredlist")

0.5.0 by Scott Chamberlain, 9 months ago

https://github.com/ropensci/rredlist

Report a bug at https://github.com/ropensci/rredlist/issues

Browse source code at https://github.com/cran/rredlist

Authors: Scott Chamberlain [aut, cre] , rOpenSci [fnd] (https://ropensci.org/) , Maëlle Salmon [ctb]

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports crul, jsonlite

Suggests roxygen2, testthat, webmockr, vcr

Imported by taxize.

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug