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.
Faceting: If facet=FALSE
or left to the default (NULL), no faceting
is done. And therefore, all parameters with facet in their name are
ignored (facetOnly, facetMincount, facetMultiselect).
name_lookup(query = NULL, rank = NULL, higherTaxonKey = NULL, status = NULL, isExtinct = NULL, habitat = NULL, nameType = NULL, datasetKey = NULL, origin = NULL, nomenclaturalStatus = NULL, limit = 100, start = 0, facet = NULL, facetMincount = NULL, facetMultiselect = NULL, type = NULL, hl = NULL, verbose = FALSE, return = "all", curlopts = list())
query | Query term(s) for full text search. |
---|---|
rank | 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 |
higherTaxonKey | Filters by any of the higher Linnean rank keys. Note this is within the respective checklist and not searching nub keys across all checklists. This parameter accepts many inputs in a vector ( passed in the same request). |
status | Filters by the taxonomic status as one of:
|
isExtinct | (logical) Filters by extinction status (e.g.
|
habitat | (character) Filters by habitat. One of: marine, freshwater, or terrestrial |
nameType | Filters by the name type as one of:
|
datasetKey | Filters by the dataset's key (a uuid) |
origin | (character) Filters by origin. One of:
|
nomenclaturalStatus | Not yet implemented, but will eventually allow for filtering by a nomenclatural status enum |
limit | Number of records to return. Hard maximum limit set by GBIF API: 99999. |
start | Record number to start at. Default: 0. |
facet | A vector/list of facet names used to retrieve the 100 most frequent values for a field. Allowed facets are: datasetKey, higherTaxonKey, rank, status, isExtinct, habitat, and nameType. Additionally threat and nomenclaturalStatus are legal values but not yet implemented, so data will not yet be returned for them. |
facetMincount | Used in combination with the facet parameter. Set facetMincount=# to exclude facets with a count less than #, e.g. http://bit.ly/1bMdByP only shows the type value 'ACCEPTED' because the other statuses have counts less than 7,000,000 |
facetMultiselect | (logical) Used in combination with the facet
parameter. Set |
type | Type of name. One of occurrence, checklist, or metadata. |
hl | (logical) Set |
verbose | (logical) If |
return | One of data, meta, facets, hierarchy, names or all. If data, a
data.frame with the data. facets returns the facets, if |
curlopts | list of named curl options passed on to
|
A list of length five:
metadata
data: either a data.frame (verbose=FALSE
, default) or a list (verbose=TRUE
).
facets
hierarchies
names
Some parameters can take many inputs, and treated as 'OR' (e.g., a or b or c). The following take many inputs:
rank
higherTaxonKey
status
habitat
nameType
datasetKey
origin
see also many-values
http://www.gbif.org/developer/species#searching
# NOT RUN { # Look up names like mammalia name_lookup(query='mammalia', limit = 20) # Start with an offset name_lookup(query='mammalia', limit=1) name_lookup(query='mammalia', limit=1, start=2) # large requests (paging is internally implemented). # hard maximum limit set by GBIF API: 99999 # name_lookup(query = "Carnivora", limit = 10000) # Get all data and parse it, removing descriptions which can be quite long out <- name_lookup('Helianthus annuus', rank="species", verbose=TRUE) lapply(out$data, function(x) { x[!names(x) %in% c("descriptions","descriptionsSerialized")] }) # Search for a genus, returning just data name_lookup(query='Cnaemidophorus', rank="genus", return="data") # Just metadata name_lookup(query='Cnaemidophorus', rank="genus", return="meta") # Just hierarchies name_lookup(query='Cnaemidophorus', rank="genus", return="hierarchy") # Just vernacular (common) names name_lookup(query='Cnaemidophorus', rank="genus", return="names") # Limit records to certain number name_lookup('Helianthus annuus', rank="species", limit=2) # Query by habitat name_lookup(habitat = "terrestrial", limit=2) name_lookup(habitat = "marine", limit=2) name_lookup(habitat = "freshwater", limit=2) # Using faceting name_lookup(facet='status', limit=0, facetMincount='70000') name_lookup(facet=c('status','higherTaxonKey'), limit=0, facetMincount='700000') name_lookup(facet='nameType', limit=0) name_lookup(facet='habitat', limit=0) name_lookup(facet='datasetKey', limit=0) name_lookup(facet='rank', limit=0) name_lookup(facet='isExtinct', limit=0) name_lookup(isExtinct=TRUE, limit=0) # text highlighting ## turn on highlighting res <- name_lookup(query='canada', hl=TRUE, limit=5) res$data name_lookup(query='canada', hl=TRUE, limit=45, return='data') ## and you can pass the output to gbif_names() function res <- name_lookup(query='canada', hl=TRUE, limit=5) gbif_names(res) # Lookup by datasetKey (set up sufficient high limit, API maximum: 99999) # name_lookup(datasetKey='3f8a1297-3259-4700-91fc-acc4170b27ce', # limit = 50000) # Some parameters accept many inputs, treated as OR name_lookup(rank = c("family", "genus")) name_lookup(higherTaxonKey = c("119", "120", "121", "204")) name_lookup(status = c("misapplied", "synonym"))$data name_lookup(habitat = c("marine", "terrestrial")) name_lookup(nameType = c("cultivar", "doubtful")) name_lookup(datasetKey = c("73605f3a-af85-4ade-bbc5-522bfb90d847", "d7c60346-44b6-400d-ba27-8d3fbeffc8a5")) name_lookup(datasetKey = "289244ee-e1c1-49aa-b2d7-d379391ce265", origin = c("SOURCE", "DENORMED_CLASSIFICATION")) # Pass on curl options name_lookup(query='Cnaemidophorus', rank="genus", curlopts = list(verbose = TRUE)) # }