Package 'inatpick'

iNaturalist annotation term and value IDs

Description

A named lookup table for human-readable annotation labels and their corresponding iNaturalist term_id and term_value_id pairs, for use with inat_fetch().

Usage

inat_annotations

Format

A data frame with columns label, term_id, term_value_id.

Value

A data frame with 20 rows and 3 columns (label, term_id, term_value_id) listing all supported annotation labels and their corresponding iNaturalist API term and term-value IDs.

---

Download photos from iNaturalist observations

Description

Downloads all photos from a data frame returned by inat_fetch(), and optionally saves observation metadata to a CSV file in the same folder.

Usage

inat_download(
  obs,
  out_dir,
  size = "large",
  metadata = TRUE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

obs	Data frame returned by inat_fetch().
out_dir	Character. Directory to save images and metadata. Created if it does not exist. There is no default: you must specify a path, e.g. a folder in your working directory or tempdir() for a temporary location.
size	Character. Photo size: "square" (75px), "small" (240px), "medium" (500px), "large" (1024px), or "original". Default "large". The size is appended to the filename (e.g. obs123_456_large.jpg).
metadata	Logical. If TRUE (default), automatically saves a metadata.csv file to out_dir alongside the downloaded photos.
overwrite	Logical. Re-download files that already exist (default FALSE).
verbose	Logical. Print progress messages (default TRUE).

Value

Invisibly returns a data frame of photo URLs and local file paths.

Examples

## Not run: 
obs <- inat_fetch(taxon_id = 488444, place_id = 6783,
                  user_login = "someuser")

# Download photos and save metadata.csv to the same folder
inat_download(obs, out_dir = file.path(tempdir(), "my_photos"))

# Download photos only, no metadata
inat_download(obs, out_dir = file.path(tempdir(), "my_photos"),
              metadata = FALSE)

## End(Not run)

---

Fetch observations from the iNaturalist API

Description

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.

Usage

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

## Not run: 
# 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

## End(Not run)

---

Export observation metadata to CSV

Description

Extracts key fields from observations returned by inat_fetch() and writes them to a CSV file. Use path to save the CSV in the same folder as your downloaded photos.

Usage

inat_metadata(obs, path, extra_cols = NULL)

Arguments

obs	Data frame returned by inat_fetch().
path	Character. Output CSV file path. There is no default: you must specify a path, e.g. a file in your working directory or tempfile(fileext = ".csv") for a temporary location. To save alongside downloaded photos, use path = file.path(out_dir, "metadata.csv").
extra_cols	Character vector of additional column names from obs to include, if present.

Value

Invisibly returns the metadata data frame.

Note

The common_name column reflects iNaturalist's preferred_common_name, which is typically in English but may vary depending on the taxon and iNaturalist's locale settings.

Examples

## Not run: 
obs <- inat_fetch(taxon_id = 488444, place_id = 6783,
                  user_login = "someuser")

# Save photos and metadata to the same folder
inat_download(obs, out_dir = file.path(tempdir(), "my_photos"))
inat_metadata(obs, path = file.path(tempdir(), "my_photos", "metadata.csv"))

## End(Not run)

---

Search for a place by name on iNaturalist

Description

Returns matching places from iNaturalist, useful for finding the place ID to pass to inat_fetch().

Usage

inat_search_place(name, n = 10)

Arguments

name	Character. Place name to search.
n	Integer. Maximum number of results to return (default 10).

Value

A data frame with columns id, name, display_name, and place_type.

Examples

## Not run: 
inat_search_place("United Kingdom")
inat_search_place("Bolivia")

## End(Not run)

---

Search for a taxon by name on iNaturalist

Description

Returns matching taxa from iNaturalist, useful for finding the taxon ID to pass to inat_fetch().

Usage

inat_search_taxon(name, rank = NULL, n = 10)

Arguments

name	Character. Taxon name to search (common or scientific).
rank	Character or NULL. Filter results by taxonomic rank, e.g. "genus", "species", "family". Default NULL returns all ranks.
n	Integer. Maximum number of results to return (default 10).

Value

A data frame with columns id, name, common_name, rank, and observations_count, ordered by number of observations.

Note

The common_name field reflects iNaturalist's preferred_common_name, which is typically in English but may vary depending on the taxon and iNaturalist's locale settings.

Examples

## Not run: 
inat_search_taxon("Drosera rotundifolia")
inat_search_taxon("Drosera", rank = "genus")
inat_search_taxon("sundew", rank = "species")

## End(Not run)

---