Search Species Taxonomy
gbif_search_speciesSearch or browse the GBIF backbone taxonomy. Accepts scientific name fragments, rank filters, and higher-taxon constraints. Useful for exploring what species exist under a higher taxon (e.g., "list all families of Coleoptera"), for simple name-fragment searches, or when gbif_match_species returns too narrow a result. kingdom, family, and genus scope the browse to a higher taxon: each is resolved to its backbone key before the search runs, so the narrowest one supplied is what scopes, an alternative name resolves to the taxon it is a synonym of, and a name that matches no backbone taxon at that rank fails rather than returning the whole index. Names are capitalized as GBIF writes them ("Paridae", not "paridae") and are matched exactly, not fuzzily. Paginated — use limit and offset to walk through results.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Name fragment to search for. Matches scientific and vernacular names. Omit the field to browse without a name term — a blank or whitespace-only value is rejected rather than sent, because GBIF answers a blank one with the whole 46,623,754-name index and a whitespace-only one with nothing, and neither is the search a caller who filled the field was asking for. | |
| rank | No | Filter to a specific taxonomic rank. | |
| genus | No | Scope the search to a genus, by name — "Quercus", "Parus". Resolved to its backbone key before the search runs, and it is the narrowest of the three, so it is what scopes when kingdom or family is supplied too. Matched exactly and capitalized as GBIF writes it; a name shared across kingdoms ("Prunella", "Oenanthe") resolves only when kingdom is supplied with it. Omit the field to browse every genus; a blank or whitespace-only value is rejected rather than dropped. | |
| limit | No | Number of records to return (default 20, max 1000). | |
| family | No | Scope the search to a family, by name — "Paridae", "Fagaceae". Resolved to its backbone key before the search runs, so an alternative family name lands on the taxon it is a synonym of ("Compositae" scopes to Asteraceae). Matched exactly and capitalized as GBIF writes it; a name that is not a backbone family fails rather than being ignored. Supplied with genus, it must be that genus's own family. Omit the field to browse every family; a blank or whitespace-only value is rejected rather than dropped. | |
| offset | No | Pagination offset. | |
| kingdom | No | Scope the search to a kingdom, by name — "Animalia", "Plantae", "Fungi". Resolved to its backbone key before the search runs, and matched exactly: capitalize it as GBIF writes it, since "animalia" resolves to nothing. Supplied alongside family or genus it disambiguates that name rather than scoping on its own — "Prunella" alone names both a bird genus and a plant genus and resolves to neither. Omit the field to browse every kingdom; a blank or whitespace-only value is rejected rather than dropped. | |
| isExtinct | No | Filter to extinct (true) or extant (false) taxa. | |
| datasetKey | No | Scope to a specific checklist dataset UUID (8-4-4-4-12 hex). Omit the field to search the GBIF backbone — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered backbone result. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| taxa | No | Matching taxa. | |
| error | No | Present when the call failed. Absent on success. | |
| limit | No | Records returned in this page. | |
| notice | No | Guidance when results are empty or paging overshot. Absent on successful result pages. | |
| offset | No | Current pagination offset. | |
| taxonScope | No | The higher-taxon scope actually applied — which of kingdom, family, or genus scoped the search, the backbone taxon its name resolved to, and that taxon key. Absent when none of the three was supplied. | |
| totalCount | No | Total matches before pagination. | |
| endOfRecords | No | True when there are no more results after this page. |