Skip to contents

Query WikiAves for bird media metadata

Source: R/query_wikiaves.R
query_wikiaves.Rd

query_wikiaves searches for metadata from WikiAves, a Brazilian citizen-science platform and the largest birdwatching community in the country. It functions as a collaborative, interactive encyclopedia of Brazilian birds, where users contribute georeferenced photographs and sound recordings that build a large database used for research and conservation. query_wikiaves returns metadata for image or sound recordings matching a given species, including download links, locality, author, and verification status.

WikiAves sits behind Cloudflare's bot protection, so this function requires authentication, which is done with access_wikiaves() (see Examples).

Usage

query_wikiaves(
  species = getOption("suwo_species"),
  format = getOption("suwo_format", c("image", "sound")),
  cores = getOption("suwo_cores", 1),
  pb = getOption("suwo_pb", TRUE),
  verbose = getOption("suwo_verbose", TRUE),
  all_data = getOption("suwo_all_data", FALSE),
  raw_data = getOption("suwo_raw_data", FALSE),
  cookies = Sys.getenv("wikiaves_cookies")
)

Arguments

species

Character string giving the scientific name of the species to search for (e.g. "Procnias averano"). Defaults to getOption("suwo_species").

format

Character string, either "image" or "sound", indicating which type of media to query. Defaults to getOption("suwo_format", c("image", "sound")).

cores

Numeric. Number of cores to use for parallel processing of paginated results. Defaults to getOption("suwo_cores", 1).

pb

Logical. Whether to show a progress bar. Defaults to getOption("suwo_pb", TRUE).

verbose

Logical. Whether to print progress and error messages. Defaults to getOption("suwo_verbose", TRUE).

all_data

Logical. Whether to return all available columns rather than the standard suwo output columns. Defaults to getOption("suwo_all_data", FALSE).

raw_data

Logical. Whether to return the raw, unformatted query output instead of the standardized suwo output. Defaults to getOption("suwo_raw_data", FALSE).

cookies

Single character string of WikiAves authentication credentials, used to get past Cloudflare's bot protection on every request this function makes. It is generated by access_wikiaves() and saved as an environmental variable (Sys.getenv("wikiaves_cookies")), which is read by default by query_wikiaves.

Value

A data frame of WikiAves observations matching species and format, with standardized suwo columns (or all available columns if all_data = TRUE, or the raw query output if raw_data = TRUE). Returns invisible(NULL) if the species is not found, no matching records exist, or the query otherwise fails.

Details

WikiAves sits behind Cloudflare's bot protection, so cookies must be a valid, non-expired credentials string – see Do I need to obtain new credentials before every call? below.

Do I need to obtain new credentials before every call? No – only once per Cloudflare session. The cf_clearance cookie returned by access_wikiaves() is typically valid for roughly an hour (Cloudflare does not publish an exact figure, and the duration can vary); after that, requests made with it will start failing again with an HTTP 403, and access_wikiaves() simply needs to be called again to obtain a fresh set of credentials.

A few practical notes on when to refresh credentials:

  • If query_wikiaves is paging through a species with a large number of recordings, the session may expire partway through a single call – if that happens, call access_wikiaves() again and retry.

  • If some time has passed since the cookies were last obtained, refresh them before querying rather than waiting for a failure.

  • access_wikiaves() reuses the same browser profile directory by default, so repeat calls are usually fast and do not require solving the Cloudflare challenge by hand each time.

If valid cookies are not supplied, query_wikiaves fails gracefully with an explanatory message and returns invisible(NULL) rather than throwing an error.

See also

access_wikiaves(), which generates the cookies argument this function requires.

Examples

if (interactive()) {
# Obtain fresh authentication cookies (only needs to be re-run once the
# cookies expire, roughly every hour):
cookies_live <- access_wikiaves()

# Query sound recordings for a species:
result <- query_wikiaves(
  species = "Procnias averano",
  format = "sound",
  cookies = cookies_live
)

# Query image records instead:
result_images <- query_wikiaves(
  species = "Procnias averano",
  format = "image",
  cookies = cookies_live
)
}