natserv (version 0.4.0)

ns_images: NatureServe image metadata

Description

NatureServe image metadata

Usage

ns_images(
  uid = NULL,
  scientificName = NULL,
  commonName = NULL,
  includeSynonyms = NULL,
  resolution = NULL,
  ITISNames = NULL,
  key = NULL,
  ...
)

Arguments

uid

(character) a species UID, e.g., ELEMENT_GLOBAL.2.100925

scientificName

(character) An asterisk () wildcarded species scientific name, e.g., 'Aquila chry'. Name matching is case-insensitive.

commonName

(character) An asterisk () wildcarded species common name, e.g., 'gEAGLE'. Name matching is case-insensitive.

includeSynonyms

(character) An optional parameter, relevant to scientific or common name queries, that indicates whether to include synonymous names in the query, as follows:

• Y (or y) - search the Primary and all synonymous Scientific and Common Names

• Any other value, or omitted - search only the Primary Scientific and Common Name fields

resolution

(character) An optional parameter that restricts output to images at a certain resolution. The value can be of one of the following.

• lowest - return only the lowest resolution version of images

• highest - return only the highest resolution version of images

• thumbnail - return only the version NatureServe deems the 'thumbnail image'

• web - return only the version NatureServe deems the 'web image'

The omission of this parameter leads to the return of metadata for images at all available resolutions.

ITISNames

(character) An optional parameter, relevant to scientific or common name queries, that will indicate whether to restrict queries to ITIS names, as follows.

• Y (or y) - query using ITIS names

• Any other value, or omitted - query using NatureServe names

NOTE: This parameter is a placeholder only and will not affect processing. At present, searching by ITIS names is not possible.

key

(character) API key. Required. See Authentication below for more.

...

Curl options passed on to HttpClient

Value

a list with terms and images

Authentication

Get an API key from NatureServe at https://services.natureserve.org/developer/index.jsp. You can pass your token in as an argument or store it one of two places:

• your .Rprofile file with an entry like options(NatureServeKey = "your-natureserve-key")

• your .Renviron file with an entry like NATURE_SERVE_KEY=your-natureserve-key

See Startup for information on how to create/find your .Rrofile and .Renviron files

Details

Note that the NatureServer servers apparently want Windows HTML encoding (Windows-1252), instead of UTF-8, so some accents and such may not work

References

https://services.natureserve.org/index.jsp

Examples

# NOT RUN {
# search by uid
ns_images(uid = 'ELEMENT_GLOBAL.2.100925')

# search by common name and resolutio thumbnail
(res <- ns_images(commonName = "*eagle", resolution = 'thumbnail'))

# search "Ruby*", all common names [in any language], and highest
# resolution only:
(res <- ns_images(commonName = "Ruby*", includeSynonyms = 'y',
  resolution = 'highest'))
# }