Match Species Name
gbif_match_speciesRead-onlyIdempotent
Match a scientific name against the GBIF backbone taxonomy. Returns the best-matching taxon with full classification and a confidence score (0–100). This is the mandatory first step for any GBIF workflow — it returns the backbone taxonKey required by gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets. When the queried name is a synonym, taxonKey is the accepted taxon it resolves to and matchedTaxonKey carries the synonym's own key; occurrence counts differ sharply between the two, so pass taxonKey. Below confidence 80, the match should be reviewed. matchType NONE means no usable match was found — try removing the strict flag or broadening the name.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Scientific name to match. Examples: "Parus major", "Agaricus bisporus", "Homo sapiens". Fuzzy matching handles minor spelling variations. Common names are not supported — use gbif_search_species for vernacular name searches. | |
| rank | No | Expected taxonomic rank. Use to avoid matching a genus when you expect a species. | |
| strict | No | When true, only return an exact match. When false (default), GBIF applies fuzzy matching — useful for minor spelling variations and abbreviated names. | |
| kingdom | No | Narrow the match to a specific kingdom (e.g., "Animalia", "Plantae", "Fungi") to disambiguate names that appear in multiple kingdoms. Omit the field to match against the whole backbone — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the undisambiguated match, which is indistinguishable from a match that honored the kingdom. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rank | No | Taxonomic rank of the matched taxon. | |
| class | No | Class of the matched taxon. | |
| error | No | Present when the call failed. Absent on success. | |
| genus | No | Genus of the matched taxon. | |
| order | No | Order of the matched taxon. | |
| family | No | Family of the matched taxon. | |
| notice | No | Guidance when the queried name was a synonym and taxonKey was resolved to the accepted taxon. Absent when the matched name is already the accepted one. | |
| phylum | No | Phylum of the matched taxon. | |
| status | No | Taxonomic status: ACCEPTED, SYNONYM, or DOUBTFUL. | |
| kingdom | No | Kingdom of the matched taxon. | |
| species | No | Species canonical name of the matched taxon. | |
| classKey | No | Backbone taxon key for the class. | |
| genusKey | No | Backbone taxon key for the genus. | |
| orderKey | No | Backbone taxon key for the order. | |
| taxonKey | No | GBIF backbone taxon key to pass to downstream tools. The accepted taxon's key when the queried name is a synonym, otherwise the matched taxon's own key. | |
| familyKey | No | Backbone taxon key for the family. | |
| matchType | No | EXACT, FUZZY, HIGHERRANK, or NONE. NONE means no usable match. | |
| phylumKey | No | Backbone taxon key for the phylum. | |
| confidence | No | Match confidence score 0–100. Below 80 warrants review. | |
| kingdomKey | No | Backbone taxon key for the kingdom. | |
| speciesKey | No | Backbone taxon key for the species. | |
| canonicalName | No | Scientific name without authorship. | |
| scientificName | No | Full scientific name with authorship. | |
| matchedTaxonKey | No | Backbone key of the name that actually matched. Present only when it differs from taxonKey — that is, when a synonym was resolved to its accepted taxon. |