README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# rebird: wrapper to the eBird API

<!-- badges: start -->
[![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/)
<!-- badges: end -->

`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 <https://ebird.org/api/keygen>.

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)
```

<!--
## Frequency of observations at hotspots or regions

Obtain historical frequencies of bird occurrences by hotspot or region

```{r ebirdfreq}
# ebirdfreq(loctype = 'hotspots', loc = 'L196159')
```
-->

## 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
 - [ ]     Taxonomy Versions
 - [ ]     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