Giter Site home page Giter Site logo

rredlist's Introduction

rredlist

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

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. 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 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 2017-3 <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.

rredlist's People

Contributors

sckott avatar

Watchers

James Cloos avatar Moi avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.