GBIF icon

GBIF

GBIF provides free and open access to biodiversity data

Actions22

  • Collection Actions
  • Dataset Actions
  • Dataset Search Actions
  • Installation Actions
  • Institution Actions
  • Occurrence Actions
  • Occurrence Count Actions
  • Occurrence Search Actions
  • Occurrence Search Catalog Number Actions
  • Occurrence Search Collection Code Actions
  • Occurrence Search Occurrence ID Actions
  • Occurrence Search Recorded By Actions
  • Occurrence Search Record Number Actions
  • Occurrence Search Institution Code Actions
  • Organization Actions
  • Name Parser Actions
  • Network Actions
  • Node Actions
  • Species Actions
  • Species Match Actions
  • Species Search Actions
  • Species Suggest Actions

Species Search → Get

AI-generated

Overview

The "Species Search - Get" operation in this node allows users to perform detailed searches for species data using the GBIF (Global Biodiversity Information Facility) API. It supports a full-text query and numerous filters related to taxonomy, conservation status, habitat, nomenclature, and more. This node is beneficial for biodiversity researchers, ecologists, conservationists, and data scientists who need to retrieve structured species information from GBIF's extensive biodiversity database.

Practical examples include:

  • Searching for species by name or phrase with additional filters like extinction status or habitat.
  • Filtering species by taxonomic rank or nomenclatural status.
  • Retrieving species threatened status such as "Endangered" or "Critically Endangered".
  • Faceting results by various categories to analyze species distribution or classification.

Properties

Name Meaning
Query (q) A simple full-text search parameter; can be a word or phrase to search species names or descriptions.
Additional Fields A collection of optional filters and parameters to refine the search:
- Dataset Key Filter species by a specific checklist dataset key (UUID).
- Facet Allows faceted search on fields such as Constituent Key, Dataset Key, Habitat, Higher Taxon Key, Is Extinct, Issue, Name Type, Nomenclatural Status, Rank, Status, Threat, and Type.
- Facet Minimum Count Sets a minimum count threshold for facets to be included in the response (e.g., exclude facets with counts less than 1000).
- Habitat Filter species by habitat type: Freshwater, Marine, Terrestrial.
- Higher Taxon Key Filter by higher Linnean rank keys within the respective checklist.
- Is Extinct Boolean filter to include only extinct or non-extinct species.
- Issue Filter by indexing issues such as accepted name missing, homonym, nomenclatural status invalid, etc.
- Name Type Filter by name types like Blacklisted, Candidatus, Cultivar, Doubtful, Hybrid, Informal, Scientific, Virus, etc.
- Nomenclatural Status Filter by nomenclatural statuses such as Aborted, Alternative, Ambiguous, Conserved, Denied, Doubtful, Illegitimate, Invalid, Legitimate, New Combination, etc.
- Rank Filter by taxonomic rank, e.g., Aberration, Biovar, Class, Family, Genus, Species, Subspecies, Variety, etc.
- Source ID Filter by source identifier.
- Status Filter by taxonomic status: Accepted, Doubtful, Synonym, Heterotypic Synonym, Homotypic Synonym, Proparte Synonym, Misapplied.
- Threat Filter by threat status: Critically Endangered, Data Deficient, Endangered, Extinct, Extinct In The Wild, Least Concern, Near Threatened, Not Applicable, Not Evaluated, Regionally Extinct, Vulnerable.

Output

The output is a JSON array containing the species data returned by the GBIF API based on the search criteria. Each item in the array represents a species record with detailed fields corresponding to the GBIF species endpoint response. This includes taxonomic details, nomenclatural information, conservation status, and other metadata.

No binary data output is produced by this node.

Dependencies

  • External Service: GBIF public API (https://api.gbif.org/v1)
  • No special credentials or API keys are required as the GBIF API is publicly accessible.
  • The node uses HTTP GET requests to fetch data from the GBIF API endpoints.

Troubleshooting

  • Empty Results: If no species are returned, verify that the query string (q) and filters are correctly set and that they match existing data in GBIF.
  • Invalid Filter Values: Using unsupported or misspelled filter values (e.g., incorrect taxonomic ranks or statuses) may result in errors or empty responses.
  • API Rate Limits: Although GBIF API is public, excessive requests might be throttled. Consider adding delays or limiting request frequency.
  • Network Issues: Ensure network connectivity to api.gbif.org.
  • Malformed Requests: Check that multi-option filters (like facets or issues) are properly formatted as arrays.

Common error messages typically come from the GBIF API and indicate invalid parameters or server issues. Review the parameters and try again if errors occur.

Links and References

This summary covers the "Species Search" resource with the "Get" operation, focusing on its input properties, output structure, dependencies, and usage considerations.

Discussion