Title: Access to Flickr API
Version: 0.1.0.1
Description: Provides an interface to the Flickr API https://www.flickr.com/services/api/ and allows R users to download data on Flickr.
Depends: R (≥ 3.1)
License: GPL (≥ 3)
Encoding: UTF-8
Imports: httr2, janitor, magrittr, rlang, utils
Suggests: sf, knitr, rmarkdown
VignetteBuilder: knitr
RoxygenNote: 7.2.0.9000
NeedsCompilation: no
Packaged: 2022-07-11 10:53:57 UTC; koki2
Author: Koki Ando [aut, cre], Eli Pousson [aut, ctb]
Maintainer: Koki Ando <koki.25.ando@gmail.com>
Repository: CRAN
Date/Publication: 2022-07-11 12:40:10 UTC

FlickrAPI: Access to Flickr API via R

Description

An R package that provides an interface to the Flickr API <https://www.flickr.com/services/api/>, which allows R users to download publicly available data on Flickr feed such as location, exif, list of photos posted by specific user.

Author(s)

Koki Ando koki.25.ando@gmail.com

See Also

https://www.flickr.com/services/api/


Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling 'rhs(lhs)'.


Request data from the Flickr API

Description

Request data from the Flickr API using the provided method, API key, and any additional values passed to [httr2::req_url_query].

Usage

FlickrAPIRequest(
  method = NULL,
  api_key = NULL,
  format = "json",
  simplifyVector = TRUE,
  check_type = FALSE,
  ...
)

Arguments

method

Flickr API method to use for request.

api_key

Flickr API key. If api_key is 'NULL', the function uses [getFlickrAPIKey()] to use the environment variable "FLICKR_API_KEY" as the key.

format

Format parameter passed to [httr2::req_url_query]

simplifyVector

Default to 'TRUE', passed to [httr2::resp_body_json]

check_type

Default to 'FALSE', passed to [httr2::resp_body_json]

...

Additional parameters passed to [httr2::req_url_query]


Get EXIF data for a Flickr photo.

Description

Return a data of EXIF data for a given photo. The calling user must have permission to view the photo.

Usage

getExif(api_key = NULL, photo_id = NULL)

get_exif(api_key = NULL, photo_id = NULL)

Arguments

api_key

Flickr API key. If api_key is 'NULL', the function uses [getFlickrAPIKey()] to use the environment variable "FLICKR_API_KEY" as the key.

photo_id

The id of the photo to fetch information for

Value

This function returns a data frame of EXIF information of given photograph

Examples

## Not run: 
getExif(api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", photo_id = "45961963324")

## End(Not run)


Get a data frame of hot tags for a given time period.

Description

Get a data frame of hot tags for a given time period.

Usage

getHotTags(api_key = NULL, period = c("day", "week"), count = 20)

get_hot_tags(api_key = NULL, period = c("day", "week"), count = 20)

Arguments

api_key

Flickr API key. If api_key is 'NULL', the function uses [getFlickrAPIKey()] to use the environment variable "FLICKR_API_KEY" as the key.

period

The period for which to fetch hot tags. Valid values are day or week. Defaults to day

count

The number of tags to return. Defaults to 20. Maximum allowed value is 200.

Value

This function a data frame of hot tags for the given period

See Also

https://www.flickr.com/services/api/flickr.tags.getHotList.html

Examples

## Not run: 
getHotTags(
  api_key = "*********",
  period = "day", count = 20
)

## End(Not run)


Get available information for a Flickr photo.

Description

R access to photo information of photos posted on Flickr via Flickr API.

Usage

getPhotoInfo(
  api_key = NULL,
  photo_id,
  output = c("location", "date", "url", "tags")
)

get_photo_info(
  api_key = NULL,
  photo_id,
  output = c("location", "date", "url", "tags")
)

Arguments

api_key

Flickr API key. If api_key is 'NULL', the function uses [getFlickrAPIKey()] to use the environment variable "FLICKR_API_KEY" as the key.

photo_id

The id of the photo to get information for.

output

Output data type. Supported options include "all", "location", "date", "url" or "tags". If output = "all", the function returns a list with all available data. Otherwise the function returns a data frame.

Value

This function returns data of specific photo's information.

See Also

https://www.flickr.com/services/api/flickr.photos.getInfo.html

Examples

## Not run: 
getPhotoInfo(
  api_key = "XXXXXXXXXX",
  photo_id = "30484882493",
  output = "location"
)

## End(Not run)

Search for photos on Flickr by user id, tags, license, or bounding box

Description

Use the Flickr Search API to return pages of photos sorted by date posted, date taken, interestingness, and relevance. Optional search parameters including spatial bounding box, user id, tags, and image license.

Usage

getPhotoSearch(
  api_key = NULL,
  user_id = NULL,
  tags = NULL,
  license_id = NULL,
  sort = "date-posted",
  desc = FALSE,
  bbox = NULL,
  img_size = NULL,
  extras = NULL,
  per_page = 100,
  page = NULL,
  ...
)

get_photo_search(
  api_key = NULL,
  user_id = NULL,
  tags = NULL,
  license_id = NULL,
  sort = "date-posted",
  desc = FALSE,
  bbox = NULL,
  img_size = NULL,
  extras = NULL,
  per_page = 100,
  page = NULL,
  ...
)

Arguments

api_key

Flickr API key. If api_key is 'NULL', the function uses [getFlickrAPIKey()] to use the environment variable "FLICKR_API_KEY" as the key.

user_id

The NSID of the user with photos to search. If this parameter is NULL passed then all public photos will be searched.

tags

A vector of tags to search for.

license_id

The license id for photos. For possible values see the Flickr API method flickr.photos.licenses.getInfo or see details for more information.

sort

Order to sort returned photos. The possible values are: "date-posted-asc", "date-posted-desc", "date-taken-asc", "date-taken-desc", "interestingness-desc", "interestingness-asc", and "relevance" The trailing "-asc" or "-desc" indicator for sort direction is optional when using the desc parameter.

desc

If 'TRUE', sort in descending order by the selected sort variable; defaults to 'FALSE'.

bbox

A object of class 'bbox' or a numeric vector with values for xmin, ymin, xmax and ymax representing the bottom-left corner of the box and the top-right corner.

img_size

A character string with the abbreviation for one or more image sizes ("sq", "t", "s", "q", "m", "n", "z", "c", "l", or "o"). If a single img_size is provided the url, width, and height columns are renamed (e.g. img_url instead of url_sq) and an img_asp column is added to the results; defaults to 'NULL'.

extras

A vector of extra information to fetch for each returned record. Currently supported fields are: c("description", "license", "date_upload", "date_taken", "owner_name", "icon_server", "original_format", "last_update", "geo", "tags", "machine_tags", "o_dims", "views", "media", "path_alias", "url_sq", "url_t", "url_s", "url_q", "url_m", "url_n", "url_z", "url_c", "url_l", "url_o")

per_page

Number specifying how many results per page to return. Default 100 results per page. Maximum of 250 if 'bbox' provided or 500 otherwise.

page

Number specifying which search results page to return. Default is page 1 of results returned.

...

Additional parameters that can include licence_id (legacy spelling),

Details

License id options:

license_id can be an integer from 0 to 10 or a corresponding license code including:

- "c" (All Rights Reserved), - "by-bc-sa" (Attribution-NonCommercial-ShareAlike), - "by-nc" (Attribution-NonCommercial), - "by-nc-nd" (Attribution-NonCommercial-NoDerivs), - "by" (Attribution), - "by-sa" (Attribution-ShareAlike), - "by-nd" (Attribution-NoDerivs), - "nkc" (No known copyright restrictions), - "pd-us" (United States Government Work), - "cc0" (Public Domain Dedication), - or "pd" (Public Domain Mark).

Value

This function returns data of specific photos matching search parameters.

Examples

## Not run: 
# Search for photos tagged "cats" and "dogs"
# Return images in descending order of date taken
getPhotoSearch(
  api_key = "XXXXXXXXXX",
  sort = "date-taken-desc",
  tags = c("cats", "dogs")
)

## End(Not run)
## Not run: 
# Search for photos uploaded to the NPS Grand Canyon user account.
# Return extra fields including the date taken and square image URL.
getPhotoSearch(
  api_key = "XXXXXXXXXX",
  user_id = "grand_canyon_nps",
  extras = c("date_taken", "url_sq")
)

## End(Not run)
## Not run: 
# Search for photos tagged "panda" in the area of Ueno Zoo, Tokyo, Japan
getPhotoSearch(
  api_key = "XXXXXXXXXX",
  tags = "panda",
  bbox = c(139.7682226529, 35.712627977, 139.7724605432, 35.7181464141),
  extras = c("geo", "owner_name", "tags")
)

## End(Not run)

Get Flickr user photos or a user's favorite photos

Description

Returns photos from the given user's photo stream. Only photos visible to the calling user will be returned.

Usage

getPhotos(user_id = NULL, img_size = "s", extras = NULL, api_key = NULL, ...)

get_photos(user_id = NULL, img_size = "s", extras = NULL, api_key = NULL, ...)

getFavePhotos(
  user_id = NULL,
  img_size = "s",
  extras = NULL,
  fave_date = NULL,
  public = TRUE,
  api_key = NULL,
  page = NULL,
  per_page = 100,
  ...
)

get_fave_photos(
  user_id = NULL,
  img_size = "s",
  extras = NULL,
  fave_date = NULL,
  public = TRUE,
  api_key = NULL,
  page = NULL,
  per_page = 100,
  ...
)

Arguments

user_id

The NSID of the user whose photos to return. A value of "me" return the calling user's photos.

img_size

A character string with the abbreviation for one or more image sizes ("sq", "t", "s", "q", "m", "n", "z", "c", "l", or "o"). If a single img_size is provided the url, width, and height columns are renamed (e.g. img_url instead of url_sq) and an img_asp column is added to the results; defaults to 'NULL'.

extras

A vector of extra information to fetch for each returned record. Currently supported fields are: c("description", "license", "date_upload", "date_taken", "owner_name", "icon_server", "original_format", "last_update", "geo", "tags", "machine_tags", "o_dims", "views", "media", "path_alias", "url_sq", "url_t", "url_s", "url_q", "url_m", "url_n", "url_z", "url_c", "url_l", "url_o")

api_key

Flickr API key. If api_key is 'NULL', the function uses [getFlickrAPIKey()] to use the environment variable "FLICKR_API_KEY" as the key.

...

Additional parameters passed to [getPhotoSearch]

fave_date

Length 1 or 2 vector with UNIX formatted date (may include minimum and maximum favorite date).

public

If 'TRUE', get public favorites (no authentication needed). If 'FALSE', get all favorite (requires authentication for access).

page

Number specifying which search results page to return. Default is page 1 of results returned.

per_page

Number specifying how many results per page to return. Default 100 results per page. Maximum of 250 if 'bbox' provided or 500 otherwise.

Details

For 'getFavePhotos' the provided user_id may need to be the NSID code or the user name rather than the typical user id due to some inconsistencies in the Flickr API.

Value

This function returns a data.frame including columns:

Examples

## Not run: 
getPhotos(api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", user_id = "141696738@N08")

## End(Not run)

Set and get a Flickr API key to/from environment variables.

Description

Set and get a Flickr API key to/from environment variables.

Get Flickr API key from environment variables

Usage

setFlickrAPIKey(api_key, overwrite = FALSE, install = FALSE)

set_flickr_api_key(api_key, overwrite = FALSE, install = FALSE)

getFlickrAPIKey(api_key = NULL)

get_flickr_api_key(api_key = NULL)

Arguments

api_key

Flickr API key

overwrite

If 'TRUE', overwrite existing token; Default: 'FALSE'

install

If 'TRUE', install token for use in future sessions; Default: 'FALSE'

mirror server hosted at Truenetwork, Russian Federation.