Species API
https://api.gbif.org/v1/
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 JSON web services.
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 | true | language, datasetKey |
| /species/{int}/synonyms | GET | NameUsage Page | Lists all synonyms for a name usage | true | language |
| /species/{int}/combinations | GET | NameUsage List | Lists all (re)combinations of a given basionym, excluding the basionym itself. | false | |
| /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, see also limitations | 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, issue, 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:
|
false | name |
Query parameters explained
The following parameters are for use exclusively with the Occurrence 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, nomenclaturalStatus, isExtinct, habitat, threat and nameType. |
| 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. Currently only 3 major biomes are accepted in our Habitat enum |
| 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) |
| issue | A specific indexing issue as defined in our NameUsageIssue enum |
| kingdom | Optional kingdom classification accepting a canonical name. |
| language | Language for vernacular names, given as an ISO 639-1 two-letter code from our |
| 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 full text search parameter. The value for this parameter can be a simple word or a phrase. Wildcards are not supported |
| 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 | Filters by the taxonomic threat status as given in our ThreatStatus enum |
| verbose | If true it shows alternative matches which were considered but then rejected |