Fetch observations from the iNaturalist API

Source: R/inat_fetch.R

Retrieves all observations matching the given filters, handling pagination automatically. Multiple annotations can be passed as a character vector; each is fetched separately and the results combined.

inat_fetch(
  taxon_id,
  place_id = NULL,
  user_login = NULL,
  annotation = NULL,
  quality_grade = "any",
  year = NULL,
  month = NULL,
  licensed = NULL,
  per_page = 200,
  verbose = TRUE
)

Arguments

taxon_id

Integer. iNaturalist taxon ID (e.g. 488444 for Caiophora chuquitensis).

place_id

Integer or NULL. iNaturalist place ID (e.g. 6783 for Bolivia).

user_login

Character or NULL. iNaturalist username.

annotation

Character vector of annotation labels, or a single integer vector c(term_id, term_value_id), or NULL. Use labels from inat_annotations (e.g. "flowers", "green_leaves", "alive"). Multiple labels can be passed as c("flowers", "green_leaves") — each is fetched separately and results are combined. See inat_annotations for all valid labels.

quality_grade

Character. One of "research", "needs_id", or "any" (default).

year

Integer or NULL. Filter by observation year.

month

Integer (1–12) or NULL. Filter by observation month.

licensed

Logical or NULL. If TRUE, return only observations with a CC photo license.

per_page

Integer. Results per API page (max 200).

verbose

Logical. Print progress messages (default TRUE).

Value

A data frame of observations with list-column photos.

See also

inat_annotations for all annotation labels and IDs.

Examples

if (FALSE) { # \dontrun{
# Single annotation
obs <- inat_fetch(taxon_id = 488444, place_id = 6783,
                  annotation = "flowers")

# Multiple annotations
obs <- inat_fetch(taxon_id = 51935, place_id = 6857,
                  annotation = c("flowers", "green_leaves"))

# See all available annotation labels
inat_annotations
} # }