# GBIF Scraper (`crawlerbros/gbif-scraper`) Actor

Scrape GBIF (Global Biodiversity Information Facility), 2.7B+ biodiversity occurrence records and 10M+ species. Search species taxonomy, browse occurrence records, explore contributing datasets, or fetch species details with vernacular names.

- **URL**: https://apify.com/crawlerbros/gbif-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Developer tools, Other, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## GBIF Scraper

Extract biodiversity data from **GBIF (Global Biodiversity Information Facility)** — the world's most comprehensive open-access biodiversity database with **2.7 billion+ occurrence records** and **10 million+ species**. No API key required.

### What Does GBIF Scraper Do?

GBIF Scraper gives you structured access to the GBIF public API. You can:

- **Search species** across the GBIF taxonomic backbone — by name, rank, or kingdom
- **Search occurrences** — individual biodiversity observations from museums, citizen science, and research institutions worldwide
- **Search datasets** — find contributing data providers and observation datasets
- **Fetch species details** — full taxonomy plus vernacular (common) names in many languages

***

### Output Fields

#### Species Records (modes: `searchSpecies`, `bySpeciesKey`)

| Field | Type | Description |
|---|---|---|
| `taxonKey` | Integer | GBIF taxon key (unique species identifier) |
| `scientificName` | String | Full scientific name with authorship |
| `canonicalName` | String | Canonical scientific name (no authorship) |
| `vernacularName` | String | Primary vernacular/common name |
| `vernacularNames` | Array | All vernacular names (mode=bySpeciesKey only) |
| `authorship` | String | Taxonomic authorship |
| `rank` | String | Taxonomic rank (KINGDOM, SPECIES, etc.) |
| `kingdom` | String | Kingdom classification |
| `phylum` | String | Phylum classification |
| `taxonClass` | String | Class classification |
| `order` | String | Order classification |
| `family` | String | Family classification |
| `genus` | String | Genus classification |
| `species` | String | Species binomial name |
| `taxonomicStatus` | String | Accepted, synonym, etc. |
| `numOccurrences` | Integer | Total occurrence count in GBIF |
| `numDescendants` | Integer | Number of child taxa |
| `habitat` | String | Habitat type |
| `threatStatuses` | Array | IUCN threat status codes |
| `synonym` | Boolean | Whether this is a synonym |
| `gbifSpeciesUrl` | String | Direct GBIF species page URL |

#### Occurrence Records (mode: `searchOccurrences`)

| Field | Type | Description |
|---|---|---|
| `occurrenceKey` | Integer | GBIF occurrence key |
| `speciesKey` | Integer | GBIF species key |
| `scientificName` | String | Scientific name of observed organism |
| `decimalLatitude` | Float | Latitude (WGS84) |
| `decimalLongitude` | Float | Longitude (WGS84) |
| `country` | String | ISO 3166-1 alpha-2 country code |
| `stateProvince` | String | State or province |
| `locality` | String | Locality description |
| `year` | Integer | Year of observation |
| `month` | Integer | Month of observation |
| `day` | Integer | Day of observation |
| `basisOfRecord` | String | How the occurrence was recorded |
| `institutionCode` | String | Contributing institution code |
| `datasetKey` | String | Contributing dataset key |
| `gbifOccurrenceUrl` | String | Direct GBIF occurrence page URL |

#### Dataset Records (mode: `searchDatasets`)

| Field | Type | Description |
|---|---|---|
| `datasetKey` | String | GBIF dataset UUID |
| `title` | String | Dataset title |
| `type` | String | Dataset type |
| `publishingOrganizationTitle` | String | Publishing organization name |
| `license` | String | Dataset license |
| `description` | String | Dataset description |
| `recordCount` | Integer | Total record count |
| `gbifDatasetUrl` | String | Direct GBIF dataset page URL |

***

### Input Configuration

#### Modes

| Mode | Description |
|---|---|
| `searchSpecies` | Search the GBIF taxonomic backbone |
| `searchOccurrences` | Search biodiversity occurrence records |
| `searchDatasets` | Search contributing datasets |
| `bySpeciesKey` | Fetch full species detail with vernacular names |

#### Input Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `mode` | Enum | `searchSpecies` | Operating mode |
| `query` | String | — | Scientific or common name query |
| `rank` | Enum | Any | Taxonomic rank filter (SPECIES, GENUS, etc.) |
| `kingdom` | Enum | Any | Kingdom filter (ANIMALIA, PLANTAE, etc.) |
| `taxonKey` | Integer | — | GBIF taxon key for occurrence filtering |
| `country` | String | — | ISO 3166-1 alpha-2 country code |
| `fromYear` | Integer | — | Filter occurrences from this year |
| `toYear` | Integer | — | Filter occurrences until this year |
| `basisOfRecord` | Enum | Any | How the occurrence was recorded |
| `datasetType` | Enum | Any | Dataset type filter |
| `speciesKey` | Integer | — | GBIF species key (mode=bySpeciesKey) |
| `maxItems` | Integer | 50 | Maximum number of records (1–1000) |

***

### Example Inputs

#### Search for lion taxonomy

```json
{
  "mode": "searchSpecies",
  "query": "Panthera leo",
  "maxItems": 10
}
```

#### Find all lion occurrences in South Africa

```json
{
  "mode": "searchOccurrences",
  "taxonKey": 5219404,
  "country": "ZA",
  "maxItems": 100
}
```

#### Fetch full species detail with vernacular names

```json
{
  "mode": "bySpeciesKey",
  "speciesKey": 5219404
}
```

#### Search oak tree species

```json
{
  "mode": "searchSpecies",
  "query": "Quercus",
  "rank": "GENUS",
  "kingdom": "PLANTAE",
  "maxItems": 50
}
```

#### Search occurrence datasets

```json
{
  "mode": "searchDatasets",
  "query": "bird",
  "datasetType": "OCCURRENCE",
  "maxItems": 20
}
```

#### Get recent bird observations in the US

```json
{
  "mode": "searchOccurrences",
  "query": "Corvus",
  "country": "US",
  "fromYear": 2020,
  "toYear": 2024,
  "basisOfRecord": "HUMAN_OBSERVATION",
  "maxItems": 200
}
```

***

### Use Cases

- **Biodiversity research**: Aggregate species distribution data for ecological analysis
- **Conservation planning**: Identify species ranges, threat statuses, and occurrence hotspots
- **Citizen science analytics**: Analyze iNaturalist and eBird observation patterns
- **Museum data mining**: Access digitized natural history collection records
- **Environmental impact assessment**: Map species presence in geographic areas
- **Species distribution modeling**: Collect training data for SDM algorithms
- **Education**: Explore taxonomy, biogeography, and biodiversity patterns

***

### Frequently Asked Questions

**Do I need a GBIF account?**
No. GBIF's public API is freely accessible without registration.

**How current is the data?**
GBIF continuously ingests new occurrence data from partners. The API reflects the current state of the database.

**What does `taxonKey` mean?**
Each species or taxon in GBIF has a unique numeric key. You can find a species key via `searchSpecies` and use it in `searchOccurrences` to get all observations of that species.

**What are basis of record types?**

- `HUMAN_OBSERVATION`: Sighted and recorded by a person (e.g., iNaturalist)
- `PRESERVED_SPECIMEN`: Museum or herbarium specimen
- `MACHINE_OBSERVATION`: Sensor, camera trap, or acoustic monitor
- `FOSSIL_SPECIMEN`: Paleontological specimen

**Can I filter by specific geographic regions?**
Yes — use the `country` field with a 2-letter ISO country code (e.g., `US`, `GB`, `ZA`).

**What is `coordinateUncertaintyInMeters`?**
The radius around the given coordinates within which the true location lies. Lower values indicate more precise georeferencing.

**Are vernacular names available in multiple languages?**
Yes — use `mode=bySpeciesKey` to retrieve vernacular names across all languages registered in GBIF for that species.

# Actor input Schema

## `mode` (type: `string`):

What to fetch from GBIF.

## `query` (type: `string`):

Scientific or common name to search (mode=searchSpecies, searchOccurrences, searchDatasets). E.g. `Panthera leo`, `lion`, `oak`.

## `rank` (type: `string`):

Filter species results by taxonomic rank (mode=searchSpecies).

## `kingdom` (type: `string`):

Filter species results by kingdom (mode=searchSpecies).

## `taxonKey` (type: `integer`):

GBIF taxon key to filter occurrence records (mode=searchOccurrences). Obtain from a searchSpecies run.

## `country` (type: `string`):

ISO 3166-1 alpha-2 country code to filter occurrences, e.g. `US`, `GB`, `DE`, `ZA`. (mode=searchOccurrences)

## `fromYear` (type: `integer`):

Filter occurrences observed on or after this year (mode=searchOccurrences).

## `toYear` (type: `integer`):

Filter occurrences observed on or before this year (mode=searchOccurrences).

## `basisOfRecord` (type: `string`):

How the occurrence was recorded (mode=searchOccurrences).

## `datasetType` (type: `string`):

Filter by dataset type (mode=searchDatasets).

## `speciesKey` (type: `integer`):

GBIF species/taxon key for detail lookup with vernacular names (mode=bySpeciesKey).

## `maxItems` (type: `integer`):

Maximum number of records to return.

## Actor input object example

```json
{
  "mode": "searchSpecies",
  "query": "Panthera leo",
  "rank": "",
  "kingdom": "",
  "taxonKey": 5219404,
  "basisOfRecord": "",
  "datasetType": "",
  "speciesKey": 5219404,
  "maxItems": 5
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing all scraped GBIF records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "searchSpecies",
    "query": "Panthera leo",
    "rank": "",
    "kingdom": "",
    "taxonKey": 5219404,
    "basisOfRecord": "",
    "datasetType": "",
    "speciesKey": 5219404,
    "maxItems": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/gbif-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "searchSpecies",
    "query": "Panthera leo",
    "rank": "",
    "kingdom": "",
    "taxonKey": 5219404,
    "basisOfRecord": "",
    "datasetType": "",
    "speciesKey": 5219404,
    "maxItems": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/gbif-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "searchSpecies",
  "query": "Panthera leo",
  "rank": "",
  "kingdom": "",
  "taxonKey": 5219404,
  "basisOfRecord": "",
  "datasetType": "",
  "speciesKey": 5219404,
  "maxItems": 5
}' |
apify call crawlerbros/gbif-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/gbif-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/9NiEVmgOcmEsUTZYr/builds/FnwQWZkBvAAwsVTsu/openapi.json