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 (or checklistTaxonKey with checklistKey, for a Catalogue of Life key), country (uppercase ISO 3166-1 alpha-2), publishingCountry, stateProvince, gadmGid, scientificName, spatial ranges and geometry (intersected), month, basisOfRecord, hasCoordinate (alias isGeoreferenced), hasGeospatialIssue, isInCluster, coordinateUncertaintyInMeters, datasetKey, publishingOrg, year, catalogNumber, institutionCode, recordedBy, mediaType, typeStatus, establishmentMeans, license, 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.
View input schema
{
"type": "object",
"properties": {
"scientificName": {
"description": "Scientific name, which GBIF resolves to its accepted taxon, so a synonym counts the records of that taxon; a name shared across kingdoms, such as Oenanthe (a bird genus and a plant genus), counts zero — use taxonKey from gbif_match_species with kingdom set for one. With taxonKey GBIF takes their union (OR), not their intersection. Omit to leave names unfiltered; blank or whitespace-only is rejected.",
"type": "string"
},
"geometry": {
"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.",
"type": "string"
},
"month": {
"description": "Calendar month (1–12), matching the occurrence search filter.",
"type": "integer",
"minimum": 1,
"maximum": 12
},
"basisOfRecord": {
"description": "Filter by how the occurrence was recorded; accepts every GBIF BasisOfRecord vocabulary member.",
"type": "string",
"enum": [
"HUMAN_OBSERVATION",
"MACHINE_OBSERVATION",
"PRESERVED_SPECIMEN",
"LIVING_SPECIMEN",
"MATERIAL_SAMPLE",
"MATERIAL_CITATION",
"OCCURRENCE",
"LITERATURE",
"FOSSIL_SPECIMEN",
"OBSERVATION",
"UNKNOWN"
]
},
"hasCoordinate": {
"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.",
"type": "boolean"
},
"isInCluster": {
"description": "True counts likely duplicates; false excludes them. Omit to include all records. GBIF exposes membership only, with no cluster identifier.",
"type": "boolean"
},
"taxonKey": {
"description": "GBIF backbone taxon key from gbif_match_species. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.). Rejected under checklistKey 7ddf754f-d193-4cc9-b351-99906754a03b — pass a Catalogue of Life key as checklistTaxonKey there.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"country": {
"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.",
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"publishingCountry": {
"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.",
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"stateProvince": {
"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.",
"type": "string"
},
"isGeoreferenced": {
"description": "Alias for hasCoordinate. True counts only georeferenced records; false only non-georeferenced records. Supplying both requires equal values.",
"type": "boolean"
},
"datasetKey": {
"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.",
"type": "string"
},
"year": {
"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.",
"type": "string"
},
"occurrenceStatus": {
"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. DETECTED and NOT_DETECTED, the spelling records and OCCURRENCE_STATUS facet buckets carry, select the same records as PRESENT and ABSENT and are sent as given. Matches the gbif_search_occurrences default, so the two tools agree.",
"type": "string",
"enum": [
"PRESENT",
"ABSENT",
"DETECTED",
"NOT_DETECTED",
"ANY"
]
},
"iucnRedListCategory": {
"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.",
"type": "string",
"enum": [
"CR",
"EN",
"VU",
"NT",
"LC",
"DD",
"EX",
"EW",
"CD"
]
},
"checklistKey": {
"description": "Taxonomy taxon keys are read in, both in this scope and in KINGDOM_KEY through SPECIES_KEY facet buckets. Omitted, or d7dddbf4-2cf0-4f39-9b2a-bb099caae36c, is the GBIF Backbone, whose integer keys taxonKey takes; GBIF no longer updates it. 7ddf754f-d193-4cc9-b351-99906754a03b is the Catalogue of Life eXtended Release, the taxonomy GBIF now maintains: scope by one of its keys with checklistTaxonKey, which requires this value, and taxonKey is rejected under it. Records keep their Backbone taxonKey either way.",
"type": "string",
"enum": [
"d7dddbf4-2cf0-4f39-9b2a-bb099caae36c",
"7ddf754f-d193-4cc9-b351-99906754a03b"
]
},
"checklistTaxonKey": {
"description": "Catalogue of Life taxon key, such as 3WSJV (Lynx pardinus), to scope to that taxon and every descendant — the checklistTaxonKey gbif_match_species or gbif_bulk_match_species returns under the same checklistKey, or a KINGDOM_KEY through SPECIES_KEY bucket of gbif_occurrence_facets under it. Requires checklistKey 7ddf754f-d193-4cc9-b351-99906754a03b, and goes to GBIF as its taxonKey. Uppercase letters and digits only, matched case-sensitively; a digit-only key such as 8288 (the genus Tringa) is not the Backbone taxonKey of the same spelling, which names an unrelated taxon. Omit the field to leave it unfiltered — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered scope.",
"type": "string"
},
"decimalLatitude": {
"description": "Latitude in decimal degrees (WGS84) as a range \"min,max\", both ends inclusive (e.g. \"47.0,48.5\"); pair it with a decimalLongitude range for a bounding box. A value without a comma is not a range: GBIF matches only records at exactly that latitude, so \"38\" is not \"around 38\". All supplied spatial filters intersect, geometry included. 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 scope.",
"type": "string"
},
"decimalLongitude": {
"description": "Longitude in decimal degrees (WGS84) as a range \"min,max\", both ends inclusive (e.g. \"8.0,9.5\"); pair it with a decimalLatitude range for a bounding box. A value without a comma is not a range: GBIF matches only records at exactly that longitude, so \"-3\" is not \"around -3\". All supplied spatial filters intersect, geometry included. 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 scope.",
"type": "string"
},
"coordinateUncertaintyInMeters": {
"description": "Coordinate uncertainty in meters as a range \"min,max\", both ends inclusive, where \"*\" may stand for one open end: \"0,1000\" or \"*,1000\" keeps records placed to within 1 km. A value without a comma is not an upper bound: GBIF matches only records whose uncertainty is exactly that value, so \"1000\" is not \"within 1 km\". 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 scope.",
"type": "string"
},
"gadmGid": {
"description": "GADM administrative-area GID at any level: country (ESP), state or province (ESP.1_1), county or district (ESP.1.5_1), or municipality (ESP.1.6.3_1). GBIF derives a record's GIDs from its coordinates, so records without coordinates match none, and the unit can differ from the verbatim stateProvince the record carries. Matched exactly and case-sensitively, and a GID holds only uppercase letters, digits, dots, and underscores — any other character is rejected. Take one from a GADM_LEVEL_0_GID, GADM_LEVEL_1_GID, GADM_LEVEL_2_GID, or GADM_LEVEL_3_GID facet on gbif_occurrence_facets, or from the gadm field of gbif_get_occurrence; a well-formed GID GBIF does not hold matches zero records rather than erroring. Omit the field to leave it unfiltered — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered scope.",
"type": "string"
},
"catalogNumber": {
"description": "Catalog number a collection assigned to the specimen or record (e.g. \"L.1592880\"), matched as the whole value, case-insensitively. Not unique across collections — one number can name records in several datasets, so pair it with institutionCode or datasetKey to single one out. Omit the field to leave it unfiltered — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered scope.",
"type": "string"
},
"institutionCode": {
"description": "Code of the institution holding the record (e.g. \"K\", \"CLO\"), matched as the whole value, case-insensitively — part of a code or of a multi-word code matches nothing. An INSTITUTION_CODE facet on gbif_occurrence_facets lists the codes in a scope, lowercased, and this filter takes them unchanged. Omit the field to leave it unfiltered — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered scope.",
"type": "string"
},
"recordedBy": {
"description": "Collector or observer, matched against each name in the record's recordedBy list (GBIF splits it on \"|\") exactly and case-sensitively: \"Charles Darwin\" and \"charles darwin\" differ, and one person written two ways (\"Charles Darwin\", \"Darwin, C.\") is two values. Take a value from a RECORDED_BY facet on gbif_occurrence_facets scoped the same way and pass it back unchanged; an unmatched value matches zero records rather than erroring. Omit the field to leave it unfiltered — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered scope.",
"type": "string"
},
"mediaType": {
"description": "Only records carrying at least one media item of this type: StillImage (photographs, scans), MovingImage (video), Sound (audio), or InteractiveResource. Records without media are excluded when this is set.",
"type": "string",
"enum": [
"StillImage",
"MovingImage",
"Sound",
"InteractiveResource"
]
},
"publishingOrg": {
"description": "UUID (8-4-4-4-12 hex) of the GBIF organization that published the records, to scope to what it shares across all its datasets — not the organization whose installation hosts them, and not publishingCountry. Take one from gbif_search_publishers, the publishingOrganizationKey of gbif_get_dataset, a gbif_search_datasets row, gbif_get_occurrence, or a gbif_search_occurrences row, or a PUBLISHING_ORG facet on gbif_occurrence_facets; a well-formed key GBIF does not hold matches zero records. Omit the field to leave it unfiltered — an empty string is rejected rather than read as no filter, because GBIF answers a blank publishingOrg with the unfiltered scope.",
"type": "string"
},
"hasGeospatialIssue": {
"description": "True keeps only records GBIF flagged with a spatial issue when interpreting them — zero coordinates, coordinates out of range, or coordinates outside the stated country, for example; false keeps only records with no such flag. GBIF often drops the coordinates of a flagged record, and a record without coordinates can carry either value, so for records to map pair false with hasCoordinate true. Omit for both.",
"type": "boolean"
},
"typeStatus": {
"description": "Nomenclatural type status of a specimen — a concept from GBIF's TypeStatus vocabulary such as Holotype, Isotype, Lectotype, Paratype, Syntype, Neotype, Type, or NotAType. Matched ignoring case and surrounding whitespace, then sent and echoed in scope in GBIF's own spelling; a value naming no concept is rejected with the full list. A concept also matches every narrower one — Type covers every kind of type, Lectotype covers Isolectotype — and a TYPE_STATUS facet on gbif_occurrence_facets lists the concepts in a scope. Omit the field to leave it unfiltered — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered scope.",
"type": "string"
},
"establishmentMeans": {
"description": "How the organism came to be where it was recorded — a concept from GBIF's EstablishmentMeans vocabulary: native, nativeEndemic, nativeReintroduced, introduced, introducedAssistedColonisation, uncertain, or vagrant. Matched ignoring case and surrounding whitespace, then sent and echoed in scope in GBIF's own spelling; any other value is rejected. A concept also matches its narrower ones: native covers nativeEndemic and nativeReintroduced, and introduced covers introducedAssistedColonisation. Most records state none and match no value. Omit the field to leave it unfiltered — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered scope.",
"type": "string"
},
"license": {
"description": "License the record is published under, as its GBIF code: CC0_1_0, CC_BY_4_0, or CC_BY_NC_4_0 — every record carries one of the three. A record states its license as a Creative Commons URL instead (http://creativecommons.org/licenses/by/4.0/legalcode for CC_BY_4_0), which this filter does not take.",
"type": "string",
"enum": [
"CC0_1_0",
"CC_BY_4_0",
"CC_BY_NC_4_0"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}