Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ropensci/rebird

Wrapper to the eBird API
https://github.com/ropensci/rebird

birds ebird ebird-api ebird-webservices r r-package rstats spocc

Last synced: 4 days ago
JSON representation

Wrapper to the eBird API

Awesome Lists containing this project

README 

        
---

output: github_document

---



```{r, echo = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "README-"

)

```



# rebird: wrapper to the eBird API



[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/)

[![R-CMD-check](https://github.com/ropensci/rebird/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/rebird/actions/workflows/R-CMD-check.yaml)

[![Codecov test coverage](https://codecov.io/gh/ropensci/rebird/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/rebird?branch=master)

[![rstudio mirror downloads](https://cranlogs.r-pkg.org/badges/rebird)](https://github.com/r-hub/cranlogs.app)

[![cran version](https://www.r-pkg.org/badges/version/rebird)](https://cran.r-project.org/package=rebird/)



`rebird` is a package to interface with the eBird webservices.



eBird is a real-time, online bird checklist program. For more information, visit their website: https://ebird.org/home



The API for the eBird webservices can be accessed here: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest



## Install



You can install the stable version from CRAN



```{r eval=FALSE}

install.packages("rebird")

```



Or the development version from Github



```{r eval=FALSE}

install.packages("devtools")

devtools::install_github("ropensci/rebird")

```



# Direct use of `rebird`



Load the package:



```{r}

library("rebird")

```



The [eBird API server](https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest)

requires users to provide an API key, which is linked to your eBird user account. 

You can pass it to the 'key' argument in `rebird` functions, but we highly recommend

storing it as an environment variable called EBIRD_KEY in your .Renviron file.

If you don't have a key, you can obtain one from .



You can keep your .Renviron file in your global R home directory (`R.home()`), your user's home

directory (`Sys.getenv("HOME")`), or your current working directory (`getwd()`). Remember

that .Renviron is loaded once when you start R, so if you add your API key to the file you will

have to restart your R session. See `?Startup` for more information on R's startup files.



Furthermore, functions now use species codes, rather than scientific names, for species-specific requests.

We've made the switch easy by providing the `species_code` function, which converts a scientific name to

its species code:



```{r speciescode}

species_code('sula variegata')

```



The `species_code` function can be called within other `rebird` functions, or the species code 

can be specified directly.



## eBird Taxonomy



The eBird taxonomy is internally stored in `rebird` and can be called using



```{r tax}

rebird::tax

```



While the internal taxonomy is kept up to date with each package release, it could

be outdated if a new taxonomy is made available before the package is updated.

You can obtain the latest eBird taxonomy by



```{r taxonomy, eval=FALSE}

new_tax <- ebirdtaxonomy()

```



## Sightings at location determined by latitude/longitude



Search for bird occurrences by latitude and longitude point



```{r ebirdgeo1}

ebirdgeo(species = species_code('spinus tristis'), lat = 42, lng = -76)

```



## Recent observations at a region



Search for bird occurrences by region and species name



```{r ebirdregion1}

ebirdregion(loc = 'US', species = 'btbwar')

```



## Recent observations at hotspots



Search for bird occurrences by a given hotspot



```{r ebirdhotspot}

ebirdregion(loc = 'L99381')

```



## Nearest observations of a species



Search for a species' occurrences near a given latitude and longitude



```{r nearestobs}

nearestobs(species_code('branta canadensis'), 42, -76)

```



## Recent notable sightings



Search for notable sightings at a given latitude and longitude



```{r ebirdnotable1}

ebirdnotable(lat = 42, lng = -70)

```



or a region



```{r ebirdnotable2}

ebirdnotable(locID = 'US-NY-109')

```



## Historic Observations



Obtain a list of species reported on a specific date in a given region 



```{r ebirdhistorical1}

ebirdhistorical(loc = 'US-VA-003', date = '2019-02-14',max = 10)



```



or a hotspot



```{r ebirdhistorical2}

ebirdhistorical(loc = 'L196159', date = '2019-02-14', fieldSet = 'full')



```



## Information on a given region or hotspot



Obtain detailed information on any valid eBird region



```{r ebirdregioninfo1}

ebirdregioninfo("CA-BC-GV")

```



or hotspot



```{r ebirdregioninfo2}

ebirdregioninfo("L196159")

```



Obtain a list of eBird species codes for all species recorded in a region



```{r ebirdregionspecies1}

ebirdregionspecies("GB-ENG-LND")

```



or a hotspot



```{r ebirdregionspecies2}

ebirdregionspecies("L5803024")

```



Obtain a list of all subregions within an eBird region



```{r ebirdsubregionlist}

ebirdsubregionlist("subnational1","US")

```



## Checklist Feed



Obtain a list of checklists submitted on a given date at a region or hotspot



```{r ebirdchecklistfeed}

ebirdchecklistfeed(loc = "L207391", date = "2020-03-24", max = 5)

```



## View Checklist



Obtain all information on a specific checklist



```{r ebirdchecklist}

ebirdchecklist("S139153079")

```



## Hotspots in a region or nearby coordinates



Obtain a list of hotspots within a region



```{r ebirdhotspotlist1}

ebirdhotspotlist("CA-NS-HL")

```



or within a radius of up to 50 kilometers, from a given set of coordinates.



```{r ebirdhotspotlist2}

ebirdhotspotlist(lat = 30, lng = -90, dist = 10)

```



## `rebird` and other packages



### How to use `rebird`



This package is part of a richer suite called [spocc - Species Occurrence Data](https://github.com/ropensci/spocc), along with several other packages, that provide access to occurrence records from multiple databases. We recommend using `spocc` as the primary R interface to `rebird` unless your needs are limited to this single source.



### `auk` vs. `rebird`



Those interested in eBird data may also want to consider [`auk`](https://github.com/CornellLabofOrnithology/auk), an R package that helps extracting and processing the whole eBird dataset. The functions in `rebird` are faster but mostly limited to accessing recent (i.e. within the last 30 days) observations, although `ebirdfreq()` does provide historical frequency of observation data. In contrast, `auk` gives access to the full set of ~ 500 million eBird observations. For most ecological applications, users will require `auk`; however, for some use cases, e.g. building tools for birders, `rebird` provides a quicker and easier way to access data. `rebird` and `auk` are both part of the rOpenSci project.



## API requests covered by `rebird`



The 2.0 APIs have considerably been expanded from the previous version, and `rebird` only covers some of them.  The webservices covered are listed below; if you'd like to contribute wrappers to APIs not yet covered by this package, feel free to submit a pull request!



### data/obs



- [x] Recent observations in a region: `ebirdregion()`

- [x] Recent notable observations in a region: `ebirdnotable()`

- [x] Recent observations of a species in a region: `ebirdregion()`

- [x] Recent nearby observations: `ebirdgeo()` 

- [x] Recent nearby observations of a species: `ebirdgeo()`

- [x] Nearest observations of a species: `nearestobs()`

- [x] Recent nearby notable observations: `ebirdnotable()`

- [ ] Recent checklists feed

- [x] Historic observations on a date: `ebirdhistorical()`



### product

- [ ] Top 100

- [x] Checklist feed on a date: `ebirdchecklistfeed()`

- [ ] Regional statistics on a date

- [x] Species list for a region: `ebirdregionspecies()`

- [x] View Checklist: `ebirdchecklist()`



### ref/geo

 - [ ]    Adjacent Regions



### ref/hotspot

 - [x] Hotspots in a region: `ebirdhotspotlist()`

 - [x] Nearby hotspots: `ebirdhotspotlist()`

 - [x] Hotspot Info: `ebirdregioninfo()`



### ref/taxonomy

 - [x]     eBird Taxonomy: `ebirdtaxonomy()`

 - [ ]     Taxonomic Forms

 - [x]     Taxonomy Versions: `ebirdtaxonomyversion()`

 - [ ]     Taxonomic Groups



### ref/region

 - [x]     Region Info: `ebirdregioninfo()`

 - [x]     Sub Region List: `ebirdsubregionlist()`



## Meta



* Please [report any issues or bugs](https://github.com/ropensci/rebird/issues).

* License: MIT

* Get citation information for `rebird` in R doing `citation(package = 'rebird')`

* Please note that the 'rebird' project is released with a [Contributor Code of Conduct][coc]. By contributing to this project, you agree to abide by its terms.



[![ropensci_footer](https://ropensci.org/public_images/github_footer.png)](https://ropensci.org/)



[coc]: https://github.com/ropensci/rebird/blob/master/CODE_OF_CONDUCT.md