Species API

version v1

Introduction

Quick links

This API works against data kept in the GBIF Checklist Bank which taxonomically indexes all registered checklist datasets in the GBIF network.

For statistics on checklist datasets, you can refer to the dataset metrics section of the Registry API.

Internally we use a Java web service client for the consumption of these HTTP-based, RESTful web services. It may be of interest to those coding against the API, and can be found in the checklistbank-ws-client project.

Working with Name Usages

A name usage is the usage of a scientific name according to one particular Checklist including the GBIF Taxonomic Backbone which is just called nub in this API. Name usages from other checklists with names that also exist in the nub will have a taxonKey that points to the related usage in the backbone.

Resource URL Method Response Description Paging Parameters
/species GET NameUsage Page Lists all name usages across all checklists true language, datasetKey, sourceId, name
/species/root/{uuid|shortname} GET NameUsage Page Lists root usages of a checklist true
/species/{int} GET NameUsage Gets the single name usage false language
/species/{int}/verbatim GET VerbatimNameUsage Gets the verbatim name usage false
/species/{int}/name GET ParsedName Gets the parsed name for a name usage false
/species/{int}/parents GET NameUsage List Lists all parent usages for a name usage false language
/species/{int}/children GET NameUsage Page Lists all direct child usages for a name usage true language
/species/{int}/related GET NameUsage List Lists all related name usages in other checklists false language, datasetKey
/species/{int}/synonyms GET NameUsage Page Lists all synonyms for a name usage true language
/species/{int}/descriptions GET Description Page Lists all descriptions for a name usage true
/species/{int}/distributions GET Distribution Page Lists all distributions for a name usage true
/species/{int}/media GET Media Page Lists all media items for a name usage true
/species/{int}/references GET Reference Page Lists all references for a name usage true
/species/{int}/speciesProfiles GET SpeciesProfile Page Lists all species profiles for a name usage true
/species/{int}/vernacularNames GET VernacularName Page Lists all vernacular names for a name usage true
/species/{int}/typeSpecimens GET TypeSpecimen Page Lists all type specimens for a name usage true

Searching Names

GBIF provides 4 different ways of finding name usages. They differ in their matching behavior, response format and also the actual content covered.

Resource URL Method Response Description Paging Parameters
/species GET NameUsage Page Lists name usages across all or some checklists that share the exact same canonical name, i.e. without authorship. true language, datasetKey, sourceId, name
/species/match GET NameUsage Page Fuzzy matches scientific names against the GBIF Backbone Taxonomy with the optional classification provided. If a classification is provided and strict is not set to true, the default matching will also try to match against these if no direct match is found for the name parameter alone. false rank, name, strict, verbose, kingdom, phylum, class, order, family, genus
/species/search GET NameUsage Page Full text search of name usages covering the scientific and vernacular name, the species description, distribution and the entire classification across all name usages of all or some checklists. Results are ordered by relevance as this search usually returns a lot of results. true q, datasetKey, rank, highertaxonKey, status, isExtinct, habitat, threat, nameType, nomenclaturalStatus, hl, facet, facetMincount, facetMultiselect
/species/suggest GET NameUsage Page A quick and simple autocomplete service that returns up to 20 name usages by doing prefix matching against the scientific name. Results are ordered by relevance. false q, datasetKey, rank

Name Parser

GBIF exposes its java based name parser library through our API. The service takes one or a list of simple scientific name strings, parses each and returns a list of parsed names.

Resource URL Method Response Description Paging Parameters
/parser/name GET ParsedName List Parses a scientific name string and returns the ParsedName version of it. Accepts multiple parameters each with a single name. Make sure you url encode the names properly. false name
/parser/name POST ParsedName List Parse list of name strings supplied via one of the following media type encodings:
  • json array of name strings
  • plain/text content
  • multipart/form-data uploaded plain text file
All text files should be UTF8 encoded with one scientific name per line (please use \n unix new lines).
false name

Query parameters explained

The following parameters are for use exclusively with the Species API described above.

Parameter Description
class Optional class classification accepting a canonical name.
datasetKey Filters by the checklist dataset key (a uuid)
facet A 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. /search?facet=type&limit=0&facetMincount=10000 only shows the type value 'OCCURRENCE' because 'CHECKLIST' and 'METADATA' have counts less than 10000.
facetMultiselect Used in combination with the facet parameter. Set facetMultiselect=true to still return counts for values that are not currently filtered, e.g. /search?facet=type&limit=0&type=CHECKLIST&facetMultiselect=true still shows type values 'OCCURRENCE' and 'METADATA' even though type is being filtered by type=CHECKLIST
family Optional family classification accepting a canonical name.
genus Optional genus classification accepting a canonical name.
habitat Filters by the habitat, though currently only as boolean marine or not-marine (i.e. habitat=true means marine, false means not-marine)
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.
hl Set hl=true to highlight terms matching the query when in fulltext search fields. The highlight will be an emphasis tag of class 'gbifH1' e.g. /search?q=plant&hl=true. Fulltext search fields include: title, keyword, country, publishing country, publishing organization title, hosting organization title, and description. One additional full text field is searched which includes information from metadata documents, but the text of this field is not returned in the response.
isExtinct Filters by extinction status (a boolean, e.g. isExtinct=true)
kingdom Optional kingdom classification accepting a canonical name.
language default=en or use HTTP header for this
name A scientific name which can be either a case insensitive filter for a canonical namestring, e.g. 'Puma concolor', or an input to the name parser
nameType Filters by the name type as given in our NameType enum
nomenclaturalStatus Not yet implemented, but will eventually allow for filtering by a nomenclatural status enum
order Optional order classification accepting a canonical name.
phylum Optional phylum classification accepting a canonical name.
q Simple search parameter. The value for this parameter can be a simple word or a phrase. Wildcards can be added to the simple word parameters only, e.g. q=*puma*
rank Filters by taxonomic rank as given in our Rank enum
sourceId Filters by the source identifier
status Filters by the taxonomic status as given in our TaxonomicStatus enum
strict If true it (fuzzy) matches only the given name, but never a taxon in the upper classification
threat Not yet implemented, but will eventually allow for filtering by a threat status enum
verbose If true it shows alternative matches which were considered but then rejected