---
title: "Full text search over name usages"
method: GET
path: "/v1/species/search"
tags: ["Searching names"]
---

# Full text search over name usages

`GET /v1/species/search`

Full-text search of name usages covering the scientific and vernacular names, 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.

## Query parameters

- `datasetKey` string, uuid
- `constituentKey` string, uuid
- `rank` 'DOMAIN' | 'SUPERKINGDOM' | 'KINGDOM' | 'SUBKINGDOM' | 'INFRAKINGDOM' | 'SUPERPHYLUM' | 'PHYLUM' | 'SUBPHYLUM' | 'INFRAPHYLUM' | 'SUPERCLASS' | 'CLASS' | 'SUBCLASS' | 'INFRACLASS' | 'PARVCLASS' | 'SUPERLEGION' | 'LEGION' | 'SUBLEGION' | 'INFRALEGION' | 'SUPERCOHORT' | 'COHORT' | 'SUBCOHORT' | 'INFRACOHORT' | 'MAGNORDER' | 'SUPERORDER' | 'GRANDORDER' | 'ORDER' | 'SUBORDER' | 'INFRAORDER' | 'PARVORDER' | 'SUPERFAMILY' | 'FAMILY' | 'SUBFAMILY' | 'INFRAFAMILY' | 'SUPERTRIBE' | 'TRIBE' | 'SUBTRIBE' | 'INFRATRIBE' | 'SUPRAGENERIC_NAME' | 'GENUS' | 'SUBGENUS' | 'INFRAGENUS' | 'SECTION' | 'SUBSECTION' | 'SERIES' | 'SUBSERIES' | 'INFRAGENERIC_NAME' | 'SPECIES_AGGREGATE' | 'SPECIES' | 'INFRASPECIFIC_NAME' | 'GREX' | 'SUBSPECIES' | 'CULTIVAR_GROUP' | 'CONVARIETY' | 'INFRASUBSPECIFIC_NAME' | 'PROLES' | 'RACE' | 'NATIO' | 'ABERRATION' | 'MORPH' | 'VARIETY' | 'SUBVARIETY' | 'FORM' | 'SUBFORM' | 'PATHOVAR' | 'BIOVAR' | 'CHEMOVAR' | 'MORPHOVAR' | 'PHAGOVAR' | 'SEROVAR' | 'CHEMOFORM' | 'FORMA_SPECIALIS' | 'CULTIVAR' | 'STRAIN' | 'OTHER' | 'UNRANKED'
- `status` 'ACCEPTED' | 'DOUBTFUL' | 'SYNONYM' | 'HETEROTYPIC_SYNONYM' | 'HOMOTYPIC_SYNONYM' | 'PROPARTE_SYNONYM' | 'MISAPPLIED'
- `isExtinct` boolean
- `habitat` 'MARINE' | 'FRESHWATER' | 'TERRESTRIAL'
- `threat` 'EXTINCT' | 'EXTINCT_IN_THE_WILD' | 'REGIONALLY_EXTINCT' | 'CRITICALLY_ENDANGERED' | 'ENDANGERED' | 'VULNERABLE' | 'NEAR_THREATENED' | 'LEAST_CONCERN' | 'DATA_DEFICIENT' | 'NOT_APPLICABLE' | 'NOT_EVALUATED'
- `nameType` 'SCIENTIFIC' | 'VIRUS' | 'HYBRID' | 'INFORMAL' | 'CULTIVAR' | 'CANDIDATUS' | 'OTU' | 'DOUBTFUL' | 'PLACEHOLDER' | 'NO_NAME' | 'BLACKLISTED'
- `nomenclaturalStatus` 'LEGITIMATE' | 'VALIDLY_PUBLISHED' | 'NEW_COMBINATION' | 'REPLACEMENT' | 'CONSERVED' | 'PROTECTED' | 'CORRECTED' | 'ORIGINAL_COMBINATION' | 'NEW_SPECIES' | 'NEW_GENUS' | 'ALTERNATIVE' | 'OBSCURE' | 'CONSERVED_PROPOSED' | 'PROVISIONAL' | 'SUBNUDUM' | 'REJECTED_PROPOSED' | 'REJECTED_OUTRIGHT_PROPOSED' | 'DOUBTFUL' | 'AMBIGUOUS' | 'CONFUSED' | 'FORGOTTEN' | 'ABORTED' | 'ORTHOGRAPHIC_VARIANT' | 'SUPERFLUOUS' | 'NUDUM' | 'NULL_NAME' | 'SUPPRESSED' | 'REJECTED_OUTRIGHT' | 'REJECTED' | 'ILLEGITIMATE' | 'INVALID' | 'DENIED'
- `origin` 'SOURCE' | 'DENORMED_CLASSIFICATION' | 'VERBATIM_PARENT' | 'VERBATIM_ACCEPTED' | 'VERBATIM_BASIONYM' | 'PROPARTE' | 'AUTONYM' | 'IMPLICIT_NAME' | 'MISSING_ACCEPTED' | 'BASIONYM_PLACEHOLDER' | 'EX_AUTHOR_SYNONYM' | 'OTHER'
- `issue` 'PARENT_NAME_USAGE_ID_INVALID' | 'ACCEPTED_NAME_USAGE_ID_INVALID' | 'ORIGINAL_NAME_USAGE_ID_INVALID' | 'ACCEPTED_NAME_MISSING' | 'RANK_INVALID' | 'NOMENCLATURAL_STATUS_INVALID' | 'TAXONOMIC_STATUS_INVALID' | 'SCIENTIFIC_NAME_ASSEMBLED' | 'CHAINED_SYNOYM' | 'BASIONYM_AUTHOR_MISMATCH' | 'TAXONOMIC_STATUS_MISMATCH' | 'PARENT_CYCLE' | 'CLASSIFICATION_RANK_ORDER_INVALID' | 'CLASSIFICATION_NOT_APPLIED' | 'VERNACULAR_NAME_INVALID' | 'DESCRIPTION_INVALID' | 'DISTRIBUTION_INVALID' | 'SPECIES_PROFILE_INVALID' | 'MULTIMEDIA_INVALID' | 'BIB_REFERENCE_INVALID' | 'ALT_IDENTIFIER_INVALID' | 'BACKBONE_MATCH_NONE' | 'BACKBONE_MATCH_FUZZY' | 'BACKBONE_MATCH_AGGREGATE' | 'ACCEPTED_NAME_NOT_UNIQUE' | 'PARENT_NAME_NOT_UNIQUE' | 'ORIGINAL_NAME_NOT_UNIQUE' | 'RELATIONSHIP_MISSING' | 'ORIGINAL_NAME_DERIVED' | 'CONFLICTING_BASIONYM_COMBINATION' | 'NO_SPECIES' | 'NAME_PARENT_MISMATCH' | 'ORTHOGRAPHIC_VARIANT' | 'HOMONYM' | 'PUBLISHED_BEFORE_GENUS' | 'UNPARSABLE' | 'PARTIALLY_PARSABLE'
- `q` string
- `hl` boolean
- `limit` integer
- `offset` integer
- `facet` string[]
- `facetMincount` integer
- `facetMultiselect` boolean
- `facetLimit` integer
- `facetOffset` integer

## Response `200`

Name usages found

- SearchResponseNameUsageSearchResultNameUsageSearchParameter
  - `offset` integer — The offset of the results within all the search results. Subsequent pages can be retrieved by using `offset + count` as the new offset.
  - `limit` integer — The limit used. Note the limit returned may be lower than the limit requested.
  - `endOfRecords` boolean — True if this page of search results is the final page.
  - `count` integer — The total number of records returned by the search.
  - `results` NameUsageSearchResult[] — Search results.
    - `key` integer
    - `nameKey` integer
    - `datasetKey` string, uuid
    - `constituentKey` string, uuid
    - `nubKey` integer
    - `parentKey` integer
    - `parent` string
    - `acceptedKey` integer
    - `accepted` string
    - `basionymKey` integer
    - `basionym` string
    - `kingdom` string
    - `phylum` string
    - `order` string
    - `family` string
    - `genus` string
    - `subgenus` string
    - `species` string
    - `kingdomKey` integer
    - `phylumKey` integer
    - `classKey` integer
    - `orderKey` integer
    - `familyKey` integer
    - `genusKey` integer
    - `subgenusKey` integer
    - `speciesKey` integer
    - `scientificName` string
    - `canonicalName` string
    - `authorship` string
    - `publishedIn` string
    - `accordingTo` string
    - `nameType` 'SCIENTIFIC' | 'VIRUS' | 'HYBRID' | 'INFORMAL' | 'CULTIVAR' | 'CANDIDATUS' | 'OTU' | 'DOUBTFUL' | 'PLACEHOLDER' | 'NO_NAME' | 'BLACKLISTED'
    - `taxonomicStatus` 'ACCEPTED' | 'DOUBTFUL' | 'SYNONYM' | 'HETEROTYPIC_SYNONYM' | 'HOMOTYPIC_SYNONYM' | 'PROPARTE_SYNONYM' | 'MISAPPLIED'
    - `rank` 'DOMAIN' | 'SUPERKINGDOM' | 'KINGDOM' | 'SUBKINGDOM' | 'INFRAKINGDOM' | 'SUPERPHYLUM' | 'PHYLUM' | 'SUBPHYLUM' | 'INFRAPHYLUM' | 'SUPERCLASS' | 'CLASS' | 'SUBCLASS' | 'INFRACLASS' | 'PARVCLASS' | 'SUPERLEGION' | 'LEGION' | 'SUBLEGION' | 'INFRALEGION' | 'SUPERCOHORT' | 'COHORT' | 'SUBCOHORT' | 'INFRACOHORT' | 'MAGNORDER' | 'SUPERORDER' | 'GRANDORDER' | 'ORDER' | 'SUBORDER' | 'INFRAORDER' | 'PARVORDER' | 'SUPERFAMILY' | 'FAMILY' | 'SUBFAMILY' | 'INFRAFAMILY' | 'SUPERTRIBE' | 'TRIBE' | 'SUBTRIBE' | 'INFRATRIBE' | 'SUPRAGENERIC_NAME' | 'GENUS' | 'SUBGENUS' | 'INFRAGENUS' | 'SECTION' | 'SUBSECTION' | 'SERIES' | 'SUBSERIES' | 'INFRAGENERIC_NAME' | 'SPECIES_AGGREGATE' | 'SPECIES' | 'INFRASPECIFIC_NAME' | 'GREX' | 'SUBSPECIES' | 'CULTIVAR_GROUP' | 'CONVARIETY' | 'INFRASUBSPECIFIC_NAME' | 'PROLES' | 'RACE' | 'NATIO' | 'ABERRATION' | 'MORPH' | 'VARIETY' | 'SUBVARIETY' | 'FORM' | 'SUBFORM' | 'PATHOVAR' | 'BIOVAR' | 'CHEMOVAR' | 'MORPHOVAR' | 'PHAGOVAR' | 'SEROVAR' | 'CHEMOFORM' | 'FORMA_SPECIALIS' | 'CULTIVAR' | 'STRAIN' | 'OTHER' | 'UNRANKED'
    - `origin` 'SOURCE' | 'DENORMED_CLASSIFICATION' | 'VERBATIM_PARENT' | 'VERBATIM_ACCEPTED' | 'VERBATIM_BASIONYM' | 'PROPARTE' | 'AUTONYM' | 'IMPLICIT_NAME' | 'MISSING_ACCEPTED' | 'BASIONYM_PLACEHOLDER' | 'EX_AUTHOR_SYNONYM' | 'OTHER'
    - `numDescendants` integer
    - `numOccurrences` integer
    - `taxonID` string
    - `extinct` boolean
    - `habitats` string[]
    - `nomenclaturalStatus` string[]
    - `threatStatuses` string[]
    - `descriptions` Description[], required
      - `key` integer — A unique GBIF identifier for the description. This key is used in the table of contents to retrieve the detailed description.
      - `taxonKey` integer — The name usage “taxon“ key to which this species profile belongs.
      - `type` string — The type used to categorize paragraphs of a taxon description. See the [Description Type vocabulary](http://rs.gbif.org/vocabulary/gbif/descriptionType).
      - `language` 'abk' | 'aar' | 'afr' | 'aka' | 'sqi' | 'amh' | 'ara' | 'arg' | 'hye' | 'asm' | 'ava' | 'ave' | 'aym' | 'aze' | 'bam' | 'bak' | 'eus' | 'bel' | 'ben' | 'bih' | 'bis' | 'bos' | 'bre' | 'bul' | 'mya' | 'cat' | 'cha' | 'che' | 'zho' | 'chu' | 'chv' | 'cor' | 'cos' | 'cre' | 'hrv' | 'ces' | 'dan' | 'div' | 'nld' | 'dzo' | 'eng' | 'epo' | 'est' | 'ewe' | 'fao' | 'fij' | 'fin' | 'fra' | 'fry' | 'ful' | 'glg' | 'lug' | 'kat' | 'deu' | 'ell' | 'kal' | 'grn' | 'guj' | 'hat' | 'hau' | 'heb' | 'her' | 'hin' | 'hmo' | 'hun' | 'isl' | 'ido' | 'ibo' | 'ind' | 'ina' | 'ile' | 'iku' | 'ipk' | 'gle' | 'ita' | 'jpn' | 'jav' | 'kan' | 'kau' | 'kas' | 'kaz' | 'khm' | 'kik' | 'kin' | 'kir' | 'kom' | 'kon' | 'kor' | 'kur' | 'kua' | 'lao' | 'lat' | 'lav' | 'lim' | 'lin' | 'lit' | 'lub' | 'ltz' | 'mkd' | 'mlg' | 'msa' | 'mal' | 'mlt' | 'glv' | 'mri' | 'mar' | 'mah' | 'mol' | 'mon' | 'nau' | 'nav' | 'ndo' | 'nep' | 'nde' | 'sme' | 'nob' | 'nno' | 'nor' | 'nya' | 'oci' | 'oji' | 'ori' | 'orm' | 'oss' | 'pli' | 'pan' | 'fas' | 'pol' | 'por' | 'pus' | 'que' | 'roh' | 'ron' | 'run' | 'rus' | 'smo' | 'sag' | 'san' | 'srd' | 'gla' | 'srp' | 'sna' | 'iii' | 'snd' | 'sin' | 'slk' | 'slv' | 'som' | 'nbl' | 'sot' | 'spa' | 'sun' | 'swa' | 'ssw' | 'swe' | 'tgl' | 'tah' | 'tgk' | 'tam' | 'tat' | 'tel' | 'tha' | 'bod' | 'tir' | 'ton' | 'tso' | 'tsn' | 'tur' | 'tuk' | 'twi' | 'uig' | 'ukr' | 'urd' | 'uzb' | 'ven' | 'vie' | 'vol' | 'wln' | 'cym' | 'wol' | 'xho' | 'yid' | 'yor' | 'zha' | 'zul' | '' — ISO 639-1 language code used for the description.
      - `description` string — Any descriptive, free text matching the category given as dc:type. The text should be either plain text or HTML.
      - `source` string — Bibliographic citation referencing a source for the description.
      - `sourceTaxonKey` integer — The name usage key of the taxon in the checklist including this description.
      - `creator` string — The author(s) of the textual information provided for a description.
      - `contributor` string — An entity responsible for making contributions to the textual information provided for a description.
      - `license` string — Official permission to do something with the resource.
    - `vernacularNames` VernacularName[], required
      - `taxonKey` integer — The name usage “taxon“ key to which this vernacular name belongs.
      - `vernacularName` string, required — A common or vernacular name.
      - `language` 'abk' | 'aar' | 'afr' | 'aka' | 'sqi' | 'amh' | 'ara' | 'arg' | 'hye' | 'asm' | 'ava' | 'ave' | 'aym' | 'aze' | 'bam' | 'bak' | 'eus' | 'bel' | 'ben' | 'bih' | 'bis' | 'bos' | 'bre' | 'bul' | 'mya' | 'cat' | 'cha' | 'che' | 'zho' | 'chu' | 'chv' | 'cor' | 'cos' | 'cre' | 'hrv' | 'ces' | 'dan' | 'div' | 'nld' | 'dzo' | 'eng' | 'epo' | 'est' | 'ewe' | 'fao' | 'fij' | 'fin' | 'fra' | 'fry' | 'ful' | 'glg' | 'lug' | 'kat' | 'deu' | 'ell' | 'kal' | 'grn' | 'guj' | 'hat' | 'hau' | 'heb' | 'her' | 'hin' | 'hmo' | 'hun' | 'isl' | 'ido' | 'ibo' | 'ind' | 'ina' | 'ile' | 'iku' | 'ipk' | 'gle' | 'ita' | 'jpn' | 'jav' | 'kan' | 'kau' | 'kas' | 'kaz' | 'khm' | 'kik' | 'kin' | 'kir' | 'kom' | 'kon' | 'kor' | 'kur' | 'kua' | 'lao' | 'lat' | 'lav' | 'lim' | 'lin' | 'lit' | 'lub' | 'ltz' | 'mkd' | 'mlg' | 'msa' | 'mal' | 'mlt' | 'glv' | 'mri' | 'mar' | 'mah' | 'mol' | 'mon' | 'nau' | 'nav' | 'ndo' | 'nep' | 'nde' | 'sme' | 'nob' | 'nno' | 'nor' | 'nya' | 'oci' | 'oji' | 'ori' | 'orm' | 'oss' | 'pli' | 'pan' | 'fas' | 'pol' | 'por' | 'pus' | 'que' | 'roh' | 'ron' | 'run' | 'rus' | 'smo' | 'sag' | 'san' | 'srd' | 'gla' | 'srp' | 'sna' | 'iii' | 'snd' | 'sin' | 'slk' | 'slv' | 'som' | 'nbl' | 'sot' | 'spa' | 'sun' | 'swa' | 'ssw' | 'swe' | 'tgl' | 'tah' | 'tgk' | 'tam' | 'tat' | 'tel' | 'tha' | 'bod' | 'tir' | 'ton' | 'tso' | 'tsn' | 'tur' | 'tuk' | 'twi' | 'uig' | 'ukr' | 'urd' | 'uzb' | 'ven' | 'vie' | 'vol' | 'wln' | 'cym' | 'wol' | 'xho' | 'yid' | 'yor' | 'zha' | 'zul' | '' — The language (from ISO 639-1) of the vernacular name.
      - `lifeStage` 'ZYGOTE' | 'EMRYO' | 'LARVA' | 'JUVENILE' | 'ADULT' | 'SPOROPHYTE' | 'SPORE' | 'GAMETOPHYTE' | 'GAMETE' | 'PUPA' — The age class or life stage of the species for which the vernacular name applies. For example, a juvenile *Anser anser* is called a “gosling“.
      - `sex` 'NONE' | 'MALE' | 'FEMALE' | 'HERMAPHRODITE' — The sex of the biological individual(s) represented in the Occurrence. For definitions, see the [GBIF sex vocabulary](http://rs.gbif.org/vocabulary/gbif/sex)
      - `country` 'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BQ' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CD' | 'CG' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CW' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GG' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IM' | 'IL' | 'IT' | 'JM' | 'JP' | 'JE' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KP' | 'KR' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MK' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'ME' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'BL' | 'SH' | 'KN' | 'LC' | 'MF' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'RS' | 'SC' | 'SL' | 'SG' | 'SX' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'SS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'US' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW' | 'AA' | 'XK' | 'XZ' | 'ZZ' — The country or area in which the vernacular name is used.
      - `area` string — The area where the vernacular name is used.
      - `source` string — Bibliographic citation referencing a source where the vernacular name refers to the cited species.
      - `sourceTaxonKey` integer — The name usage key of the taxon in the checklist including this vernacular name.
      - `preferred` boolean — This term is true if the source citing the use of this vernacular name indicates the usage has some preference or specific standing over other possible vernacular names used for the species.
      - `plural` boolean — True if the vernacular name refers to a plural form of the name.
    - `higherClassificationMap` object, required
    - `synonym` boolean
    - `class` string
  - `facets` FacetNameUsageSearchParameter[] — The resulting facets of a search operation. The list can be empty if no facets were requested. If there are no values for a facet, it will not be included in the list, i.e.: a facet should have at least 1 occurrence.
    - `field` 'DATASET_KEY' | 'CONSTITUENT_KEY' | 'RANK' | 'HIGHERTAXON_KEY' | 'STATUS' | 'IS_EXTINCT' | 'HABITAT' | 'THREAT' | 'NOMENCLATURAL_STATUS' | 'NAME_TYPE' | 'ISSUE' | 'ORIGIN'
    - `counts` Count[]
      - `name` string
      - `count` integer

## Other responses

- `400` — Invalid query
- `404` — Name usage not found

---

[API](https://skmtc.net/gbif/apis/species-api.md) · [All operations](https://skmtc.net/gbif/apis/species-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gbif/species-api/revisions/156fd5bac927/schema)