---
title: "Getting started with inatpick"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with inatpick}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse  = TRUE,
  comment   = "#>",
  eval      = FALSE
)
```

## Overview

`inatpick` provides a simple workflow for downloading photos and metadata
from [iNaturalist](https://www.inaturalist.org) via its API. The main
functions are:

| Function | Description |
|---|---|
| `inat_search_taxon()` | Find a taxon ID by name |
| `inat_search_place()` | Find a place ID by name |
| `inat_fetch()` | Fetch observations from the API |
| `inat_download()` | Download photos and metadata to a local folder |
| `inat_metadata()` | Export observation metadata to CSV |

```{r}
library(inatpick)
```

---

## Example: *Drosera* in the United Kingdom

In this example we download research-grade, CC-licensed observations of
sundews (*Drosera* genus) recorded in the United Kingdom by iNaturalist
user andresrb, filtering for observations annotated with green leaves or
open flowers.

### Step 1 — Find taxon and place IDs

Search by name to find the iNaturalist IDs. Use the `rank` argument to
filter results to a specific taxonomic level:

```{r}
# Search for the genus Drosera
inat_search_taxon("Drosera", rank = "genus")
# → id = 51935

# Search for the place
inat_search_place("United Kingdom")
# → id = 6857
```

### Step 2 — Fetch observations

Fetch research-grade, CC-licensed observations with multiple annotations.
Each annotation is fetched separately and results are combined automatically,
with duplicates removed:

```{r}
obs <- inat_fetch(
  taxon_id      = 51935,        # Drosera genus
  place_id      = 6857,         # United Kingdom
  user_login    = "andresrb",
  annotation    = c("green_leaves", "flowers"),
  quality_grade = "research",
  licensed      = TRUE
)

nrow(obs)  # how many unique observations?
```

### Step 3 — Download photos and metadata

`inat_download()` requires an `out_dir` — here we use a folder in the
working directory, but `tempdir()` works too for a temporary location.
By default it also saves a `metadata.csv` to the same folder. The `size`
argument controls resolution:

| Size | Resolution | Best for |
|---|---|---|
| `"square"` | 75px | thumbnails |
| `"small"` | 240px | quick preview |
| `"medium"` | 500px | general use |
| `"large"` | 1024px | research (default) |
| `"original"` | full | publication |

Files are named `obs{observation_id}_{photo_id}_{size}.jpg`.

```{r}
inat_download(
  obs,
  out_dir = "drosera_uk",
  size    = "large"
)
```

Already-downloaded files are skipped by default (`overwrite = FALSE`).

To download photos only without metadata:

```{r}
inat_download(obs, out_dir = "drosera_uk", metadata = FALSE)
```

### Step 4 — Export metadata separately

If you need the metadata CSV in a different location:

```{r}
inat_metadata(obs, path = "drosera_uk.csv")
```

The CSV includes observation ID, date, taxon name, common name, observer,
place, coordinates, URL, and number of photos.

---

## Finding taxon and place IDs

Use the search functions or find IDs directly in iNaturalist URLs:

- **Taxon ID**: `inaturalist.org/taxa/51935-Drosera` → `51935`
- **Place ID**: `inaturalist.org/observations?place_id=6857` → `6857`

---

## All annotation options

```{r}
# See all available annotation labels and their IDs
inat_annotations
```

---

## Further filtering options

```{r}
# Research-grade only, flowering, in July
obs_july <- inat_fetch(
  taxon_id      = 51935,
  place_id      = 6857,
  annotation    = "flowers",
  quality_grade = "research",
  month         = 7
)

# All observations worldwide — use with caution for common taxa
obs_world <- inat_fetch(taxon_id = 51935)
```

---

## Photo licenses & attribution

Photos downloaded from iNaturalist retain their original licenses as set
by individual observers (CC0, CC-BY, CC-BY-NC, etc.). Use
`licensed = TRUE` in `inat_fetch()` to restrict to CC-licensed photos only.
Always credit the observer and respect the license terms when using images
in research or publication.

See [iNaturalist Terms of Service](https://www.inaturalist.org/pages/terms)
for more information.