This vignette provides an overview of the functions in R package photosearcher.

Searching for photographs

The photo_search() function can be used to search Flickr for photographs that meet specific search criteria. For example, you could search for sightings of animals to better understand the species distribution:

#Search for photos of foxes in the UK for the year 2017
foxes <- photo_search(mindate_taken = "2017-01-01",
                      maxdate_taken = "2018-01-01",
                      text = "foxes",
                      bbox = "-12.875977,49.210420,2.636719,59.977005",
                      has_geo = TRUE)  

#Search for images of trees globally for the 1st of January 2019
trees <- photo_search(mindate_taken = "2019-01-01",
                      maxdate_taken = "2019-01-01",
                      text = "tree",
                      has_geo = TRUE)

#Search for images with text mountain and tagged lake
mountain_lake <- photo_search(mindate_taken = "2019-01-01",
                             maxdate_taken = "2019-02-01",
                             text = "mountain",
                             tags = "lake",
                             has_geo = FALSE)

Using the text parameter will search only for the phrase given. The tag parameter can be search for photographs that contain any of the given tags using tags_any = TRUE, or for only photographs that contain all of the given tags using tags_any = FALSE.

#Search for photographs with any of the tags
tags_any <- photo_search(mindate_taken = "2017-01-01",
                      maxdate_taken = "2018-01-01",
                      tags = c("lake", "mountain"),
                      tags_any = TRUE,
                      bbox = "-12.875977,49.210420,2.636719,59.977005",
                      has_geo = TRUE)

#Search for photographs with all of the tags
tags_all <- photo_search(mindate_taken = "2017-01-01",
                      maxdate_taken = "2018-01-01",
                      tags = c("lake", "mountain"),
                      tags_any = FALSE,
                      bbox = "-12.875977,49.210420,2.636719,59.977005",
                      has_geo = TRUE)

Users can also use the sf package to search via a simple features layer, this can be used to find images of in a specific location for example to aid in resource management for recreational activities in English national parks. When using an parameter that searches for a location or when has_geo == TRUE only metadata about images with latitude and longitude information will be retrieved.

#load shape file
national_parks <- sf::st_read(system.file("shape/National_Parks_England.shp", package="photosearcher"))

#Search for photos of foxes in the UK for the year 2017
parks_hiking <- photo_search(mindate_taken = "2012-01-01",
                             maxdate_taken = "2012-04-01",
                             text = "hiking",
                             sf_layer = national_parks,
                             has_geo = TRUE) 

Downloading images

The package can also download the images based of of their unique id number. You can direct the download to any save directory, if it does not exists it will be automatically created. Downloading images allows for validation of their contents. Here, we demonstrate how to download the first five images that were found using the foxes photo_search example, as well as for a single image. When downloading image, if users need certain pixel width and height dimensions (i.e. for Google Vision limits), these values can be specified.

#Downloading fox images from photosearch
downloaded_foxes <- download_images(photo_id = foxes$id[1:5], 
                                    save_dir = ".")

#Download a specific images based off its id
single_download <- download_images(photo_id = 48704764812, 
                                   save_dir = ".",
                                   max_image_height = 1200,
                                   max_image_width = 1200)

The package will only download images that the owner on Flickr has granted download permission. Those without permission will not be downloaded. The function also provides dataframe outlining which photographs were able to be downloaded. Permission to download does not automatically provide permission to use and distribute, check the photographs licence before use. The photo_search function provides the licence information for each image.

Finding information on a user

The Flickr API can also return publicly available data on its users. The user_info function returns non-identifying information including hometown and occupation. This information could be used in studies aiming to calculate distance people travel to take photographs of certain places or things.

#Find a users hometown
user <- user_info(user_id = "[email protected]")

user$hometown

user$occupation

Get the top tags for a location

Users interested in finding popular attractions or activities in  given location can request the top tags for a given location.

#Find the tags for Southampton, UK
southampton <- location_tags(woe_id = 35356)

#Find the tags for New York state, US
new_york <- location_tags(woe_id =  2347591)

The woe_id argument is a Flickr specific place identifier. A places woeID can be found using the find_place function or using online tools.

Find a locations woeID

Users can also call on the Flickr API to find information about a given location.

  #Find woeID for Kuala Lumpur
  kuala_lumpur <- find_place(place = "Kuala Lumpur")

  kuala_lumpaur$woeid

Finding tags most associated with another tag

The Flickr API can perform clustered usage analysis on a given tag, returning the tags that are most often tagged alongside the given tag. For more information on how this is done check the Flickrs getRelated documentation

  #Find tags associated with zebra
  zebra <- related_tags(tag = "zebra")

  #Find tags most assoicated with hiking
  hiking <- related_tags(tag = "hiking")
  
  #Find tags most associated with the word church
  church <- related_tags(tag = "church")

Finding Exif information about a photo

The Flickr API can also return Exchangeable image file format (Exif) data. For more information on Flickrs Exif data see the Flickrs getExif documentation

  #Find Exif information about a single photo
  exif_photo <- get_exif(photo_id = 48704764812)

Finding information on a single photo

As well as searching for metadata on photographs based up on search terms, users can also find information on a single photograph using its unique photograph number.

  #Find information about a single photo
  single_photo <- get_photoinfo(photo_id = 48704764812)

Find interesting photographs

Flickr has an algorithm for selecting a list of 500 interesting images for each day. Users can get this list using the interesting_list function.

  #Find information about a single photo
  interesting <- interesting_list(date = "2019-01-01")