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

important note: redlistr is a different package - not working with the IUCN Red List API

Citing the IUCN Red List API

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.

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

Install

CRAN

install.packages("rredlist")

Development version

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

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

To consume this JSON, you can use jsonlite

Or other tools, e.g., jq via the jqr R client

Meta

rofooter