Search GBIF species taxonomy, occurrence records, datasets, and publishers.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Resolve up to 50 scientific names to GBIF backbone taxon keys in one call — the batch counterpart to gbif_match_species for checklist, inventory, and species-list workflows that would otherwise need one round trip per name. Each name is matched independently and results are returned in input order, one entry per processed name. By default, an oversized batch processes the first 50 and returns the remainder in unprocessedNames. A name with no backbone match yields matchType NONE (no taxonKey) instead of failing the batch; a per-name lookup failure yields matchType ERROR carrying that name's error message and, when the failure was classified, a machine-readable reason — the rest of the batch is unaffected, and the call as a whole still succeeds. When a queried name is a synonym, taxonKey is the accepted taxon it resolves to and matchedTaxonKey carries the synonym's own key. Common names are not supported — use gbif_search_species for vernacular searches. Below confidence 80, review the match.
Scientific names to match against the GBIF backbone. Up to 50 are matched in parallel; additional names are returned in unprocessedNames when read-limit clamping is enabled (default). Every submitted name must be valid.
When true, require an exact match for every name (no fuzzy matching). When false (default), GBIF applies fuzzy matching to tolerate minor misspellings.
Tool list last changed Oct 25, 2026.
Resolve up to 50 scientific names to GBIF backbone taxon keys in one call — the batch counterpart to gbif_match_species for checklist, inventory, and species-list workflows that would otherwise need one round trip per name. Each name is matched independently and results are returned in input order, one entry per processed name. By default, an oversized batch processes the first 50 and returns the remainder in unprocessedNames. A name with no backbone match yields matchType NONE (no taxonKey) instead of failing the batch; a per-name lookup failure yields matchType ERROR carrying that name's error message and, when the failure was classified, a machine-readable reason — the rest of the batch is unaffected, and the call as a whole still succeeds. When a queried name is a synonym, taxonKey is the accepted taxon it resolves to and matchedTaxonKey carries the synonym's own key. Common names are not supported — use gbif_search_species for vernacular searches. Below confidence 80, review the match.
| Argument | Type | Description |
|---|---|---|
| names* | array | Scientific names to match against the GBIF backbone. Up to 50 are matched in parallel; additional names are returned in unprocessedNames when read-limit clamping is enabled (default). Every submitted name must be valid. |
| strict | boolean | When true, require an exact match for every name (no fuzzy matching). When false (default), GBIF applies fuzzy matching to tolerate minor misspellings. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"names"
],
"properties": {
"names": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "A scientific name to match, e.g. \"Panthera leo\"."
},
"minItems": 1,
"description": "Scientific names to match against the GBIF backbone. Up to 50 are matched in parallel; additional names are returned in unprocessedNames when read-limit clamping is enabled (default). Every submitted name must be valid."
},
"strict": {
"type": "boolean",
"default": false,
"description": "When true, require an exact match for every name (no fuzzy matching). When false (default), GBIF applies fuzzy matching to tolerate minor misspellings."
}
},
"additionalProperties": false
}Count occurrences matching a taxon + location filter without fetching records. Use for quick totals ("how many Aves records in Sweden?") or before deciding whether to paginate a full search. Accepts taxonKey, country (uppercase ISO 3166-1 alpha-2), publishingCountry, stateProvince, scientificName, spatial ranges and geometry (intersected), month, basisOfRecord, hasCoordinate (alias isGeoreferenced), isInCluster, coordinateUncertaintyInMeters, datasetKey, year, occurrenceStatus, and iucnRedListCategory. Counts sightings only by default, matching gbif_search_occurrences — GBIF also indexes absence records, and for some taxa they are the overwhelming majority. A count above 100,001 is the signal to partition rather than page: gbif_search_occurrences cannot reach past that offset, so split the query by DATASET_KEY via gbif_occurrence_facets and search each dataset separately.
| Argument | Type | Description |
|---|---|---|
| year | string | Year or year range (e.g., "2024" or "2020,2024"). Both endpoints inclusive. Omit the field to count across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total. |
| month | number | Calendar month (1–12), matching the occurrence search filter. |
| country | string | ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., "GB", "US"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know ("XX") is rejected upstream by name. |
Fetch full dataset metadata by UUID key — title, description, citation text, contacts, license, DOI, record count, numConstituents (sub-datasets), and temporal/geographic coverage. Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail. Contacts are capped by contactLimit (default 10); contactsTotal and contactsReturned report the full count.
| Argument | Type | Description |
|---|---|---|
| datasetKey* | string | Dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record. |
| contactLimit | integer | Maximum number of contacts to include (default 10, max 100). Set to 0 to omit contact detail while still reporting contactsTotal — useful when citation, license, and record count are all you need from a high-contact dataset like eBird. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"datasetKey"
],
"properties": {
"datasetKey": {
"type": "string",
"description": "Dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record."
},
"contactLimit": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Maximum number of contacts to include (default 10, max 100). Set to 0 to omit contact detail while still reporting contactsTotal — useful when citation, license, and record count are all you need from a high-contact dataset like eBird."
}
},
"additionalProperties": false
}Fetch a single occurrence record by its GBIF occurrence key. Returns the complete Darwin Core record — all coordinates, administrative geography (GADM levels 0–3), dates, collections metadata, collector identifiers, conservation status, media links, and quality issue flags. Check occurrenceStatus before reading the record as a sighting: ABSENT means a survey looked for the taxon and did not find it. Use the occurrence key from gbif_search_occurrences results.
| Argument | Type | Description |
|---|---|---|
| occurrenceKey* | number | GBIF occurrence key from gbif_search_occurrences results. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"occurrenceKey"
],
"properties": {
"occurrenceKey": {
"type": "number",
"description": "GBIF occurrence key from gbif_search_occurrences results."
}
},
"additionalProperties": false
}Fetch a single backbone taxon by its GBIF taxon key. Returns full classification, authorship, taxonomic status, vernacular name, descendant count, and publication reference. Use after gbif_match_species when you need the complete record rather than the match summary. When taxonomicStatus is SYNONYM, acceptedKey and accepted fields identify the accepted taxon. The extinct field is absent (not false) on most records — only present on explicitly flagged taxa.
| Argument | Type | Description |
|---|---|---|
| taxonKey* | number | GBIF backbone taxon key from gbif_match_species or another taxonomy tool. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"taxonKey"
],
"properties": {
"taxonKey": {
"type": "number",
"description": "GBIF backbone taxon key from gbif_match_species or another taxonomy tool."
}
},
"additionalProperties": false
}List direct children of a backbone taxon — genera within a family, species within a genus, subspecies within a species. Paginated. Use gbif_match_species to get the taxonKey first, then iterate with offset for large groups.
| Argument | Type | Description |
|---|---|---|
| limit | number | Number of children to return (default 20, max 1000). |
| offset | number | Pagination offset. |
| taxonKey* | number | GBIF backbone taxon key from gbif_match_species or another taxonomy tool. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"taxonKey"
],
"properties": {
"limit": {
"type": "number",
"default": 20,
"minimum": 1,
"description": "Number of children to return (default 20, max 1000)."
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Pagination offset."
},
"taxonKey": {
"type": "number",
"description": "GBIF backbone taxon key from gbif_match_species or another taxonomy tool."
}
},
"additionalProperties": false
}Return the parent chain for a taxon — from kingdom (or domain) down to the immediate parent of the queried taxon — as an ordered array. Each entry has its rank, canonical name, and taxon key. The array is returned root-first (kingdom → phylum → class → … → immediate parent of the queried taxon); the queried taxon itself is not included — call gbif_get_species for its own record. Useful for building taxonomic trees or understanding placement without navigating the backbone level-by-level.
| Argument | Type | Description |
|---|---|---|
| taxonKey* | number | GBIF backbone taxon key from gbif_match_species or another taxonomy tool. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"taxonKey"
],
"properties": {
"taxonKey": {
"type": "number",
"description": "GBIF backbone taxon key from gbif_match_species or another taxonomy tool."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| name* | string | 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 | string | Expected taxonomic rank. Use to avoid matching a genus when you expect a species. |
| strict | boolean | When true, only return an exact match. When false (default), GBIF applies fuzzy matching — useful for minor spelling variations and abbreviated names. |
| kingdom | string | 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. |
Aggregate occurrence counts across a dimension (COUNTRY, STATE_PROVINCE, YEAR, BASIS_OF_RECORD, DATASET_KEY, KINGDOM_KEY, etc.). Returns one page of facet values ranked by count descending — the top facetLimit at facetOffset 0, a later slice of the same ranking past that. No record payloads returned. Core tool for distribution analysis and trend queries: "which countries have the most records for this species?", "how has observation volume changed since 2010?". Scope the aggregation with taxonKey, country (uppercase ISO 3166-1 alpha-2), publishingCountry, stateProvince, year, scientificName, latitude/longitude ranges, month, hasCoordinate, isInCluster, coordinateUncertaintyInMeters, geometry (all spatial filters intersect), basisOfRecord, datasetKey, occurrenceStatus, or iucnRedListCategory filters. Also the way to split a result set too large for gbif_search_occurrences to page (offset+limit caps at 100,001): facet by DATASET_KEY, then search each datasetKey on its own. Aggregates sightings only by default, matching gbif_search_occurrences and gbif_count_occurrences; to measure the presence/absence split itself, pass facet OCCURRENCE_STATUS with occurrenceStatus ANY.
| Argument | Type | Description |
|---|---|---|
| year | string | Year or year range (e.g., "2020,2024") to scope the aggregation. Both endpoints inclusive. Omit the field to aggregate across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation. |
| facet* | string | Dimension to aggregate by (e.g., COUNTRY, YEAR, BASIS_OF_RECORD, SPECIES_KEY, OCCURRENCE_STATUS, IUCN_RED_LIST_CATEGORY). DATASET_KEY is the first cut when a result set is too large to page: every occurrence carries exactly one datasetKey, so its buckets cover totalOccurrences with no gap or overlap. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free second cuts for a dataset bucket still too large; both have a matching filter on the occurrence tools. A dimension a record can lack drops that record from every bucket: YEAR loses undated records; MONTH, STATE_PROVINCE, and SPECIES_KEY lose records lacking that dimension, even where the occurrence tools can filter on it. Sums are comparable only across the same occurrenceStatus scope. |
Search GBIF datasets by keyword, type, publishing country (uppercase ISO 3166-1 alpha-2), publishing organization, or hosting organization. The two organization filters answer different questions — publishingOrg matches the organization whose data it is, hostingOrg the organization whose installation serves it — and an organization key from gbif_search_publishers usually wants publishingOrg. Returns dataset title, description, license, record count, and DOI. Use to find the source dataset behind a set of records, or to explore what data collections are available for a taxon, country, or organization.
| Argument | Type | Description |
|---|---|---|
| q | string | Free-text search across dataset title and description. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because GBIF answers a blank one with all 123,527 indexed datasets and a whitespace-only one with none, and neither is the search a caller who filled the field was asking for. |
| type | string | Filter by dataset type. OCCURRENCE for observation records, CHECKLIST for species lists. |
| limit | number | Number of datasets to return (default 20, max 1000). |
| offset | number | Pagination offset. |
| hostingOrg | string | UUID (8-4-4-4-12 hex, lowercase — matched case-sensitively, as publishingOrg is) of the organization whose installation serves the dataset — distinct from the organization that published it, which is publishingOrg. Most organizations publish through an installation someone else runs, so a key from gbif_search_publishers matches nothing here for them. Supplied together the two filters are intersected, not combined. |
Search 3.9B+ GBIF occurrence records with Darwin Core filters. Use taxonKey from gbif_match_species for reliable results — it resolves synonyms automatically. Accepts country (uppercase ISO 3166-1 alpha-2, where the record was observed), publishingCountry (the publishing organization's country — a different question), stateProvince, bounding box (decimalLatitude/decimalLongitude ranges), WKT polygon geometry, year range, month, basis of record, coordinate filter, and dataset key. Returns sightings only by default — GBIF also indexes absence records (surveys that looked and found nothing), and occurrenceStatus controls whether they are included. Pagination is capped at offset+limit=100,001 and GBIF offers no cursor or scroll, so a larger result set is covered only by partitioning it — facet it by DATASET_KEY with gbif_occurrence_facets and search each datasetKey separately. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free second cuts for a dataset bucket still over the cap; YEAR, MONTH, STATE_PROVINCE, and SPECIES_KEY lose records lacking that dimension. Repeat every biological filter on the facet call and each partition search, including the same occurrenceStatus, and compare sub-split sums against the bucket total. Bulk retrieval is outside this server: use the asynchronous GBIF Download API with a GBIF.org account or the monthly GBIF Parquet snapshot on AWS Open Data.
| Argument | Type | Description |
|---|---|---|
| year | string | Year or year range. Single year: "2024". Range: "2020,2024". Filters by observation year. Both endpoints inclusive. Omit the field to search every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. |
| limit | number | Number of records to return (default 20, max 300). |
| month | number |
Search organizations registered with GBIF by name fragment or country. Returns organization key, title, and country — sufficient to chain into gbif_search_datasets as publishingOrg for the datasets an organization published, or as hostingOrg for the ones its own installation serves, or to understand who publishes data for a region. publishingOrg is the usual chain: most organizations publish through an installation someone else runs, so hostingOrg matches nothing for them.
| Argument | Type | Description |
|---|---|---|
| q | string | Name fragment to search for. Matches organization names. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because the registry answers either with all 3,561 registered organizations. |
| limit | number | Number of organizations to return (default 20, max 1000). |
| offset | number | Pagination offset. |
| country | string | ISO 3166-1 country code to filter organizations by country. The alpha-2 form ("GB") is canonical; unlike the country codes on the occurrence tools and gbif_search_datasets, this one also resolves the alpha-3 form ("GBR") and is case-insensitive, because the registry endpoint matches the parsed country rather than the string. A value GBIF cannot parse as a country errors rather than returning an empty list. Omit the field to search every country — an empty string is rejected rather than read as no filter, because the registry answers a blank country with all 3,561 organizations. |
Search or browse the GBIF backbone taxonomy by default, or an explicit checklist datasetKey. 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.
| Argument | Type | Description |
|---|---|---|
| q | string | 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 | string | Filter to a specific taxonomic rank. |
| genus | string | 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. |
| geometry |
| string |
| WKT polygon in longitude latitude order. All supplied spatial filters intersect: decimalLatitude and decimalLongitude remain active and restrict results to the overlap. Omit to leave geometry unfiltered; blank or whitespace-only is rejected. |
| taxonKey | number | GBIF backbone taxon key from gbif_match_species. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.). |
| datasetKey | string | Filter to a specific dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets. Omit the field to count across every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered total. The result is not the recordCount the dataset tools and the gbif://dataset/{datasetKey} resource report for the same key: that figure spans every occurrenceStatus, while this count applies occurrenceStatus below, PRESENT by default. |
| isInCluster | boolean | True counts likely duplicates; false excludes them. Omit to include all records. GBIF exposes membership only, with no cluster identifier. |
| basisOfRecord | string | Filter by how the occurrence was recorded; accepts every GBIF BasisOfRecord vocabulary member. |
| hasCoordinate | boolean | True counts records with coordinates; false counts only records without coordinates. Omit for both. Alias isGeoreferenced may be supplied alone or with the same value; conflicts fail as invalid_filter. |
| stateProvince | string | State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: "England", "England - Greater London", and "Greater London" are three distinct values, and "england" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value counts zero rather than erroring. Omit the field to count across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total. |
| scientificName | string | Scientific name; does not match synonyms. With taxonKey GBIF takes their union (OR), not their intersection. Omit to leave names unfiltered; blank or whitespace-only is rejected. |
| decimalLatitude | string | Latitude or latitude range "min,max" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave latitude unbounded; blank or whitespace-only is rejected. |
| isGeoreferenced | boolean | Alias for hasCoordinate. True counts only georeferenced records; false only non-georeferenced records. Supplying both requires equal values. |
| decimalLongitude | string | Longitude or longitude range "min,max" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave longitude unbounded; blank or whitespace-only is rejected. |
| occurrenceStatus | string | Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so counting one inflates the total with the opposite of a sighting. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone. Matches the gbif_search_occurrences default, so the two tools agree. |
| publishingCountry | string | ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — distinct from where the occurrence was observed, which is country. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. |
| iucnRedListCategory | string | Count only records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set. |
| coordinateUncertaintyInMeters | string | Coordinate uncertainty radius in meters, e.g. "0,1000"; range endpoints inclusive. Omit for any uncertainty; blank or whitespace-only is rejected. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"year": {
"type": "string",
"description": "Year or year range (e.g., \"2024\" or \"2020,2024\"). Both endpoints inclusive. Omit the field to count across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total."
},
"month": {
"type": "number",
"maximum": 12,
"minimum": 1,
"description": "Calendar month (1–12), matching the occurrence search filter."
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., \"GB\", \"US\"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms (\"gb\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know (\"XX\") is rejected upstream by name."
},
"geometry": {
"type": "string",
"description": "WKT polygon in longitude latitude order. All supplied spatial filters intersect: decimalLatitude and decimalLongitude remain active and restrict results to the overlap. Omit to leave geometry unfiltered; blank or whitespace-only is rejected."
},
"taxonKey": {
"type": "number",
"description": "GBIF backbone taxon key from gbif_match_species. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.)."
},
"datasetKey": {
"type": "string",
"description": "Filter to a specific dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets. Omit the field to count across every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered total. The result is not the recordCount the dataset tools and the gbif://dataset/{datasetKey} resource report for the same key: that figure spans every occurrenceStatus, while this count applies occurrenceStatus below, PRESENT by default."
},
"isInCluster": {
"type": "boolean",
"description": "True counts likely duplicates; false excludes them. Omit to include all records. GBIF exposes membership only, with no cluster identifier."
},
"basisOfRecord": {
"enum": [
"HUMAN_OBSERVATION",
"MACHINE_OBSERVATION",
"PRESERVED_SPECIMEN",
"LIVING_SPECIMEN",
"MATERIAL_SAMPLE",
"MATERIAL_CITATION",
"OCCURRENCE",
"LITERATURE",
"FOSSIL_SPECIMEN",
"OBSERVATION",
"UNKNOWN"
],
"type": "string",
"description": "Filter by how the occurrence was recorded; accepts every GBIF BasisOfRecord vocabulary member."
},
"hasCoordinate": {
"type": "boolean",
"description": "True counts records with coordinates; false counts only records without coordinates. Omit for both. Alias isGeoreferenced may be supplied alone or with the same value; conflicts fail as invalid_filter."
},
"stateProvince": {
"type": "string",
"description": "State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: \"England\", \"England - Greater London\", and \"Greater London\" are three distinct values, and \"england\" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value counts zero rather than erroring. Omit the field to count across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total."
},
"scientificName": {
"type": "string",
"description": "Scientific name; does not match synonyms. With taxonKey GBIF takes their union (OR), not their intersection. Omit to leave names unfiltered; blank or whitespace-only is rejected."
},
"decimalLatitude": {
"type": "string",
"description": "Latitude or latitude range \"min,max\" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave latitude unbounded; blank or whitespace-only is rejected."
},
"isGeoreferenced": {
"type": "boolean",
"description": "Alias for hasCoordinate. True counts only georeferenced records; false only non-georeferenced records. Supplying both requires equal values."
},
"decimalLongitude": {
"type": "string",
"description": "Longitude or longitude range \"min,max\" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave longitude unbounded; blank or whitespace-only is rejected."
},
"occurrenceStatus": {
"enum": [
"PRESENT",
"ABSENT",
"ANY"
],
"type": "string",
"default": "PRESENT",
"description": "Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so counting one inflates the total with the opposite of a sighting. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone. Matches the gbif_search_occurrences default, so the two tools agree."
},
"publishingCountry": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — distinct from where the occurrence was observed, which is country. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms (\"us\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here."
},
"iucnRedListCategory": {
"enum": [
"CR",
"EN",
"VU",
"NT",
"LC",
"DD",
"EX",
"EW",
"CD"
],
"type": "string",
"description": "Count only records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set."
},
"coordinateUncertaintyInMeters": {
"type": "string",
"description": "Coordinate uncertainty radius in meters, e.g. \"0,1000\"; range endpoints inclusive. Omit for any uncertainty; blank or whitespace-only is rejected."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "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": {
"enum": [
"KINGDOM",
"PHYLUM",
"CLASS",
"ORDER",
"FAMILY",
"GENUS",
"SPECIES",
"SUBSPECIES"
],
"type": "string",
"description": "Expected taxonomic rank. Use to avoid matching a genus when you expect a species."
},
"strict": {
"type": "boolean",
"default": false,
"description": "When true, only return an exact match. When false (default), GBIF applies fuzzy matching — useful for minor spelling variations and abbreviated names."
},
"kingdom": {
"type": "string",
"description": "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."
}
},
"additionalProperties": false
}| month | number | Calendar month (1–12), matching the occurrence search filter. |
| country | string | ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded, to scope to one country. Not the publisher's country — that is publishingCountry, and the two disagree on most records. Scope to one country, or pass back a value this tool returned under facet COUNTRY to drill into that bucket. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. |
| geometry | string | WKT polygon to scope the aggregation to a geographic area (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. All supplied spatial filters intersect: decimalLatitude and decimalLongitude remain active and restrict results to the overlap. Omit the field to aggregate everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation. |
| taxonKey | number | Backbone taxon key to scope the aggregation. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.). |
| datasetKey | string | Scope the aggregation to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet, or the datasetKey field on an occurrence record. Omit the field to aggregate across every dataset — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered aggregation. |
| facetLimit | number | Maximum number of facet values to return (default 10, max 100). |
| facetOffset | number | Zero-based offset into the ranked facet values, for paging past the first facetLimit values on high-cardinality dimensions like DATASET_KEY. Advance by facetLimit to fetch the next page (0, then facetLimit, then 2×facetLimit, …). |
| isInCluster | boolean | True includes likely duplicates; false excludes them. Omit to include all records. GBIF exposes membership only, with no cluster identifier. |
| basisOfRecord | string | Scope to a specific basis of record. |
| hasCoordinate | boolean | True includes records with coordinates; false only records without coordinates. Omit for both. |
| stateProvince | string | State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. Pass back a value this tool returned under facet STATE_PROVINCE rather than a guessed one: GBIF stores what each dataset recorded without normalizing it, so "England", "England - Greater London", and "Greater London" are three distinct values, "england" is none of them, and an unmatched value aggregates zero records rather than erroring. Omit the field to aggregate across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation. |
| scientificName | string | Scientific name; does not match synonyms. With taxonKey GBIF takes their union (OR), not their intersection. Omit to leave names unfiltered; blank or whitespace-only is rejected. |
| decimalLatitude | string | Latitude or latitude range "min,max" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave latitude unbounded; blank or whitespace-only is rejected. |
| decimalLongitude | string | Longitude or longitude range "min,max" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave longitude unbounded; blank or whitespace-only is rejected. |
| occurrenceStatus | string | Presence/absence scope. Defaults to PRESENT so the aggregation counts sightings, not the surveys that looked and found nothing, and agrees with gbif_count_occurrences on the same filters. Use ANY for both — required to see both buckets when facet is OCCURRENCE_STATUS — or ABSENT for non-observations alone. |
| publishingCountry | string | ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. Scope to one publisher country, or pass back a value this tool returned under facet PUBLISHING_COUNTRY to drill into that bucket. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. |
| iucnRedListCategory | string | Scope to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Leave unset and facet on IUCN_RED_LIST_CATEGORY to see the whole distribution instead. |
| coordinateUncertaintyInMeters | string | Coordinate uncertainty radius in meters, e.g. "0,1000"; range endpoints inclusive. Omit for any uncertainty; blank or whitespace-only is rejected. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"facet"
],
"properties": {
"year": {
"type": "string",
"description": "Year or year range (e.g., \"2020,2024\") to scope the aggregation. Both endpoints inclusive. Omit the field to aggregate across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation."
},
"facet": {
"enum": [
"BASIS_OF_RECORD",
"COUNTRY",
"STATE_PROVINCE",
"YEAR",
"DATASET_KEY",
"KINGDOM_KEY",
"PHYLUM_KEY",
"CLASS_KEY",
"ORDER_KEY",
"FAMILY_KEY",
"GENUS_KEY",
"SPECIES_KEY",
"PUBLISHING_COUNTRY",
"MONTH",
"OCCURRENCE_STATUS",
"IUCN_RED_LIST_CATEGORY"
],
"type": "string",
"description": "Dimension to aggregate by (e.g., COUNTRY, YEAR, BASIS_OF_RECORD, SPECIES_KEY, OCCURRENCE_STATUS, IUCN_RED_LIST_CATEGORY). DATASET_KEY is the first cut when a result set is too large to page: every occurrence carries exactly one datasetKey, so its buckets cover totalOccurrences with no gap or overlap. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free second cuts for a dataset bucket still too large; both have a matching filter on the occurrence tools. A dimension a record can lack drops that record from every bucket: YEAR loses undated records; MONTH, STATE_PROVINCE, and SPECIES_KEY lose records lacking that dimension, even where the occurrence tools can filter on it. Sums are comparable only across the same occurrenceStatus scope."
},
"month": {
"type": "number",
"maximum": 12,
"minimum": 1,
"description": "Calendar month (1–12), matching the occurrence search filter."
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded, to scope to one country. Not the publisher's country — that is publishingCountry, and the two disagree on most records. Scope to one country, or pass back a value this tool returned under facet COUNTRY to drill into that bucket. Lowercase and alpha-3 forms (\"gb\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here."
},
"geometry": {
"type": "string",
"description": "WKT polygon to scope the aggregation to a geographic area (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. All supplied spatial filters intersect: decimalLatitude and decimalLongitude remain active and restrict results to the overlap. Omit the field to aggregate everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation."
},
"taxonKey": {
"type": "number",
"description": "Backbone taxon key to scope the aggregation. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.)."
},
"datasetKey": {
"type": "string",
"description": "Scope the aggregation to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet, or the datasetKey field on an occurrence record. Omit the field to aggregate across every dataset — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered aggregation."
},
"facetLimit": {
"type": "number",
"default": 10,
"minimum": 1,
"description": "Maximum number of facet values to return (default 10, max 100)."
},
"facetOffset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Zero-based offset into the ranked facet values, for paging past the first facetLimit values on high-cardinality dimensions like DATASET_KEY. Advance by facetLimit to fetch the next page (0, then facetLimit, then 2×facetLimit, …)."
},
"isInCluster": {
"type": "boolean",
"description": "True includes likely duplicates; false excludes them. Omit to include all records. GBIF exposes membership only, with no cluster identifier."
},
"basisOfRecord": {
"enum": [
"HUMAN_OBSERVATION",
"MACHINE_OBSERVATION",
"PRESERVED_SPECIMEN",
"LIVING_SPECIMEN",
"MATERIAL_SAMPLE",
"MATERIAL_CITATION",
"OCCURRENCE",
"LITERATURE",
"FOSSIL_SPECIMEN",
"OBSERVATION",
"UNKNOWN"
],
"type": "string",
"description": "Scope to a specific basis of record."
},
"hasCoordinate": {
"type": "boolean",
"description": "True includes records with coordinates; false only records without coordinates. Omit for both."
},
"stateProvince": {
"type": "string",
"description": "State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. Pass back a value this tool returned under facet STATE_PROVINCE rather than a guessed one: GBIF stores what each dataset recorded without normalizing it, so \"England\", \"England - Greater London\", and \"Greater London\" are three distinct values, \"england\" is none of them, and an unmatched value aggregates zero records rather than erroring. Omit the field to aggregate across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation."
},
"scientificName": {
"type": "string",
"description": "Scientific name; does not match synonyms. With taxonKey GBIF takes their union (OR), not their intersection. Omit to leave names unfiltered; blank or whitespace-only is rejected."
},
"decimalLatitude": {
"type": "string",
"description": "Latitude or latitude range \"min,max\" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave latitude unbounded; blank or whitespace-only is rejected."
},
"decimalLongitude": {
"type": "string",
"description": "Longitude or longitude range \"min,max\" in decimal degrees (WGS84). All supplied spatial filters intersect, including geometry. Omit to leave longitude unbounded; blank or whitespace-only is rejected."
},
"occurrenceStatus": {
"enum": [
"PRESENT",
"ABSENT",
"ANY"
],
"type": "string",
"default": "PRESENT",
"description": "Presence/absence scope. Defaults to PRESENT so the aggregation counts sightings, not the surveys that looked and found nothing, and agrees with gbif_count_occurrences on the same filters. Use ANY for both — required to see both buckets when facet is OCCURRENCE_STATUS — or ABSENT for non-observations alone."
},
"publishingCountry": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. Scope to one publisher country, or pass back a value this tool returned under facet PUBLISHING_COUNTRY to drill into that bucket. Lowercase and alpha-3 forms (\"us\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here."
},
"iucnRedListCategory": {
"enum": [
"CR",
"EN",
"VU",
"NT",
"LC",
"DD",
"EX",
"EW",
"CD"
],
"type": "string",
"description": "Scope to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Leave unset and facet on IUCN_RED_LIST_CATEGORY to see the whole distribution instead."
},
"coordinateUncertaintyInMeters": {
"type": "string",
"description": "Coordinate uncertainty radius in meters, e.g. \"0,1000\"; range endpoints inclusive. Omit for any uncertainty; blank or whitespace-only is rejected."
}
},
"additionalProperties": false
}| publishingOrg | string | UUID (8-4-4-4-12 hex, lowercase — GBIF matches these two keys case-sensitively, so an upper-cased rendering of a real key matches nothing) of the organization that published the dataset — the organization whose data it is, and the question a key from gbif_search_publishers is usually asking. The organization that serves it is hostingOrg, which matches a different set. Supplied together the two filters are intersected, not combined, so the same key in both fields returns only what that organization both published and serves. |
| publishingCountry | string | ISO 3166-1 alpha-2 code, uppercase, of the organization that published the dataset (e.g., "GB", "US", "DE", "SE"). Lowercase and alpha-3 forms ("gb", "GBR") match nothing upstream, which is why only the uppercase two-letter form is accepted here — unlike the country filter on gbif_search_publishers, which resolves either form. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not assign ("XX") is rejected upstream by name. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"q": {
"type": "string",
"description": "Free-text search across dataset title and description. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because GBIF answers a blank one with all 123,527 indexed datasets and a whitespace-only one with none, and neither is the search a caller who filled the field was asking for."
},
"type": {
"enum": [
"OCCURRENCE",
"CHECKLIST",
"METADATA",
"SAMPLING_EVENT"
],
"type": "string",
"description": "Filter by dataset type. OCCURRENCE for observation records, CHECKLIST for species lists."
},
"limit": {
"type": "number",
"default": 20,
"minimum": 1,
"description": "Number of datasets to return (default 20, max 1000)."
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Pagination offset."
},
"hostingOrg": {
"type": "string",
"description": "UUID (8-4-4-4-12 hex, lowercase — matched case-sensitively, as publishingOrg is) of the organization whose installation serves the dataset — distinct from the organization that published it, which is publishingOrg. Most organizations publish through an installation someone else runs, so a key from gbif_search_publishers matches nothing here for them. Supplied together the two filters are intersected, not combined."
},
"publishingOrg": {
"type": "string",
"description": "UUID (8-4-4-4-12 hex, lowercase — GBIF matches these two keys case-sensitively, so an upper-cased rendering of a real key matches nothing) of the organization that published the dataset — the organization whose data it is, and the question a key from gbif_search_publishers is usually asking. The organization that serves it is hostingOrg, which matches a different set. Supplied together the two filters are intersected, not combined, so the same key in both fields returns only what that organization both published and serves."
},
"publishingCountry": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the dataset (e.g., \"GB\", \"US\", \"DE\", \"SE\"). Lowercase and alpha-3 forms (\"gb\", \"GBR\") match nothing upstream, which is why only the uppercase two-letter form is accepted here — unlike the country filter on gbif_search_publishers, which resolves either form. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not assign (\"XX\") is rejected upstream by name."
}
},
"additionalProperties": false
}| Calendar month (1–12). Useful for seasonal distribution queries. |
| offset | number | Pagination offset. GBIF serves offset+limit up to 100,001 and rejects anything past it, with no cursor or scroll to continue from. To reach a result set larger than that, split it into per-datasetKey searches using a DATASET_KEY facet from gbif_occurrence_facets — gap-free and high-cardinality, unlike YEAR, which leaves undated records in no bucket — rather than paging deeper. |
| country | string | ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., "GB", "US", "DE", "SE"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know ("XX") is rejected upstream by name. |
| geometry | string | WKT polygon for geographic filtering (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. All supplied spatial filters intersect: decimalLatitude and decimalLongitude remain active and restrict results to the overlap. Omit the field to search everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. |
| taxonKey | number | GBIF backbone taxon key from gbif_match_species. Preferred over scientificName — matches all synonyms automatically. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.). |
| datasetKey | string | Restrict results to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet (gbif_occurrence_facets), or the datasetKey field on an occurrence record. Omit the field to search every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered result set. |
| isInCluster | boolean | Filter to records flagged as likely duplicates (true) or exclude them (false). Omit to include all. Note: GBIF does not expose a cluster identifier — only the membership flag. To de-duplicate, set isInCluster: false to exclude all clustered records. |
| basisOfRecord | string | Filter by how the occurrence was recorded. HUMAN_OBSERVATION covers citizen science. PRESERVED_SPECIMEN covers natural history collections. |
| hasCoordinate | boolean | When true, return only georeferenced records (those with coordinates). When false, return ONLY records without coordinates. Omit the parameter entirely to include all records regardless of coordinate presence. |
| stateProvince | string | State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: "England", "England - Greater London", and "Greater London" are three distinct values, and "england" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value returns zero records rather than an error. Omit the field to search every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. Records carrying no stateProvince match no value, so this cannot partition a scope. |
| scientificName | string | Scientific name filter. Less precise than taxonKey — does not match synonyms. Use taxonKey from gbif_match_species for reliable results. Supplying both does not narrow the search: GBIF combines the two taxon filters with OR, so the result is the union of the two, not their intersection. Omit the field to search every name — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. |
| decimalLatitude | string | Latitude range as "min,max" (e.g., "47.0,48.5"). Decimal degrees, WGS84. Combine with decimalLongitude for a bounding box. Omit the field to leave latitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. |
| decimalLongitude | string | Longitude range as "min,max" (e.g., "8.0,9.5"). Decimal degrees, WGS84. Combine with decimalLatitude for a bounding box. Omit the field to leave longitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. |
| occurrenceStatus | string | Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so including one would read as a sighting of the opposite. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone. |
| publishingCountry | string | ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — distinct from where the occurrence was observed, which is country. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. |
| iucnRedListCategory | string | Restrict to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set. |
| coordinateUncertaintyInMeters | string | Filter by coordinate uncertainty radius in meters. Range format: "min,max" (e.g., "0,1000" for sub-kilometer precision). Both endpoints inclusive. Omit the field to accept any uncertainty — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"year": {
"type": "string",
"description": "Year or year range. Single year: \"2024\". Range: \"2020,2024\". Filters by observation year. Both endpoints inclusive. Omit the field to search every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set."
},
"limit": {
"type": "number",
"default": 20,
"minimum": 1,
"description": "Number of records to return (default 20, max 300)."
},
"month": {
"type": "number",
"maximum": 12,
"minimum": 1,
"description": "Calendar month (1–12). Useful for seasonal distribution queries."
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Pagination offset. GBIF serves offset+limit up to 100,001 and rejects anything past it, with no cursor or scroll to continue from. To reach a result set larger than that, split it into per-datasetKey searches using a DATASET_KEY facet from gbif_occurrence_facets — gap-free and high-cardinality, unlike YEAR, which leaves undated records in no bucket — rather than paging deeper."
},
"country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., \"GB\", \"US\", \"DE\", \"SE\"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms (\"gb\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know (\"XX\") is rejected upstream by name."
},
"geometry": {
"type": "string",
"description": "WKT polygon for geographic filtering (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. All supplied spatial filters intersect: decimalLatitude and decimalLongitude remain active and restrict results to the overlap. Omit the field to search everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set."
},
"taxonKey": {
"type": "number",
"description": "GBIF backbone taxon key from gbif_match_species. Preferred over scientificName — matches all synonyms automatically. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.)."
},
"datasetKey": {
"type": "string",
"description": "Restrict results to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet (gbif_occurrence_facets), or the datasetKey field on an occurrence record. Omit the field to search every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered result set."
},
"isInCluster": {
"type": "boolean",
"description": "Filter to records flagged as likely duplicates (true) or exclude them (false). Omit to include all. Note: GBIF does not expose a cluster identifier — only the membership flag. To de-duplicate, set isInCluster: false to exclude all clustered records."
},
"basisOfRecord": {
"enum": [
"HUMAN_OBSERVATION",
"MACHINE_OBSERVATION",
"PRESERVED_SPECIMEN",
"LIVING_SPECIMEN",
"MATERIAL_SAMPLE",
"MATERIAL_CITATION",
"OCCURRENCE",
"LITERATURE",
"FOSSIL_SPECIMEN",
"OBSERVATION",
"UNKNOWN"
],
"type": "string",
"description": "Filter by how the occurrence was recorded. HUMAN_OBSERVATION covers citizen science. PRESERVED_SPECIMEN covers natural history collections."
},
"hasCoordinate": {
"type": "boolean",
"description": "When true, return only georeferenced records (those with coordinates). When false, return ONLY records without coordinates. Omit the parameter entirely to include all records regardless of coordinate presence."
},
"stateProvince": {
"type": "string",
"description": "State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: \"England\", \"England - Greater London\", and \"Greater London\" are three distinct values, and \"england\" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value returns zero records rather than an error. Omit the field to search every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. Records carrying no stateProvince match no value, so this cannot partition a scope."
},
"scientificName": {
"type": "string",
"description": "Scientific name filter. Less precise than taxonKey — does not match synonyms. Use taxonKey from gbif_match_species for reliable results. Supplying both does not narrow the search: GBIF combines the two taxon filters with OR, so the result is the union of the two, not their intersection. Omit the field to search every name — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set."
},
"decimalLatitude": {
"type": "string",
"description": "Latitude range as \"min,max\" (e.g., \"47.0,48.5\"). Decimal degrees, WGS84. Combine with decimalLongitude for a bounding box. Omit the field to leave latitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set."
},
"decimalLongitude": {
"type": "string",
"description": "Longitude range as \"min,max\" (e.g., \"8.0,9.5\"). Decimal degrees, WGS84. Combine with decimalLatitude for a bounding box. Omit the field to leave longitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set."
},
"occurrenceStatus": {
"enum": [
"PRESENT",
"ABSENT",
"ANY"
],
"type": "string",
"default": "PRESENT",
"description": "Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so including one would read as a sighting of the opposite. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone."
},
"publishingCountry": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — distinct from where the occurrence was observed, which is country. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms (\"us\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here."
},
"iucnRedListCategory": {
"enum": [
"CR",
"EN",
"VU",
"NT",
"LC",
"DD",
"EX",
"EW",
"CD"
],
"type": "string",
"description": "Restrict to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set."
},
"coordinateUncertaintyInMeters": {
"type": "string",
"description": "Filter by coordinate uncertainty radius in meters. Range format: \"min,max\" (e.g., \"0,1000\" for sub-kilometer precision). Both endpoints inclusive. Omit the field to accept any uncertainty — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"q": {
"type": "string",
"description": "Name fragment to search for. Matches organization names. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because the registry answers either with all 3,561 registered organizations."
},
"limit": {
"type": "number",
"default": 20,
"minimum": 1,
"description": "Number of organizations to return (default 20, max 1000)."
},
"offset": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Pagination offset."
},
"country": {
"type": "string",
"description": "ISO 3166-1 country code to filter organizations by country. The alpha-2 form (\"GB\") is canonical; unlike the country codes on the occurrence tools and gbif_search_datasets, this one also resolves the alpha-3 form (\"GBR\") and is case-insensitive, because the registry endpoint matches the parsed country rather than the string. A value GBIF cannot parse as a country errors rather than returning an empty list. Omit the field to search every country — an empty string is rejected rather than read as no filter, because the registry answers a blank country with all 3,561 organizations."
}
},
"additionalProperties": false
}| limit | number | Number of records to return (default 20, max 1000). |
| family | string | 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 | number | Pagination offset. |
| kingdom | string | 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 | boolean | Filter to extinct (true) or extant (false) taxa. |
| datasetKey | string | 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. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"q": {
"type": "string",
"description": "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": {
"enum": [
"KINGDOM",
"PHYLUM",
"CLASS",
"ORDER",
"FAMILY",
"GENUS",
"SPECIES",
"SUBSPECIES"
],
"type": "string",
"description": "Filter to a specific taxonomic rank."
},
"genus": {
"type": "string",
"description": "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": {
"type": "number",
"default": 20,
"minimum": 1,
"description": "Number of records to return (default 20, max 1000)."
},
"family": {
"type": "string",
"description": "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": {
"type": "number",
"default": 0,
"minimum": 0,
"description": "Pagination offset."
},
"kingdom": {
"type": "string",
"description": "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": {
"type": "boolean",
"description": "Filter to extinct (true) or extant (false) taxa."
},
"datasetKey": {
"type": "string",
"description": "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."
}
},
"additionalProperties": false
}