---
title: Introduction to the rebird package
author: Sebastian Pardo, Rafael Maia
date: "2021-01-25"
output: rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{Introduction to the rebird package}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

A programmatic interface to the eBird database. Find out more about eBird at [their website](https://ebird.org/home/).

## Installation

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

Then load the package into the R session

```{r}
library("rebird")
```

## Usage

The [eBird API server](https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest) 
has been updated and thus there are a couple major changes in the way `rebird` works.
API requests to eBird now require 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)
```

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