rgbif (version 0.9.6)

name_usage: Lookup details for specific names in all taxonomies in GBIF.

Description

Lookup details for specific names in all taxonomies in GBIF.

Usage

name_usage(key = NULL, name = NULL, data = "all", language = NULL, datasetKey = NULL, uuid = NULL, sourceId = NULL, rank = NULL, shortname = NULL, start = NULL, limit = 100, return = "all", ...)

Arguments

key

(numeric) A GBIF key for a taxon

name

(character) Filters by a case insensitive, canonical namestring, e.g. 'Puma concolor'

data

(character) Specify an option to select what data is returned. See Description below.

language

(character) Language, default is english

datasetKey

(character) Filters by the dataset's key (a uuid)

uuid

(character) A uuid for a dataset. Should give exact same results as datasetKey.

sourceId

(numeric) Filters by the source identifier. Not used right now.

rank

(character) Taxonomic rank. Filters by taxonomic rank as one of: CLASS, CULTIVAR, CULTIVAR_GROUP, DOMAIN, FAMILY, FORM, GENUS, INFORMAL, INFRAGENERIC_NAME, INFRAORDER, INFRASPECIFIC_NAME, INFRASUBSPECIFIC_NAME, KINGDOM, ORDER, PHYLUM, SECTION, SERIES, SPECIES, STRAIN, SUBCLASS, SUBFAMILY, SUBFORM, SUBGENUS, SUBKINGDOM, SUBORDER, SUBPHYLUM, SUBSECTION, SUBSERIES, SUBSPECIES, SUBTRIBE, SUBVARIETY, SUPERCLASS, SUPERFAMILY, SUPERORDER, SUPERPHYLUM, SUPRAGENERIC_NAME, TRIBE, UNRANKED, VARIETY

shortname

(character) A short name..need more info on this?

start

Record number to start at. Default: 0. Use in combination with limit to page through results.

limit

Number of records to return. Default: 100. Maximum: 1000.

return

One of data, meta, or all. If data, a data.frame with the data. meta returns the metadata for the entire call. all gives all data back in a list.

...

Further named parameters, such as query, path, etc, passed on to modify_url within GET call. Unnamed parameters will be combined with config.

Value

A list of length two. The first element is metadata. The second is a data.frame

Details

This service uses fuzzy lookup so that you can put in partial names and you should get back those things that match. See examples below.

This function is different from name_lookup in that that function searches for names. This function encompasses a bunch of API endpoints, most of which require that you already have a taxon key, but there is one endpoint that allows name searches (see examples below).

Note that data="verbatim" hasn't been working.

Options for the data parameter are: 'all', 'verbatim', 'name', 'parents', 'children', 'related', 'synonyms', 'descriptions','distributions', 'media', 'references', 'speciesProfiles', 'vernacularNames', 'typeSpecimens', 'root'

This function used to be vectorized with respect to the data parameter, where you could pass in multiple values and the function internally loops over each option making separate requests. This has been removed. You can still loop over many options for the data parameter, just use an lapply family function, or a for loop, etc.

References

http://www.gbif.org/developer/species#nameUsages

Examples

## Not run: 
# # A single name usage
# name_usage(key=1)
# 
# # Name usage for a taxonomic name
# name_usage(name='Puma', rank="GENUS")
# 
# # All name usages
# name_usage()
# 
# # References for a name usage
# name_usage(key=2435099, data='references')
# 
# # Species profiles, descriptions
# name_usage(key=3119195, data='speciesProfiles')
# name_usage(key=3119195, data='descriptions')
# name_usage(key=2435099, data='children')
# 
# # Vernacular names for a name usage
# name_usage(key=3119195, data='vernacularNames')
# 
# # Limit number of results returned
# name_usage(key=3119195, data='vernacularNames', limit=3)
# 
# # Search for names by dataset with datasetKey parameter
# name_usage(datasetKey="d7dddbf4-2cf0-4f39-9b2a-bb099caae36c")
# 
# # Search for a particular language
# name_usage(key=3119195, language="FRENCH", data='vernacularNames')
# 
# # Pass on httr options
# ## here, print progress, notice the progress bar
# library('httr')
# # res <- name_usage(name='Puma concolor', limit=300, config=progress())
# ## End(Not run)