rebird

Wrapper to the eBird API

https://github.com/ropensci/rebird

Keywords

Keywords from Contributors

Repository

Wrapper to the eBird API

README.Rmd

---
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/graph/badge.svg)](https://app.codecov.io/gh/ropensci/rebird)
[![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

Owner

CodeMeta (codemeta.json)

{
  "@context": [
    "https://doi.org/doi:10.5063/schema/codemeta-2.0",
    "http://schema.org"
  ],
  "@type": "SoftwareSourceCode",
  "identifier": "rebird",
  "description": "A programmatic client for the eBird database \n    (<https://ebird.org/home>), including functions for searching for bird \n    observations by geographic location (latitude, longitude), eBird \n    hotspots, location identifiers, by notable sightings, by region, and by \n    taxonomic name.",
  "name": "rebird: R Client for the eBird Database of Bird Observations",
  "codeRepository": "https://github.com/ropensci/rebird",
  "issueTracker": "https://github.com/ropensci/rebird/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "1.2.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.0.3 (2020-10-10)",
  "provider": {
    "@id": "https://cran.r-project.org",
    "@type": "Organization",
    "name": "Central R Archive Network (CRAN)",
    "url": "https://cran.r-project.org"
  },
  "author": [
    {
      "@type": "Person",
      "givenName": "Rafael",
      "familyName": "Maia",
      "email": "rm72@zips.uakron.edu"
    },
    {
      "@type": "Person",
      "givenName": "Scott",
      "familyName": "Chamberlain",
      "email": "myrmecocystus@gmail.com",
      "@id": "https://orcid.org/0000-0003-1444-9135"
    },
    {
      "@type": "Person",
      "givenName": "Andy",
      "familyName": "Teucher",
      "email": "andy.teucher@gmail.com"
    },
    {
      "@type": "Person",
      "givenName": "Sebastian",
      "familyName": "Pardo",
      "email": "sebpardo@gmail.com",
      "@id": "https://orcid.org/0000-0002-4147-5796"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Sebastian",
      "familyName": "Pardo",
      "email": "sebpardo@gmail.com",
      "@id": "https://orcid.org/0000-0002-4147-5796"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=covr"
    }
  ],
  "softwareRequirements": [
    {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 2.10"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "methods",
      "name": "methods"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "utils",
      "name": "utils"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "stats",
      "name": "stats"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "httr",
      "name": "httr",
      "version": ">= 1.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=httr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "jsonlite",
      "name": "jsonlite",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=jsonlite"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "dplyr",
      "name": "dplyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=dplyr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "assertthat",
      "name": "assertthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=assertthat"
    }
  ],
  "applicationCategory": "DataAccess",
  "isPartOf": "https://ropensci.org",
  "keywords": [
    "birds",
    "birding",
    "ebird",
    "database",
    "data",
    "biology",
    "observations",
    "sightings",
    "ornithology",
    "rstats",
    "ebird-api",
    "r",
    "ebird-webservices",
    "spocc",
    "r-package"
  ],
  "contIntegration": [
    "https://github.com/ropensci/rebird/blob/master/.github/workflows/R-CMD-check.yaml",
    "https://coveralls.io/r/ropensci/rebird"
  ],
  "releaseNotes": "https://github.com/ropensci/rebird/blob/master/NEWS.md",
  "readme": "https://github.com/ropensci/rebird/blob/master/README.md",
  "fileSize": "45165.535KB",
  "relatedLink": "https://docs.ropensci.org/rebird/",
  "contributor": [
    {
      "@type": "Person",
      "givenName": "Guy",
      "familyName": "Babineau",
      "email": "guy.babineau@gmail.com"
    },
    {
      "@type": "Person",
      "givenName": "Marianna",
      "familyName": "Foos",
      "email": "marianna.foos@gmail.com"
    },
    {
      "@type": "Person",
      "givenName": "David",
      "familyName": "Bradnum",
      "email": "david.bradnum@gmail.com"
    }
  ],
  "copyrightHolder": {},
  "funder": {},
  "developmentStatus": "http://www.repostatus.org/#active"
}

GitHub Events

Committers

Last synced: 8 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages