GnistAI GnistAI
Log in

Getting Started with GBIF Biodiversity

Global biodiversity data — species occurrences, taxonomy, and datasets from the Global Biodiversity Information Facility.

All Tutorials   |   Overview   |   Playground   |   MCP   |   REST API   |   Home
Science

Data source: GBIF (Global Biodiversity Information Facility)

Overview

GBIF Biodiversity wraps GBIF (Global Biodiversity Information Facility), handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

  1. Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
  2. Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config 
{
  "mcpServers": {
    "gnist-gbif": {
      "url": "https://context.gnist.ai/mcp/gbif/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

search_species

Search the GBIF taxonomy backbone for species, genera, families, or higher taxa. Covers 2.4M+ species from the GBIF backbone taxonomy — the most comprehensive global species catalogue. Returns scientific names, common names, taxonomic hierarchy, and occurrence counts. Data aggregated from 2,100+ institutions worldwide. Args: query: Species name or keyword to search. rank: Taxonomic rank filter. habitat: Habitat filter. limit: Number of results (1–50, default 20). Returns: List of matching taxa with scientific name, common name, classification, and occurrence count. Use the key with get_species or search_occurrences for details.

ParameterTypeRequiredDescription
querystringrequiredSpecies name or keyword (e.g. "Panthera leo", "orchid", "Atlantic salmon", "pine").
rankanyoptionalTaxonomic rank filter: SPECIES, GENUS, FAMILY, ORDER, CLASS, PHYLUM, KINGDOM. Omit for all.
habitatanyoptionalHabitat filter: MARINE, FRESHWATER, TERRESTRIAL. Omit for all.
limitintegeroptionalNumber of results (1–50, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/gbif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_species", "arguments": {"query": "Panthera leo"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'Panthera leo'}, 'name': 'search_species'}},
)
print(resp.json())

get_species

Get full taxonomic details for a species by its GBIF taxon key. Returns the complete classification hierarchy from kingdom to species, plus status and occurrence count. Args: taxon_key: GBIF taxon key (numeric). Returns: Full taxonomic record. Returns found=false if key not found.

ParameterTypeRequiredDescription
taxon_keystringrequiredGBIF taxon key (numeric). Found in search_species results.
curl -X POST "https://context.gnist.ai/mcp/gbif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_species", "arguments": {"taxon_key": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'taxon_key': 'example'}, 'name': 'get_species'}},
)
print(resp.json())

search_occurrences

Search 2.4B+ biodiversity occurrence records — species sightings, specimens, and observations. Each record is a documented observation of a species at a specific place and time. Sources include museum specimens, citizen science (eBird, iNaturalist), research surveys, and automated monitoring. Covers all of life — animals, plants, fungi, bacteria. Args: taxon_key: GBIF taxon key. Use search_species to find it. scientific_name: Scientific name as alternative to taxon_key. country: ISO country code to filter by location. year_range: Year or year range filter. basis_of_record: Filter by observation type. has_coordinate: Only records with GPS coordinates. limit: Number of results (1–50, default 20). Returns: List of occurrence records with species, location, date, observer, and source dataset.

ParameterTypeRequiredDescription
taxon_keyanyoptionalGBIF taxon key (numeric). Use search_species to find keys. Provide this or scientific_name.
scientific_nameanyoptionalScientific name (e.g. "Panthera leo"). Alternative to taxon_key.
countryanyoptionalISO 3166-1 alpha-2 country code (e.g. 'NO' for Norway, 'US', 'GB').
year_rangeanyoptionalYear or year range (e.g. '2023' or '2020,2024' for a range).
basis_of_recordanyoptionalRecord type: HUMAN_OBSERVATION, PRESERVED_SPECIMEN, MACHINE_OBSERVATION, FOSSIL_SPECIMEN, LIVING_SPECIMEN.
has_coordinateanyoptionalFilter to records with GPS coordinates.
limitintegeroptionalNumber of results (1–50, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/gbif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_occurrences", "arguments": {"taxon_key": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'taxon_key': 'example'},
            'name': 'search_occurrences'}},
)
print(resp.json())

search_datasets

Search 100K+ biodiversity datasets published through GBIF. Datasets are collections of occurrence records or species checklists published by institutions, museums, citizen science platforms, and research projects. Args: query: Search term for dataset titles and descriptions. type_filter: Filter by dataset type. publishing_country: Filter by country of the publishing organization. limit: Number of results (1–50, default 20). Returns: List of datasets with title, description, type, publisher, and record count.

ParameterTypeRequiredDescription
querystringrequiredDataset search term (e.g. "birds Norway", "marine mammals", "eBird", "herbarium").
type_filteranyoptionalDataset type: OCCURRENCE, CHECKLIST, SAMPLING_EVENT, METADATA.
publishing_countryanyoptionalISO 3166-1 alpha-2 code of the publishing country.
limitintegeroptionalNumber of results (1–50, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/gbif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_datasets", "arguments": {"query": "birds Norway"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'birds Norway'}, 'name': 'search_datasets'}},
)
print(resp.json())

get_species_distribution

Get the global distribution of a species — occurrence counts by country. Shows which countries a species has been observed in and how many records exist. Useful for understanding species range, conservation status, and biodiversity hotspots. Args: taxon_key: GBIF taxon key (numeric). Returns: List of countries with occurrence counts, sorted by count (highest first).

ParameterTypeRequiredDescription
taxon_keystringrequiredGBIF taxon key (numeric). Use search_species to find it.
curl -X POST "https://context.gnist.ai/mcp/gbif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_species_distribution", "arguments": {"taxon_key": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'taxon_key': 'example'},
            'name': 'get_species_distribution'}},
)
print(resp.json())

report_feedback

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: general)
curl -X POST "https://context.gnist.ai/mcp/gbif/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbif/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_species to find items, then get_species to get full details. This two-step pattern is common for exploring data before drilling down.
Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does GBIF Biodiversity provide?

Global biodiversity data — species occurrences, taxonomy, and datasets from the Global Biodiversity Information Facility. It exposes 6 tools: search_species, get_species, search_occurrences, search_datasets, get_species_distribution, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the GBIF Biodiversity API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground
Try tools in your browser — no setup required.
Full Reference
Complete docs for all 6 tools.

Related Tutorials

Academic Research
Tutorial
Health Research
Tutorial
Environmental Monitoring
Tutorial
Research Funding
Tutorial
arXiv
Tutorial
ClinicalTrials.gov
Tutorial