---
title: "Introduction to using FlickrAPI"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to using FlickrAPI}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette provides a quick tour of the R package "FlickrAPI". This package is maintained by [Koki Ando](https://github.com/koki25ando).

# Installation

```{r setup}
# pak::pkg_install("koki25ando/FlickrAPI")
library(FlickrAPI)
```

# Setting up a Flickr API key

```{r, eval = FALSE}
# Set the API key for a single session
setFlickrAPIKey(api_key = "YOUR_API_KEY_HERE")

# Install the API key for future sessions
setFlickrAPIKey(api_key = "YOUR_API_KEY_HERE", install = TRUE)

# Overwrite an existing API key
setFlickrAPIKey(api_key = "YOUR_API_KEY_HERE", overwrite = TRUE)
```

# Searching for Flickr photos

There are two functions for searching Flickr photos:

- `getPhotos()`
- `getPhotoSearch()`

`getPhotos()` allows you to get public photos for any Flickr user or all photos from the account associated with the Flickr API key.

```{r, eval = FALSE}
# Search for photos uploaded by Koki Ando
getPhotos(user_id = "141696738@N08")
```

`getPhotoSearch()` supports a broader range of search options including:

- User id
- Tags
- License
- Bounding box (for photos with locations)

```{r, eval = FALSE}
getPhotoSearch(tags = c("cats", "dogs"))
```

```{r, eval = FALSE}
# Search for photos of cats and dogs in North Carolina
nc_bbox <- c(-84.32385, 33.88199, -75.45698, 36.58965)

getPhotoSearch(tags = c("cats", "dogs"), bbox = nc_bbox)
```

`getPhotoSearch()` returns 100 photos per page by default but this can be increased to 250 if using the bbox parameter searching by location or 500 otherwise. Additional pages can be accessed using the page parameter.

The extras parameter can be used to return additional information about the photos including "description", "date_upload", "date_taken", "owner_name", and urls for all available image sizes.

```{r, eval = FALSE}
# Search for photos tagged "panda" in the area of Ueno Zoo, Tokyo, Japan
getPhotoSearch(
  tags = "panda",
  bbox = c(139.7682226529, 35.712627977, 139.7724605432, 35.7181464141),
  sort = "interestingness-desc",
  extras = c("geo", "tags")
)
```


# Get data on Flickr photos

There are two functions for getting data about a specific Flickr photo:

- `getExif()`
- `getPhotoInfo()`

## Get Flickr data for a photo

```{r, eval = FALSE}
getPhotoInfo(photo_id = "51899696261", output = "url")
```

## Get EXIF metadata for a photo

```{r, eval = FALSE }
getExif(photo_id = "51872765082")
```