gbif-biodiversity-mcp-server

{'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".'}, 'maxItems': 50, 'minItems': 1, 'description': 'Scientific names to match against the GBIF backbone. 1â\x80\x9350 per call, matched in parallel.'}, '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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['results']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': 'Machine-readable failure mode.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'results': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'matchType'], 'properties': {'name': {'type': 'string', 'description': 'The input name this entry corresponds to.'}, 'rank': {'type': 'string', 'description': 'Taxonomic rank of the matched taxon.'}, 'error': {'type': 'string', 'description': 'Failure message when matchType is ERROR. Absent otherwise.'}, 'reason': {'type': 'string', 'description': 'Machine-readable failure identifier when matchType is ERROR â\x80\x94 e.g. invalid_filter when GBIF rejected a supplied value. Absent when the failure carried no classification, and absent on every non-ERROR entry.'}, 'status': {'type': 'string', 'description': 'Taxonomic status: ACCEPTED, SYNONYM, or DOUBTFUL.'}, 'taxonKey': {'type': 'number', 'description': "GBIF backbone taxon key to pass to gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets â\x80\x94 the accepted taxon's key when this name is a synonym, otherwise the matched taxon's own key. Absent when matchType is NONE or ERROR."}, 'matchType': {'type': 'string', 'description': 'EXACT, FUZZY, or HIGHERRANK for a match; NONE when GBIF found no usable match; ERROR when the lookup itself failed for this name (see error).'}, 'confidence': {'type': 'number', 'description': 'Match confidence 0â\x80\x93100. Below 80 warrants review. Absent on ERROR.'}, 'canonicalName': {'type': 'string', 'description': 'Matched scientific name without authorship. Absent when unmatched.'}, 'scientificName': {'type': 'string', 'description': 'Full matched scientific name with authorship. Absent when unmatched.'}, 'matchedTaxonKey': {'type': 'number', 'description': 'Backbone key of the name that actually matched. Present only when it differs from taxonKey â\x80\x94 that is, when a synonym was resolved to its accepted taxon.'}}, 'description': 'Match outcome for one input name.', 'additionalProperties': False}, 'description': 'One result per input name, in input order.'}}, 'additionalProperties': False}

{'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 â\x80\x94 a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.'}, '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 â\x80\x94 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.'}, '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 â\x80\x94 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.'}, 'stateProvince': {'type': 'string', 'description': 'State, province, or first-level administrative division, matched as a verbatim string â\x80\x94 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 â\x80\x94 an unmatched value counts zero rather than erroring. Omit the field to count across every state or province â\x80\x94 a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.'}, 'isGeoreferenced': {'type': 'boolean', 'description': 'When true, count only georeferenced records. When false, count only non-georeferenced records.'}, '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 â\x80\x94 not where the occurrence was observed, which is country. The two differ constantly: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations. 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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['count', 'occurrenceStatus']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'count': {'type': 'number', 'description': 'Total occurrences matching the supplied filters.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_filter`: A filter was supplied blank or whitespace-only, datasetKey is not an 8-4-4-4-12 hex UUID, a two-letter country or publishingCountry code is one GBIF does not know, or GBIF rejected another filter value as malformed. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Guidance when the count is zero under a verbatim stateProvince filter, larger than gbif_search_occurrences can page to, or narrowed by a presence/absence filter. Absent when none applies.'}, 'occurrenceStatus': {'type': 'string', 'description': 'The presence/absence filter applied upstream â\x80\x94 PRESENT, ABSENT, or ANY when no filter was sent. Says what the count covers.'}}, 'additionalProperties': False}

{'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': 100, 'minimum': 0, 'description': 'Maximum number of contacts to include (default 10, max 100). Set to 0 to omit contact detail while still reporting contactsTotal â\x80\x94 useful when citation, license, and record count are all you need from a high-contact dataset like eBird.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'contactLimit applied when the list was capped. Raise it (max 100) to see more. Absent otherwise.'}, 'doi': {'type': 'string', 'description': 'DOI for citation. May be absent.'}, 'key': {'type': 'string', 'description': 'Dataset UUID.'}, 'type': {'type': 'string', 'description': 'Dataset type (OCCURRENCE, CHECKLIST, etc.).'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The datasetKey UUID does not match any dataset in GBIF. `invalid_filter`: datasetKey is not a UUID, or GBIF rejected the request as malformed. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Contacts included in this response when the list was capped. Absent otherwise.'}, 'title': {'type': 'string', 'description': 'Dataset title.'}, 'notice': {'type': 'string', 'description': 'How to reach the contacts contactLimit held back. Absent when every contact was returned.'}, 'license': {'type': 'string', 'description': 'License identifier. May be absent.'}, 'contacts': {'type': 'array', 'items': {'type': 'object', 'properties': {'type': {'type': 'string', 'description': 'Contact type (e.g., ADMINISTRATIVE_POINT_OF_CONTACT).'}, 'email': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Contact email addresses. May be absent.'}, 'lastName': {'type': 'string', 'description': 'Last name. May be absent.'}, 'firstName': {'type': 'string', 'description': 'First name. May be absent.'}, 'organization': {'type': 'string', 'description': 'Organization name. May be absent.'}}, 'description': 'A dataset contact with role, name, organization, and email.', 'additionalProperties': False}, 'description': 'Dataset contacts, capped at contactLimit. Absent when the dataset has no contacts or contactLimit is 0.'}, 'truncated': {'type': 'boolean', 'description': 'True when the dataset carries more contacts than contactLimit allowed through. Absent when every contact was returned.'}, 'description': {'type': 'string', 'description': 'Full dataset description. May be absent.'}, 'recordCount': {'type': 'number', 'description': 'Occurrence records GBIF has indexed for this dataset, matching the figure gbif_search_datasets reports. Spans every occurrenceStatus: absence records â\x80\x94 surveys that looked for a taxon and did not find it â\x80\x94 are counted alongside sightings, and on some datasets they are the overwhelming majority. gbif_count_occurrences with this datasetKey answers the other question, defaulting to occurrenceStatus PRESENT, so the two figures are expected to differ rather than one being wrong. Fetched separately because the detail endpoint omits it; absent when that lookup does not return in time.'}, 'citationText': {'type': 'string', 'description': 'Full citation text for academic reference. May be absent.'}, 'contactsTotal': {'type': 'number', 'description': 'Total contacts on the dataset before applying contactLimit. Present when the dataset has any contacts.'}, 'numConstituents': {'type': 'number', 'description': 'Number of constituent sub-datasets. May be absent.'}, 'contactsReturned': {'type': 'number', 'description': 'Number of contacts included in this response (â\x89¤ contactLimit). Present when the dataset has any contacts.'}, 'publishingCountry': {'type': 'string', 'description': 'Country code of the publishing organization.'}, 'temporalCoverages': {'type': 'array', 'items': {'type': 'object', 'properties': {'end': {'type': 'string', 'description': 'Coverage end as an ISO 8601 date-time. May be absent.'}, 'start': {'type': 'string', 'description': 'Coverage start as an ISO 8601 date-time. May be absent.'}}, 'description': 'A temporal coverage range.', 'additionalProperties': False}, 'description': 'Temporal coverage ranges declared by the dataset. May be absent.'}, 'geographicCoverages': {'type': 'array', 'items': {'type': 'object', 'properties': {'description': {'type': 'string', 'description': 'Geographic coverage description (e.g. "Worldwide"). May be absent.'}}, 'description': 'A geographic coverage entry.', 'additionalProperties': False}, 'description': 'Geographic coverage descriptions declared by the dataset. May be absent.'}}, 'additionalProperties': False}

{'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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'day': {'type': 'number', 'description': 'Observation day. May be absent.'}, 'key': {'type': 'number', 'description': 'GBIF occurrence key.'}, 'sex': {'type': 'string', 'description': 'Sex of the individual(s). May be absent.'}, 'gadm': {'type': 'object', 'properties': {'level0': {'type': 'object', 'properties': {'gid': {'type': 'string', 'description': 'GADM GID â\x80\x94 stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.'}, 'name': {'type': 'string', 'description': 'Administrative-unit name. May be absent.'}}, 'description': 'GADM level 0 â\x80\x94 country. May be absent.', 'additionalProperties': False}, 'level1': {'type': 'object', 'properties': {'gid': {'type': 'string', 'description': 'GADM GID â\x80\x94 stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.'}, 'name': {'type': 'string', 'description': 'Administrative-unit name. May be absent.'}}, 'description': 'GADM level 1 â\x80\x94 state/province. May be absent.', 'additionalProperties': False}, 'level2': {'type': 'object', 'properties': {'gid': {'type': 'string', 'description': 'GADM GID â\x80\x94 stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.'}, 'name': {'type': 'string', 'description': 'Administrative-unit name. May be absent.'}}, 'description': 'GADM level 2 â\x80\x94 county/district. May be absent.', 'additionalProperties': False}, 'level3': {'type': 'object', 'properties': {'gid': {'type': 'string', 'description': 'GADM GID â\x80\x94 stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.'}, 'name': {'type': 'string', 'description': 'Administrative-unit name. May be absent.'}}, 'description': 'GADM level 3 â\x80\x94 municipality/ward, the finest level GBIF indexes. Absent where the country does not subdivide that far.', 'additionalProperties': False}}, 'description': 'GADM administrative geography â\x80\x94 stable GIDs and names at levels 0â\x80\x933. May be absent.', 'additionalProperties': False}, 'year': {'type': 'number', 'description': 'Observation year. May be absent.'}, 'class': {'type': 'string', 'description': 'Class classification. May be absent.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The occurrenceKey does not exist in GBIF. `invalid_filter`: GBIF rejected the occurrenceKey as unparseable â\x80\x94 a fraction, or a value past the largest integer the endpoint accepts. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'genus': {'type': 'string', 'description': 'Genus classification.'}, 'media': {'type': 'array', 'items': {'type': 'object', 'properties': {'type': {'type': 'string', 'description': 'Media type (StillImage, Sound, etc.).'}, 'title': {'type': 'string', 'description': 'Media title.'}, 'format': {'type': 'string', 'description': 'MIME format of the media.'}, 'license': {'type': 'string', 'description': 'License for the media.'}, 'identifier': {'type': 'string', 'description': 'URL to the media file.'}}, 'description': 'A media item (image, audio, video) associated with the occurrence.', 'additionalProperties': False}, 'description': 'Associated media (images, audio, video). May be absent.'}, 'month': {'type': 'number', 'description': 'Observation month (1â\x80\x9312). May be absent.'}, 'order': {'type': 'string', 'description': 'Order classification.'}, 'family': {'type': 'string', 'description': 'Family classification.'}, 'issues': {'type': 'array', 'items': {'type': 'string'}, 'description': 'GBIF data quality issue flags.'}, 'phylum': {'type': 'string', 'description': 'Phylum classification.'}, 'country': {'type': 'string', 'description': 'Country name. May be absent.'}, 'kingdom': {'type': 'string', 'description': 'Kingdom classification.'}, 'species': {'type': 'string', 'description': 'Species canonical name.'}, 'classKey': {'type': 'number', 'description': 'Backbone taxon key for the class. May be absent.'}, 'locality': {'type': 'string', 'description': 'Locality description. May be absent.'}, 'taxonKey': {'type': 'number', 'description': 'Backbone taxon key.'}, 'continent': {'type': 'string', 'description': 'Continent name. May be absent.'}, 'eventDate': {'type': 'string', 'description': 'Observation date as ISO 8601 string. May be absent.'}, 'eventTime': {'type': 'string', 'description': 'Time of day of the observation, with seconds and UTC offset (e.g. 20:15:00+01:00) â\x80\x94 the offset eventDate omits when it carries a local time. May be absent.'}, 'lifeStage': {'type': 'string', 'description': 'Life stage of the individual(s). May be absent.'}, 'taxonRank': {'type': 'string', 'description': 'Taxonomic rank of the identified taxon.'}, 'datasetKey': {'type': 'string', 'description': 'UUID of the source dataset.'}, 'recordedBy': {'type': 'string', 'description': 'Collector name(s). May be absent.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code. May be absent.'}, 'identifiers': {'type': 'array', 'items': {'type': 'object', 'properties': {'type': {'type': 'string', 'description': 'Identifier type (e.g. URL, DOI, GBIF_PORTAL). May be absent.'}, 'identifier': {'type': 'string', 'description': 'The identifier value. May be absent.'}}, 'description': 'An alternative identifier for the occurrence record.', 'additionalProperties': False}, 'description': 'Alternative record identifiers from the source. May be absent.'}, 'identifiedBy': {'type': 'string', 'description': 'Identifier name(s). May be absent.'}, 'occurrenceID': {'type': 'string', 'description': 'Darwin Core occurrenceID â\x80\x94 the source record identifier, often a URL back to the origin record. May be absent.'}, 'basisOfRecord': {'type': 'string', 'description': 'How the occurrence was recorded.'}, 'canonicalName': {'type': 'string', 'description': 'Canonical name without authorship.'}, 'catalogNumber': {'type': 'string', 'description': 'Catalog number within the collection. May be absent.'}, 'stateProvince': {'type': 'string', 'description': 'State or province. May be absent.'}, 'collectionCode': {'type': 'string', 'description': 'Collection code within the institution. May be absent.'}, 'scientificName': {'type': 'string', 'description': 'Scientific name from occurrence record.'}, 'decimalLatitude': {'type': 'number', 'description': 'Latitude in decimal degrees (WGS84). May be absent.'}, 'individualCount': {'type': 'number', 'description': 'Number of individuals. May be absent.'}, 'institutionCode': {'type': 'string', 'description': 'Code of the contributing institution. May be absent.'}, 'taxonomicStatus': {'type': 'string', 'description': 'Status of the identification carried on this record â\x80\x94 ACCEPTED, PROVISIONALLY_ACCEPTED, SYNONYM, DOUBTFUL, and so on. Says whether the occurrence was filed under an accepted name or a synonym. May be absent.'}, 'decimalLongitude': {'type': 'number', 'description': 'Longitude in decimal degrees (WGS84). May be absent.'}, 'occurrenceStatus': {'type': 'string', 'description': 'PRESENT when the record asserts the taxon was there, ABSENT when it documents a survey that looked and did not find it. An ABSENT record is not a sighting â\x80\x94 it carries coordinates, a date, and a recorder all the same. May be absent.'}, 'publishingCountry': {'type': 'string', 'description': 'Country code of the publishing organization.'}, 'iucnRedListCategory': {'type': 'string', 'description': 'IUCN Red List category of the taxon â\x80\x94 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. May be absent.'}, 'coordinateUncertaintyInMeters': {'type': 'number', 'description': 'Coordinate uncertainty radius in meters. May be absent.'}}, 'additionalProperties': False}

{'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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'key': {'type': 'number', 'description': 'GBIF backbone taxon key.'}, 'rank': {'type': 'string', 'description': 'Taxonomic rank (SPECIES, GENUS, FAMILY, etc.).'}, 'class': {'type': 'string', 'description': 'Class classification.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The taxonKey does not exist in the GBIF backbone. `invalid_filter`: GBIF rejected the taxonKey as unparseable â\x80\x94 a fraction, or a value outside the 32-bit signed integer range. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'genus': {'type': 'string', 'description': 'Genus classification.'}, 'order': {'type': 'string', 'description': 'Order classification.'}, 'family': {'type': 'string', 'description': 'Family classification.'}, 'parent': {'type': 'string', 'description': 'Name of the immediate parent taxon.'}, 'phylum': {'type': 'string', 'description': 'Phylum classification.'}, 'extinct': {'type': 'boolean', 'description': 'True when the taxon is explicitly flagged as extinct. Absent on most records.'}, 'kingdom': {'type': 'string', 'description': 'Kingdom classification.'}, 'species': {'type': 'string', 'description': 'Species canonical name.'}, 'accepted': {'type': 'string', 'description': 'Scientific name of the accepted taxon when this record is a synonym.'}, 'classKey': {'type': 'number', 'description': 'Taxon key for the class.'}, 'genusKey': {'type': 'number', 'description': 'Taxon key for the genus.'}, 'orderKey': {'type': 'number', 'description': 'Taxon key for the order.'}, 'familyKey': {'type': 'number', 'description': 'Taxon key for the family.'}, 'parentKey': {'type': 'number', 'description': 'Taxon key of the immediate parent.'}, 'phylumKey': {'type': 'number', 'description': 'Taxon key for the phylum.'}, 'authorship': {'type': 'string', 'description': 'Taxonomic authorship of the name.'}, 'kingdomKey': {'type': 'number', 'description': 'Taxon key for the kingdom.'}, 'speciesKey': {'type': 'number', 'description': 'Taxon key for the species.'}, 'acceptedKey': {'type': 'number', 'description': 'Backbone key of the accepted taxon when this record is a synonym.'}, 'publishedIn': {'type': 'string', 'description': 'Original description citation when available.'}, 'canonicalName': {'type': 'string', 'description': 'Scientific name without authorship.'}, 'numDescendants': {'type': 'number', 'description': 'Count of child taxa in the backbone under this taxon.'}, 'numOccurrences': {'type': 'number', 'description': 'Occurrence record count in GBIF.'}, 'scientificName': {'type': 'string', 'description': 'Full scientific name with authorship.'}, 'vernacularName': {'type': 'string', 'description': 'English common name when available.'}, 'taxonomicStatus': {'type': 'string', 'description': 'ACCEPTED, SYNONYM, DOUBTFUL, etc. SYNONYM means acceptedKey/accepted are populated.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['taxonKey'], 'properties': {'limit': {'type': 'number', 'default': 20, 'maximum': 1000, '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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['children', 'offset', 'limit', 'endOfRecords']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'Limit applied when the result was truncated. Re-call with offset to page on.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The taxonKey does not exist in the GBIF backbone. `invalid_filter`: GBIF rejected the taxonKey as unparseable â\x80\x94 a fraction, or a value outside the 32-bit signed integer range. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'limit': {'type': 'number', 'description': 'Records returned in this page.'}, 'shown': {'type': 'number', 'description': 'Children returned in this page when the result was truncated.'}, 'notice': {'type': 'string', 'description': 'Agent guidance â\x80\x94 a no-children note for a valid taxon, or a pagination note when the page was capped. Absent on a complete single page.'}, 'offset': {'type': 'number', 'description': 'Current pagination offset.'}, 'children': {'type': 'array', 'items': {'type': 'object', 'properties': {'key': {'type': 'number', 'description': 'GBIF backbone taxon key.'}, 'rank': {'type': 'string', 'description': 'Taxonomic rank.'}, 'canonicalName': {'type': 'string', 'description': 'Scientific name without authorship.'}, 'numDescendants': {'type': 'number', 'description': 'Count of child taxa under this node.'}, 'numOccurrences': {'type': 'number', 'description': 'Occurrence record count.'}, 'scientificName': {'type': 'string', 'description': 'Full scientific name with authorship.'}, 'vernacularName': {'type': 'string', 'description': 'Common name when available.'}, 'taxonomicStatus': {'type': 'string', 'description': 'ACCEPTED, SYNONYM, DOUBTFUL, etc.'}}, 'description': 'A direct child taxon with key, name, rank, and status.', 'additionalProperties': False}, 'description': 'Direct child taxa.'}, 'truncated': {'type': 'boolean', 'description': 'True when more children exist beyond this page. Absent on the final page.'}, 'endOfRecords': {'type': 'boolean', 'description': 'True when there are no more results after this page.'}}, 'additionalProperties': False}

{'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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['classification']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `not_found`: The taxonKey does not exist in the GBIF backbone. `invalid_filter`: GBIF rejected the taxonKey as unparseable â\x80\x94 a fraction, or a value outside the 32-bit signed integer range. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Guidance when the chain is empty because the taxon sits at the root of the backbone. Absent when the chain has entries.'}, 'classification': {'type': 'array', 'items': {'type': 'object', 'properties': {'key': {'type': 'number', 'description': 'Backbone taxon key for this rank.'}, 'name': {'type': 'string', 'description': 'Canonical name at this rank.'}, 'rank': {'type': 'string', 'description': 'Taxonomic rank (KINGDOM, PHYLUM, CLASS, etc.).'}, 'scientificName': {'type': 'string', 'description': 'Full scientific name with authorship.'}}, 'description': 'A single rank entry in the classification chain.', 'additionalProperties': False}, 'description': 'Classification chain ordered from root (kingdom) to the immediate parent of the queried taxon. The queried taxon itself is not included â\x80\x94 call gbif_get_species for its own record.'}}, '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 â\x80\x94 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 â\x80\x94 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 â\x80\x94 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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rank': {'type': 'string', 'description': 'Taxonomic rank of the matched taxon.'}, 'class': {'type': 'string', 'description': 'Class of the matched taxon.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_match', 'invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `no_match`: matchType is NONE â\x80\x94 no candidate met the match threshold. `invalid_filter`: kingdom was supplied blank or whitespace-only, which disambiguates nothing. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'genus': {'type': 'string', 'description': 'Genus of the matched taxon.'}, 'order': {'type': 'string', 'description': 'Order of the matched taxon.'}, 'family': {'type': 'string', 'description': 'Family of the matched taxon.'}, 'notice': {'type': 'string', 'description': 'Guidance when the queried name was a synonym and taxonKey was resolved to the accepted taxon. Absent when the matched name is already the accepted one.'}, 'phylum': {'type': 'string', 'description': 'Phylum of the matched taxon.'}, 'status': {'type': 'string', 'description': 'Taxonomic status: ACCEPTED, SYNONYM, or DOUBTFUL.'}, 'kingdom': {'type': 'string', 'description': 'Kingdom of the matched taxon.'}, 'species': {'type': 'string', 'description': 'Species canonical name of the matched taxon.'}, 'classKey': {'type': 'number', 'description': 'Backbone taxon key for the class.'}, 'genusKey': {'type': 'number', 'description': 'Backbone taxon key for the genus.'}, 'orderKey': {'type': 'number', 'description': 'Backbone taxon key for the order.'}, 'taxonKey': {'type': 'number', 'description': "GBIF backbone taxon key to pass to downstream tools. The accepted taxon's key when the queried name is a synonym, otherwise the matched taxon's own key."}, 'familyKey': {'type': 'number', 'description': 'Backbone taxon key for the family.'}, 'matchType': {'type': 'string', 'description': 'EXACT, FUZZY, HIGHERRANK, or NONE. NONE means no usable match.'}, 'phylumKey': {'type': 'number', 'description': 'Backbone taxon key for the phylum.'}, 'confidence': {'type': 'number', 'description': 'Match confidence score 0â\x80\x93100. Below 80 warrants review.'}, 'kingdomKey': {'type': 'number', 'description': 'Backbone taxon key for the kingdom.'}, 'speciesKey': {'type': 'number', 'description': 'Backbone taxon key for the species.'}, 'canonicalName': {'type': 'string', 'description': 'Scientific name without authorship.'}, 'scientificName': {'type': 'string', 'description': 'Full scientific name with authorship.'}, 'matchedTaxonKey': {'type': 'number', 'description': 'Backbone key of the name that actually matched. Present only when it differs from taxonKey â\x80\x94 that is, when a synonym was resolved to its accepted taxon.'}}, 'additionalProperties': False}

{'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 â\x80\x94 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 dimension to split on when a result set is too large to page: every occurrence carries exactly one datasetKey, so its buckets sum to totalOccurrences with no gap and no overlap, and it has the cardinality to cut a large scope into pageable pieces. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free too and both have a matching filter on the occurrence tools, so either can drive a further split of a bucket still too large â\x80\x94 but on that same scope they return 9 and 41 buckets against DATASET_KEY's 550, so neither replaces it as the first cut. A dimension a record can lack silently drops that record: faceting one 60,290,950-record scope by YEAR returned 224 buckets summing to 59,407,400, leaving 883,550 undated records in no bucket at all, and MONTH, STATE_PROVINCE, and SPECIES_KEY lose records the same way â\x80\x94 stateProvince included, even though the occurrence tools can now filter on it. Sums are comparable only across the same occurrenceStatus scope."}, '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 â\x80\x94 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. Omit the field to aggregate everywhere â\x80\x94 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 â\x80\x94 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, 'maximum': 100, '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Ã\x97facetLimit, â\x80¦).'}, 'basisOfRecord': {'enum': ['HUMAN_OBSERVATION', 'MACHINE_OBSERVATION', 'PRESERVED_SPECIMEN', 'LIVING_SPECIMEN', 'MATERIAL_SAMPLE', 'MATERIAL_CITATION', 'OCCURRENCE', 'LITERATURE'], 'type': 'string', 'description': 'Scope to a specific basis of record.'}, 'stateProvince': {'type': 'string', 'description': 'State, province, or first-level administrative division, matched as a verbatim string â\x80\x94 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 â\x80\x94 a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.'}, '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 â\x80\x94 required to see both buckets when facet is OCCURRENCE_STATUS â\x80\x94 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 â\x80\x94 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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['facet', 'totalOccurrences', 'counts', 'facetLimit', 'facetOffset', 'occurrenceStatus']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'facetLimit applied when the page was capped. Re-call with facetOffset advanced by this value to page on. Absent otherwise.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_filter`: A scope filter was supplied blank or whitespace-only, datasetKey is not an 8-4-4-4-12 hex UUID, a two-letter country or publishingCountry code is one GBIF does not know, or GBIF rejected the geometry or year scope as malformed. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'facet': {'type': 'string', 'description': 'The facet dimension aggregated.'}, 'shown': {'type': 'number', 'description': 'Facet values returned in this page when the page was capped. Absent otherwise.'}, 'counts': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'count'], 'properties': {'name': {'type': 'string', 'description': 'Facet value (country code, year, basisOfRecord, etc.).'}, 'count': {'type': 'number', 'description': 'Occurrence count for this facet value.'}}, 'description': 'A facet value with its occurrence count.', 'additionalProperties': False}, 'description': 'Facet values ranked by count descending â\x80\x94 one page of up to facetLimit entries starting at facetOffset, not necessarily the top ones.'}, 'notice': {'type': 'string', 'description': 'Guidance when no facet values were returned, the page came back full and more values may remain, a verbatim stateProvince filter matched nothing, or a presence/absence filter narrowed the aggregation. Absent only when none applies.'}, 'truncated': {'type': 'boolean', 'description': 'Heuristic continuation flag: present and true when this page returned a full facetLimit of values, so more distinct values may exist past facetOffset + facetLimit. GBIF exposes no total distinct-value count, so this is an estimate, not exact. Absent when the page came back short, which is the only proof the ranking is exhausted.'}, 'facetLimit': {'type': 'number', 'description': 'Maximum facet values requested.'}, 'facetOffset': {'type': 'number', 'description': 'Zero-based offset applied to the ranked facet values.'}, 'occurrenceStatus': {'type': 'string', 'description': 'The presence/absence filter applied upstream â\x80\x94 PRESENT, ABSENT, or ANY when no filter was sent. Says what totalOccurrences and every bucket cover.'}, 'totalOccurrences': {'type': 'number', 'description': 'Total matching occurrences across all facet values.'}}, 'additionalProperties': False}

{'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 â\x80\x94 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, 'maximum': 1000, '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 â\x80\x94 matched case-sensitively, as publishingOrg is) of the organization whose installation serves the dataset â\x80\x94 not 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: of the first 25 GB organizations the registry lists, all 25 host no datasets while 13 publish one or two. Supplied together the two filters are intersected, not combined.'}, 'publishingOrg': {'type': 'string', 'description': 'UUID (8-4-4-4-12 hex, lowercase â\x80\x94 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 â\x80\x94 the organization whose data it is, and the question a key from gbif_search_publishers is usually asking. Not the organization that serves it, which is hostingOrg and matches a different set: Butterfly Conservation (0d72dd7f-6f05-46af-85c2-8b6e77ce5534) publishes 3 datasets and hosts none, while the National Biodiversity Network (07f617d0-c688-11d8-bf62-b8a03c50a862) hosts 984 â\x80\x94 those 3 among them â\x80\x94 and publishes 1. 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 â\x80\x94 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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['datasets', 'totalCount', 'offset', 'limit', 'endOfRecords']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_filter`: A filter was supplied blank or whitespace-only, publishingOrg or hostingOrg is not a lowercase 8-4-4-4-12 hex UUID, publishingCountry is a two-letter code GBIF does not assign, or GBIF rejected another filter value as malformed. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'limit': {'type': 'number', 'description': 'Datasets returned in this page.'}, 'notice': {'type': 'string', 'description': 'Guidance when results are empty or paging overshot. Absent on successful result pages.'}, 'offset': {'type': 'number', 'description': 'Current pagination offset.'}, 'datasets': {'type': 'array', 'items': {'type': 'object', 'properties': {'doi': {'type': 'string', 'description': 'DOI for citation. May be absent.'}, 'key': {'type': 'string', 'description': 'Dataset UUID for gbif_get_dataset chaining.'}, 'type': {'type': 'string', 'description': 'Dataset type (OCCURRENCE, CHECKLIST, etc.).'}, 'title': {'type': 'string', 'description': 'Dataset title.'}, 'license': {'type': 'string', 'description': 'License identifier. May be absent.'}, 'description': {'type': 'string', 'description': 'Brief description, truncated to a 300-character preview. May be absent.'}, 'recordCount': {'type': 'number', 'description': 'Occurrence records GBIF has indexed for this dataset, spanning every occurrenceStatus: absence records â\x80\x94 surveys that looked for a taxon and did not find it â\x80\x94 are counted alongside sightings, and on some datasets they are the overwhelming majority. For the sightings-only figure, call gbif_count_occurrences with this key; it defaults to occurrenceStatus PRESENT, so the two figures are expected to differ rather than one being wrong.'}, 'publishingCountry': {'type': 'string', 'description': 'Country code of the publisher.'}, 'descriptionTruncated': {'type': 'boolean', 'description': 'True when the description was shortened to the 300-char preview; call gbif_get_dataset with this key for the full text. Omitted when the dataset has no description.'}}, 'description': 'A GBIF dataset with key, title, type, license, and record count.', 'additionalProperties': False}, 'description': 'Matching datasets.'}, 'totalCount': {'type': 'number', 'description': 'Total matching datasets before pagination.'}, 'endOfRecords': {'type': 'boolean', 'description': 'True when there are no more results after this page.'}}, 'additionalProperties': False}

{'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 â\x80\x94 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, 'maximum': 300, 'minimum': 1, 'description': 'Number of records to return (default 20, max 300).'}, 'month': {'type': 'number', 'maximum': 12, 'minimum': 1, 'description': 'Calendar month (1â\x80\x9312). 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 â\x80\x94 gap-free and high-cardinality, unlike YEAR, which leaves undated records in no bucket â\x80\x94 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 â\x80\x94 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. Takes precedence over decimalLatitude/decimalLongitude. Omit the field to search everywhere â\x80\x94 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 â\x80\x94 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 â\x80\x94 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 â\x80\x94 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'], '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 â\x80\x94 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 â\x80\x94 an unmatched value returns zero records rather than an error. Omit the field to search every state or province â\x80\x94 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 â\x80\x94 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 â\x80\x94 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 â\x80\x94 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 â\x80\x94 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 â\x80\x94 not where the occurrence was observed, which is country. The two differ constantly: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations. 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 â\x80\x94 a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['occurrences', 'totalCount', 'offset', 'limit', 'endOfRecords', 'occurrenceStatus']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['pagination_cap_exceeded', 'invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `pagination_cap_exceeded`: offset + limit exceeds 100,001, the deepest page GBIF serves. `invalid_filter`: A filter value is unusable â\x80\x94 any filter supplied blank or whitespace-only, a datasetKey that is not an 8-4-4-4-12 hex UUID, a two-letter country or publishingCountry code GBIF does not know, or a WKT geometry or range GBIF rejects. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'limit': {'type': 'number', 'description': 'Records returned in this page.'}, 'notice': {'type': 'string', 'description': 'Guidance when results are empty, paging overshot, the match is larger than the pagination cap can reach, or a presence/absence filter narrowed the result. Absent only when none applies.'}, 'offset': {'type': 'number', 'description': 'Current pagination offset.'}, 'totalCount': {'type': 'number', 'description': 'Total matching occurrences before pagination.'}, 'occurrences': {'type': 'array', 'items': {'type': 'object', 'properties': {'day': {'type': 'number', 'description': 'Observation day. May be absent.'}, 'key': {'type': 'number', 'description': 'GBIF occurrence key for gbif_get_occurrence chaining.'}, 'rank': {'type': 'string', 'description': 'Taxonomic rank of the identified taxon.'}, 'year': {'type': 'number', 'description': 'Observation year. May be absent.'}, 'month': {'type': 'number', 'description': 'Observation month (1â\x80\x9312). May be absent.'}, 'issues': {'type': 'array', 'items': {'type': 'string'}, 'description': 'GBIF data quality issue flags for this record.'}, 'country': {'type': 'string', 'description': 'Country name. May be absent.'}, 'locality': {'type': 'string', 'description': 'Locality description. May be absent.'}, 'taxonKey': {'type': 'number', 'description': 'Backbone taxon key.'}, 'eventDate': {'type': 'string', 'description': 'Observation date as ISO 8601 string. May be absent.'}, 'eventTime': {'type': 'string', 'description': 'Time of day of the observation, with seconds and UTC offset (e.g. 20:15:00+01:00) â\x80\x94 the offset eventDate omits when it carries a local time. May be absent.'}, 'datasetKey': {'type': 'string', 'description': 'UUID of the source dataset.'}, 'recordedBy': {'type': 'string', 'description': 'Collector name(s). May be absent.'}, 'countryCode': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code. May be absent.'}, 'datasetName': {'type': 'string', 'description': 'Name of the source dataset. May be absent.'}, 'basisOfRecord': {'type': 'string', 'description': 'How the occurrence was recorded.'}, 'canonicalName': {'type': 'string', 'description': 'Canonical name without authorship.'}, 'stateProvince': {'type': 'string', 'description': 'State or province name. May be absent.'}, 'scientificName': {'type': 'string', 'description': 'Scientific name from occurrence record.'}, 'decimalLatitude': {'type': 'number', 'description': 'Latitude in decimal degrees (WGS84). May be absent.'}, 'individualCount': {'type': 'number', 'description': 'Number of individuals. May be absent.'}, 'taxonomicStatus': {'type': 'string', 'description': 'Status of the identification carried on this record â\x80\x94 ACCEPTED, PROVISIONALLY_ACCEPTED, SYNONYM, DOUBTFUL, and so on. Says whether the occurrence was filed under an accepted name or a synonym. May be absent.'}, 'decimalLongitude': {'type': 'number', 'description': 'Longitude in decimal degrees (WGS84). May be absent.'}, 'occurrenceStatus': {'type': 'string', 'description': 'PRESENT when the record asserts the taxon was there, ABSENT when it documents a survey that looked and did not find it. An ABSENT record is not a sighting. May be absent.'}, 'publishingCountry': {'type': 'string', 'description': 'Country code of the publishing organization.'}, 'iucnRedListCategory': {'type': 'string', 'description': 'IUCN Red List category of the taxon â\x80\x94 CR, EN, VU, NT, LC, DD, EX, EW, or CD. May be absent.'}, 'coordinateUncertaintyInMeters': {'type': 'number', 'description': 'Coordinate uncertainty radius in meters. May be absent.'}}, 'description': 'A single occurrence record with location, taxon, date, and provenance fields.', 'additionalProperties': False}, 'description': 'Occurrence records matching the filters.'}, 'endOfRecords': {'type': 'boolean', 'description': 'True when there are no more results after this page.'}, 'occurrenceStatus': {'type': 'string', 'description': 'The presence/absence filter applied upstream â\x80\x94 PRESENT, ABSENT, or ANY when no filter was sent. Says what totalCount and the returned records cover.'}}, '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 â\x80\x94 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, 'maximum': 1000, '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 â\x80\x94 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}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['publishers', 'totalCount', 'offset', 'limit', 'endOfRecords']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_filter'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_filter`: q was supplied blank or whitespace-only, country is the empty string, or GBIF could not parse the country value as a country. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'limit': {'type': 'number', 'description': 'Organizations returned in this page.'}, 'notice': {'type': 'string', 'description': 'Guidance when results are empty or paging overshot. Absent on successful result pages.'}, 'offset': {'type': 'number', 'description': 'Current pagination offset.'}, 'publishers': {'type': 'array', 'items': {'type': 'object', 'properties': {'key': {'type': 'string', 'description': 'Organization UUID. Chains into gbif_search_datasets as publishingOrg for the datasets this organization published, or as hostingOrg for the ones its own installation serves â\x80\x94 publishingOrg is the usual one, since most organizations host nothing.'}, 'city': {'type': 'string', 'description': 'City. May be absent.'}, 'title': {'type': 'string', 'description': 'Organization name.'}, 'country': {'type': 'string', 'description': 'ISO 3166-1 alpha-2 country code.'}}, 'description': 'A GBIF-registered publishing organization.', 'additionalProperties': False}, 'description': 'Matching organizations.'}, 'totalCount': {'type': 'number', 'description': 'Total matching organizations before pagination.'}, 'endOfRecords': {'type': 'boolean', 'description': 'True when there are no more results after this page.'}}, 'additionalProperties': False}

{'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 â\x80\x94 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 â\x80\x94 "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, 'maximum': 1000, 'minimum': 1, 'description': 'Number of records to return (default 20, max 1000).'}, 'family': {'type': 'string', 'description': 'Scope the search to a family, by name â\x80\x94 "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 â\x80\x94 "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 â\x80\x94 "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 â\x80\x94 an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered backbone result.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['taxa', 'totalCount', 'offset', 'limit', 'endOfRecords']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'taxa': {'type': 'array', 'items': {'type': 'object', 'properties': {'key': {'type': 'number', 'description': 'GBIF backbone taxon key.'}, 'rank': {'type': 'string', 'description': 'Taxonomic rank.'}, 'class': {'type': 'string', 'description': 'Class classification.'}, 'genus': {'type': 'string', 'description': 'Genus classification.'}, 'order': {'type': 'string', 'description': 'Order classification.'}, 'family': {'type': 'string', 'description': 'Family classification.'}, 'phylum': {'type': 'string', 'description': 'Phylum classification.'}, 'extinct': {'type': 'boolean', 'description': 'True when explicitly flagged as extinct.'}, 'kingdom': {'type': 'string', 'description': 'Kingdom classification.'}, 'canonicalName': {'type': 'string', 'description': 'Scientific name without authorship.'}, 'numDescendants': {'type': 'number', 'description': 'Count of child taxa in the backbone.'}, 'numOccurrences': {'type': 'number', 'description': 'Occurrence record count in GBIF.'}, 'scientificName': {'type': 'string', 'description': 'Full scientific name with authorship.'}, 'vernacularName': {'type': 'string', 'description': 'Common name when available.'}, 'taxonomicStatus': {'type': 'string', 'description': 'ACCEPTED, SYNONYM, DOUBTFUL, etc.'}}, 'description': 'A backbone taxon with classification, status, and occurrence counts.', 'additionalProperties': False}, 'description': 'Matching taxa.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_filter', 'unresolved_taxon_scope', 'conflicting_taxon_scope'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_filter`: q, kingdom, family, genus, or datasetKey was supplied blank or whitespace-only, datasetKey is not an 8-4-4-4-12 hex UUID, or GBIF rejected another filter value as malformed. `unresolved_taxon_scope`: kingdom, family, or genus named no GBIF backbone taxon at that rank â\x80\x94 a misspelling, a lowercase name, a name entered under the wrong rank, or a name shared across kingdoms with no kingdom supplied to separate them. `conflicting_taxon_scope`: the supplied family and genus each resolved, but to taxa in different lineages â\x80\x94 the genus does not sit in that family. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'limit': {'type': 'number', 'description': 'Records returned in this page.'}, 'notice': {'type': 'string', 'description': 'Guidance when results are empty or paging overshot. Absent on successful result pages.'}, 'offset': {'type': 'number', 'description': 'Current pagination offset.'}, 'taxonScope': {'type': 'string', 'description': 'The higher-taxon scope actually applied â\x80\x94 which of kingdom, family, or genus scoped the search, the backbone taxon its name resolved to, and that taxon key. Absent when none of the three was supplied.'}, 'totalCount': {'type': 'number', 'description': 'Total matches before pagination.'}, 'endOfRecords': {'type': 'boolean', 'description': 'True when there are no more results after this page.'}}, 'additionalProperties': False}