Package {inatpick}

inatpick: Download Photos and Metadata from iNaturalist

Description

A lightweight interface to the iNaturalist API for downloading observation photos and exporting metadata to CSV. Supports filtering by taxon, place, user, and annotation.

Details

The main workflow:

1. inat_search_taxon() / inat_search_place() — find taxon and place IDs

2. inat_fetch() — retrieve observations from the API

3. inat_download() — download photos to a local folder

4. inat_metadata() — export observation metadata to CSV

Author(s)

Maintainer: Andrés Romero-Bravo aromerobravo@gmail.com

Authors:

• Andrés Romero-Bravo aromerobravo@gmail.com

See Also

Useful links:

• https://github.com/andresarb/inatpick

• https://andresarb.github.io/inatpick/

• Report bugs at https://github.com/andresarb/inatpick/issues

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

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

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

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

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

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)

Resolve annotation label to term_id and term_value_id

Description

Resolve annotation label to term_id and term_value_id

Usage

resolve_annotation(annotation)

Arguments

Value

A named integer vector with term_id and term_value_id.