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

rebird: wrapper to the eBird API

<!-- badges: start -->

<!-- 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

install.packages("rebird")

Or the development version from Github

install.packages("devtools")
devtools::install_github("ropensci/rebird")

Direct use of rebird

Load the package:

library("rebird")

The eBird API server 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:

species_code('sula variegata')
#> Peruvian Booby (Sula variegata): perboo1
#> [1] "perboo1"

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

rebird::tax
#> # A tibble: 17,415 × 15
#>    sciName     comName speciesCode category taxonOrder bandingCodes comNameCodes
#>    <chr>       <chr>   <chr>       <chr>         <dbl> <chr>        <chr>       
#>  1 Struthio c… Common… ostric2     species           2 <NA>         COOS        
#>  2 Struthio m… Somali… ostric3     species           7 <NA>         SOOS        
#>  3 Struthio c… Common… y00934      slash             8 <NA>         SOOS,COOS   
#>  4 Casuarius … Southe… soucas1     species          10 <NA>         SOCA        
#>  5 Casuarius … Dwarf … dwacas1     species          11 <NA>         DWCA        
#>  6 Casuarius … Northe… norcas1     species          12 <NA>         NOCA        
#>  7 Dromaius n… Emu     emu1        species          13 <NA>         EMU,COEM    
#>  8 Apteryx au… Southe… sobkiw1     species          19 <NA>         SBKI        
#>  9 Apteryx au… Southe… sobkiw2     issf             20 <NA>         SBKI        
#> 10 Apteryx au… Southe… sobkiw3     issf             21 <NA>         SBKI        
#> # ℹ 17,405 more rows
#> # ℹ 8 more variables: sciNameCodes <chr>, order <chr>, familyCode <chr>,
#> #   familyComName <chr>, familySciName <chr>, reportAs <chr>, extinct <lgl>,
#> #   extinctYear <int>

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

new_tax <- ebirdtaxonomy()

Sightings at location determined by latitude/longitude

Search for bird occurrences by latitude and longitude point

ebirdgeo(species = species_code('spinus tristis'), lat = 42, lng = -76)
#> American Goldfinch (Spinus tristis): amegfi
#> # A tibble: 28 × 13
#>    speciesCode comName  sciName locId locName obsDt howMany   lat   lng obsValid
#>    <chr>       <chr>    <chr>   <chr> <chr>   <chr>   <int> <dbl> <dbl> <lgl>   
#>  1 amegfi      America… Spinus… L200… Oakrid… 2025…       1  42.1 -75.9 TRUE    
#>  2 amegfi      America… Spinus… L124… Happy … 2025…      13  42.1 -75.9 TRUE    
#>  3 amegfi      America… Spinus… L888… Nowlan… 2025…      42  42.1 -75.9 TRUE    
#>  4 amegfi      America… Spinus… L104… 14 Bou… 2025…       4  42.1 -75.9 TRUE    
#>  5 amegfi      America… Spinus… L186… Otsini… 2025…       2  42.1 -75.9 TRUE    
#>  6 amegfi      America… Spinus… L471… Home: … 2025…       4  42.1 -76.1 TRUE    
#>  7 amegfi      America… Spinus… L351… Brixiu… 2025…      14  42.1 -76.0 TRUE    
#>  8 amegfi      America… Spinus… L224… Highla… 2025…       2  42.1 -76.0 TRUE    
#>  9 amegfi      America… Spinus… L233… 1443–1… 2025…      12  42.1 -75.9 TRUE    
#> 10 amegfi      America… Spinus… L399… 701 Pa… 2025…       1  42.1 -76.0 TRUE    
#> # ℹ 18 more rows
#> # ℹ 3 more variables: obsReviewed <lgl>, locationPrivate <lgl>, subId <chr>

Recent observations at a region

Search for bird occurrences by region and species name

ebirdregion(loc = 'US', species = 'btbwar')
#> # A tibble: 46 × 13
#>    speciesCode comName  sciName locId locName obsDt howMany   lat   lng obsValid
#>    <chr>       <chr>    <chr>   <chr> <chr>   <chr>   <int> <dbl> <dbl> <lgl>   
#>  1 btbwar      Black-t… Setoph… L106… Palmet… 2025…       1  26.9 -80.1 TRUE    
#>  2 btbwar      Black-t… Setoph… L163… Young … 2025…       1  26.5 -80.1 TRUE    
#>  3 btbwar      Black-t… Setoph… L171… Three … 2025…       1  28.1 -80.7 TRUE    
#>  4 btbwar      Black-t… Setoph… L246… Green … 2025…       1  26.5 -80.2 TRUE    
#>  5 btbwar      Black-t… Setoph… L405… Frog P… 2025…       1  25.4 -80.6 TRUE    
#>  6 btbwar      Black-t… Setoph… L129… Lantan… 2025…       2  26.6 -80.0 TRUE    
#>  7 btbwar      Black-t… Setoph… L330… Orchid… 2025…       1  26.2 -80.3 TRUE    
#>  8 btbwar      Black-t… Setoph… L399… 715 Pa… 2025…       2  26.9 -80.1 TRUE    
#>  9 btbwar      Black-t… Setoph… L458… Kendal… 2025…       1  25.7 -80.4 TRUE    
#> 10 btbwar      Black-t… Setoph… L123… Merrit… 2025…       1  28.7 -80.7 TRUE    
#> # ℹ 36 more rows
#> # ℹ 3 more variables: obsReviewed <lgl>, locationPrivate <lgl>, subId <chr>

Recent observations at hotspots

Search for bird occurrences by a given hotspot

ebirdregion(loc = 'L99381')
#> # A tibble: 57 × 14
#>    speciesCode comName  sciName locId locName obsDt howMany   lat   lng obsValid
#>    <chr>       <chr>    <chr>   <chr> <chr>   <chr>   <int> <dbl> <dbl> <lgl>   
#>  1 cangoo      Canada … Branta… L993… Stewar… 2025…      80  42.5 -76.5 TRUE    
#>  2 mallar3     Mallard  Anas p… L993… Stewar… 2025…     150  42.5 -76.5 TRUE    
#>  3 ambduc      America… Anas r… L993… Stewar… 2025…       3  42.5 -76.5 TRUE    
#>  4 canvas      Canvasb… Aythya… L993… Stewar… 2025…       8  42.5 -76.5 TRUE    
#>  5 redhea      Redhead  Aythya… L993… Stewar… 2025…     500  42.5 -76.5 TRUE    
#>  6 rinduc      Ring-ne… Aythya… L993… Stewar… 2025…       5  42.5 -76.5 TRUE    
#>  7 comgol      Common … Buceph… L993… Stewar… 2025…       4  42.5 -76.5 TRUE    
#>  8 hoomer      Hooded … Lophod… L993… Stewar… 2025…      10  42.5 -76.5 TRUE    
#>  9 commer      Common … Mergus… L993… Stewar… 2025…     300  42.5 -76.5 TRUE    
#> 10 rebmer      Red-bre… Mergus… L993… Stewar… 2025…      10  42.5 -76.5 TRUE    
#> # ℹ 47 more rows
#> # ℹ 4 more variables: obsReviewed <lgl>, locationPrivate <lgl>, subId <chr>,
#> #   exoticCategory <chr>

Nearest observations of a species

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

nearestobs(species_code('branta canadensis'), 42, -76)
#> Canada Goose (Branta canadensis): cangoo
#> # A tibble: 14 × 13
#>    speciesCode comName  sciName locId locName obsDt howMany   lat   lng obsValid
#>    <chr>       <chr>    <chr>   <chr> <chr>   <chr>   <int> <dbl> <dbl> <lgl>   
#>  1 cangoo      Canada … Branta… L109… Hillcr… 2025…       8  42.2 -75.9 TRUE    
#>  2 cangoo      Canada … Branta… L247… Conflu… 2025…      14  42.1 -75.9 TRUE    
#>  3 cangoo      Canada … Branta… L189… Conflu… 2025…       5  42.1 -75.9 TRUE    
#>  4 cangoo      Canada … Branta… L505… Boland… 2025…       9  42.2 -75.9 TRUE    
#>  5 cangoo      Canada … Branta… L186… Otsini… 2025…      60  42.1 -75.9 TRUE    
#>  6 cangoo      Canada … Branta… L201… Conflu… 2025…     150  42.1 -76.3 TRUE    
#>  7 cangoo      Canada … Branta… L351… Anson … 2025…      34  42.1 -76.1 TRUE    
#>  8 cangoo      Canada … Branta… L714… Draper… 2025…       4  42.1 -76.3 TRUE    
#>  9 cangoo      Canada … Branta… L367… River … 2025…     120  42.1 -76.3 TRUE    
#> 10 cangoo      Canada … Branta… L154… IBM Gl… 2025…      13  42.1 -76.0 TRUE    
#> 11 cangoo      Canada … Branta… L278… Harold… 2025…      85  42.1 -76.0 TRUE    
#> 12 cangoo      Canada … Branta… L137… Apalac… 2025…      80  42.1 -76.1 TRUE    
#> 13 cangoo      Canada … Branta… L166… Chugnu… 2025…      80  42.1 -76.0 TRUE    
#> 14 cangoo      Canada … Branta… L501… Willia… 2025…      80  42.1 -76.0 TRUE    
#> # ℹ 3 more variables: obsReviewed <lgl>, locationPrivate <lgl>, subId <chr>

<!-- ## Frequency of observations at hotspots or regions &#10;Obtain his