RecentNearbySpecies {lifeR}

Retrieve recent nearby observations of a species

Description

Retrieve recent nearby observations of a species

Usage

RecentNearbySpecies(
  key,
  species_code,
  lat = 32.241,
  lng = -110.938,
  dist = 50,
  back = 4,
  hotspot = TRUE,
  include_provisional = FALSE,
  max_tries = 5,
  timeout_sec = 30,
  verbose = TRUE
)

Arguments

key

Character eBird API key.

species_code

Species code for species of interest; usually a six-character string such as "purmar" or "batpig". See https://science.ebird.org/en/use-ebird-data/the-ebird-taxonomy/ for more information.

lat

Numeric decimal degree latitude; use negative values for southern latitudes (i.e. -46.86, not "46.86 S").

lng

Numeric decimal degree longitude; use negative values for western longitudes (i.e. -72.08, not "72.08 W").

dist

Numeric radius in kilometers of distance from geographic center point given by lat and lng from which to return recent observations of a species.

back

Integer number of days back to search for observations.

hotspot

Logical indicating whether or not to restrict results to hotspot locations.

include_provisional

Logical indicating whether or not to include observations which have not yet been reviewed.

max_tries

Integer maximum number of query attempts to try.

timeout_sec

Integer time to allow before query is aborted.

verbose

Logical determining whether or not to print messages during queries.

Details

The function uses the eBird API (see https://documenter.getpostman.com/view/664302/S1ENwy59/) to query recent sightings of a species. Queries to the eBird API require a user key; you can request an eBird API key by logging into your eBird account and navigating to https://ebird.org/api/keygen/. See examples and vignette for using your eBird API key.

Value

An object of class "recent_obs" with the following elements:

query_type

The type of query performed.

query_parameters

List of query parameters passed in request, including the species code.

obs

Data frame of observations returned from query; if no observations are returned, obs is NULL. Columns include:

speciesCode

The (usually) six-letter species code, see https://science.ebird.org/en/use-ebird-data/the-ebird-taxonomy/

comName

Species' common name.

sciName

Species' scientific name.

locId

eBird identifier of the location.

locName

Name of the location.

obsDt

Observation date as character string in the format "YYYY-MM-DD HH:MM".

howMany

Number of individuals.

lat

Decimal latitude.

lng

Decimal longitude.

obsValid

Logical indicating if observation marked as valid.

obsReviewed

Logical indicating if observation has been reviewed.

locationPrivate

Logical indicating whether or not location is designated as private.

subId

Checklist ID for this observation.

Examples

## Not run: 
  # Read eBird key in from file
  key <- scan(file = "ebird-key.txt", what = "character")
  # Search for observations of Verdin within 5 km from lat/lng coordinates
  recent <- RecentNearbySpecies(key = key, species_code = "verdin",
                                lat = 32.28, lng = -111.02, dist = 5)

## End(Not run)