Get BirdWeather Detections

Retrieves bird detections from the BirdWeather API with optional filters. Handles pagination automatically up to the specified limit. Returns a fully flat data.table with all nested fields (coords, species, station) expanded into individual columns. Includes automatic retry with exponential backoff to handle transient 504/server errors mid-pagination.

Usage

get_detections(
  from = NULL,
  to = NULL,
  tz = NULL,
  time_gte = NULL,
  time_lte = NULL,
  station_ids = NULL,
  station_types = NULL,
  species_ids = NULL,
  species_names = NULL,
  continents = NULL,
  countries = NULL,
  confidence_gte = NULL,
  probability_gte = NULL,
  probability_lte = NULL,
  ne = NULL,
  sw = NULL,
  limit = NULL,
  max_retries = 5
)

Arguments

from: Start date as a string ("YYYY-MM-DD") or full ISO8601 UTC datetime (e.g. "2025-01-01T00:00:00.000Z"). Defaults to 24 hours ago if NULL. If tz is supplied, this should instead be a local datetime string without a trailing Z (e.g. "2025-05-16T00:00:00") and it will be converted to UTC automatically before the query. Note: the BirdWeather API resolves the period filter to calendar days; sub-day filtering is done by the package.
to: End date as a string ("YYYY-MM-DD") or full ISO8601 UTC datetime (e.g. "2025-01-02T00:00:00.000Z"). Defaults to now if NULL. See from for local-time usage with tz.
tz: Optional. An Olson timezone string (e.g. "America/Chicago", "Europe/London") specifying the local timezone of the from and to strings. When supplied, both datetimes are converted to UTC before the API query. When NULL (the default), from and to are passed to the API as-is and are assumed to already be in UTC. Use OlsonNames() for valid timezone strings.
time_gte: Optional. Filter detections at or after this time of day, as a string in "HH:MM" format (e.g. "13:00"). Always interpreted as UTC regardless of the tz argument. Applied via the BirdWeather API's timeOfDayGte argument (minutes since midnight UTC).
time_lte: Optional. Filter detections at or before this time of day, as a string in "HH:MM" format (e.g. "15:00"). Always interpreted as UTC regardless of the tz argument. See time_gte for details.
station_ids: Character vector of station IDs to filter on (optional)
station_types: Character vector of station types to filter on (optional). Known types include "puc" (BirdWeather PUC units), "birdnetpi" (Raspberry Pi-based stations), and "app" (mobile app detections).
species_ids: Character vector of species IDs to filter on (optional)
species_names: Character vector of species common or scientific names to filter on (optional). Will be resolved to IDs via find_species(). If a name matches multiple species, all matches are printed and the user is prompted to rerun with a more specific name.
continents: Character vector of continents to filter on (optional)
countries: Character vector of countries to filter on (optional)
confidence_gte: Minimum BirdNET confidence threshold as a float (optional)
probability_gte: Numeric. Filter detections with probability greater than or equal to this value. Probability is a measure of the species' likely occurrence given timestamp, station_lat, and station_lon. eBird is the source of species occurrence probabilities. (optional)
probability_lte: Numeric. Filter detections with probability less than or equal to this value. See probability_gte for details. (optional)
ne: Named list with lat and lon defining the north-east corner of a bounding box (optional). Must be used together with sw. Example: list(lat = 42.0, lon = -85.0)
sw: Named list with lat and lon defining the south-west corner of a bounding box (optional). Must be used together with ne. Example: list(lat = 36.0, lon = -96.0)
limit: Maximum total number of detections to return (default: NULL, returns all matching detections). Each page fetches 250 at a time. Set to a specific number for exploratory pulls.
max_retries: Maximum number of retry attempts per page on transient errors (default: 5). Retries use exponential backoff with jitter.

Value

A flat data.table where each row is one detection with columns: id, timestamp, confidence, probability, score, species_id, common_name, scientific_name, classification, station_id, station_name, station_type, station_country, station_continent, station_state, station_location, station_lat, station_lon

Examples

if (FALSE) { # \dontrun{
connect_birdweather()

# Get detections for a date range
dets <- get_detections(
  from  = "2025-01-01",
  to    = "2025-01-02",
  limit = 1000
)

# Filter by species name
dets <- get_detections(
  from          = "2025-01-01",
  to            = "2025-01-02",
  species_names = "Black-capped Chickadee",
  limit         = 1000
)

# Filter by time of day (UTC) - only detections between 13:00 and 15:00
dets <- get_detections(
  from     = "2025-05-01",
  to       = "2025-05-31",
  time_gte = "13:00",
  time_lte = "15:00",
  limit    = 1000
)

# Filter by time of day in local timezone
dets <- get_detections(
  from     = "2025-05-01",
  to       = "2025-05-31",
  tz       = "America/New_York",
  time_gte = "13:00",
  time_lte = "15:00",
  limit    = 1000
)

# Filter by continent with confidence threshold
dets <- get_detections(
  from           = "2025-01-01",
  to             = "2025-01-02",
  continents     = "North America",
  confidence_gte = 0.9,
  limit          = 1000
)

# Filter by bounding box using local times
dets <- get_detections(
  from  = "2025-05-16T00:00:00",
  to    = "2025-05-16T23:59:59",
  tz    = "America/Chicago",
  ne    = list(lat = 38.95, lon = -89.85),
  sw    = list(lat = 38.35, lon = -90.75),
  limit = 5000
)
} # }

Usage

Arguments

Value

See also

Examples