# GBIF Biodiversity Scraper — Species & Occurrences (`hipersoft/gbif-species-scraper`) Actor

Search GBIF's global biodiversity database in bulk. Get species taxonomy (kingdom to genus, rank, status) or occurrence records (coordinates, country, date, basis of record). Filter occurrences by country, year and coordinates. Export to JSON, CSV or Excel.

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

## Pricing

from $0.0004 / record scraped

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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 Biodiversity Scraper — Species & Occurrences

Search and export **GBIF** — the Global Biodiversity Information Facility — into clean **JSON, CSV, Excel or XML**. Pull **species taxonomy** (scientific name, rank, full kingdom-to-genus classification, taxonomic status) or **occurrence records** (geographic coordinates, country, observation date, basis of record, source dataset) for any organism in GBIF's billion-record biodiversity index.

Built for researchers, ecologists, conservation teams and data pipelines that need structured biodiversity data at scale instead of clicking through the GBIF portal one page at a time.

### What does the GBIF Biodiversity Scraper do?

Give it a name to search — a scientific name like `Panthera leo`, a genus, or a common word like `oak` — pick a **mode**, and the actor paginates through GBIF and returns one clean row per result:

- **Species mode** — one row per taxon: `scientificName`, `canonicalName`, `rank`, the full taxonomy (`kingdom`, `phylum`, `class`, `order`, `family`, `genus`), `status` and `numDescendants`.
- **Occurrences mode** — one row per recorded observation: `scientificName`, `country`, `decimalLatitude`, `decimalLongitude`, `eventDate`, `basisOfRecord` and `datasetName`.

### What data can you get?

#### Species mode

| Field | Type | Description |
| --- | --- | --- |
| `key` | integer | GBIF taxon key (unique taxon identifier) |
| `scientificName` | string | Full scientific name, including authorship where available |
| `canonicalName` | string | Canonical name without authorship |
| `rank` | string | Taxonomic rank, e.g. `SPECIES`, `GENUS`, `FAMILY` |
| `kingdom` | string | Kingdom in the classification |
| `phylum` | string | Phylum in the classification |
| `class` | string | Class in the classification |
| `order` | string | Order in the classification |
| `family` | string | Family in the classification |
| `genus` | string | Genus in the classification |
| `status` | string | Taxonomic status, e.g. `ACCEPTED`, `SYNONYM` |
| `numDescendants` | integer | Number of descendant taxa under this taxon |

#### Occurrences mode

| Field | Type | Description |
| --- | --- | --- |
| `key` | integer | GBIF occurrence key (unique record identifier) |
| `scientificName` | string | Scientific name recorded for the observation |
| `country` | string | Country where the organism was recorded |
| `decimalLatitude` | number | Latitude in decimal degrees |
| `decimalLongitude` | number | Longitude in decimal degrees |
| `eventDate` | string | Date the observation was made |
| `basisOfRecord` | string | Record basis, e.g. `HUMAN_OBSERVATION`, `PRESERVED_SPECIMEN` |
| `datasetName` | string | Name of the source dataset that published the record |

### Use cases

- **Ecology & conservation research** — map where a species has been recorded and how many observations exist over time.
- **Taxonomy lookups** — resolve a name to its GBIF taxon key and full classification for downstream enrichment.
- **Species distribution modelling** — pull georeferenced occurrence points for a taxon, filtered by country and year.
- **Biodiversity dashboards** — feed clean, structured records into your own analytics or mapping tools.
- **Education** — build teaching datasets of species and their real-world observation records.

### How to use it

1. Add the GBIF Biodiversity Scraper to your Apify account and open the input form.
2. Choose a **Mode** — `species` for taxonomy, `occurrences` for observation records.
3. Enter a **Search query** (e.g. `Panthera leo`).
4. For occurrences, optionally filter by **Country** (ISO2 code), **Year**, and whether records must have **coordinates**.
5. Set **Max items** to cap the export, then **Run**.
6. **Export** the dataset as JSON, CSV, Excel or XML, or pull it via the Apify API.

### Input

```json
{
  "mode": "occurrences",
  "query": "Panthera leo",
  "country": "KE",
  "hasCoordinate": true,
  "maxItems": 500
}
```

| Field | Type | Description |
| --- | --- | --- |
| `mode` | string | `species` (taxonomy) or `occurrences` (observation records). |
| `query` | string | Free-text search term, usually a scientific or common name. |
| `rank` | string | Species mode: restrict to a single rank (e.g. `SPECIES`, `GENUS`). |
| `country` | string | Occurrences mode: ISO 3166-1 alpha-2 country code (e.g. `KE`). |
| `year` | integer | Occurrences mode: filter to a single observation year. |
| `hasCoordinate` | boolean | Occurrences mode: only records that carry coordinates. |
| `maxItems` | integer | Maximum records to return (default 1000). |

### Output

```json
{
  "key": 5013750474,
  "scientificName": "Panthera leo (Linnaeus, 1758)",
  "country": "Kenya",
  "decimalLatitude": -1.399759,
  "decimalLongitude": 34.906483,
  "eventDate": "2013-10-15T00:00",
  "basisOfRecord": "HUMAN_OBSERVATION",
  "datasetName": "iNaturalist research-grade observations"
}
```

### FAQ

**What is GBIF?**
GBIF (Global Biodiversity Information Facility) is an open-data network that aggregates species and occurrence records from museums, herbaria, research projects and citizen-science platforms worldwide.

**How many records can I get?**
As many as your search returns — GBIF holds billions of occurrence records. Use **Max items** to cap a run and keep it cheap.

**How does billing work?**
You pay only per record you get, so small, tightly filtered runs stay inexpensive.

**What export formats are supported?**
JSON, CSV, Excel and XML, plus direct access via the Apify API.

**Can I use this with n8n?**
Yes. Run the GBIF Biodiversity Scraper from n8n with the [Apify node](https://n8n.io/integrations/apify/) — trigger a run, wait for it to finish, and read the dataset items straight into your workflow to enrich records, build maps or drive alerts. It also works with [Make](https://apify.com/integrations/make), [Zapier](https://apify.com/integrations/zapier) and the [Apify API](https://docs.apify.com/api/v2).

**Can I connect this to other tools?**
The GBIF Biodiversity Scraper connects with almost any cloud service or web app through [integrations on the Apify platform](https://apify.com/integrations) — [Make](https://apify.com/integrations/make), [Zapier](https://apify.com/integrations/zapier), [Slack](https://docs.apify.com/platform/integrations/slack), [Google Drive](https://docs.apify.com/platform/integrations/drive) and [many more](https://apify.com/integrations), plus [webhooks](https://docs.apify.com/platform/integrations/webhooks) to trigger an action whenever a run finishes.

**Is this only public data?**
Yes. It returns only openly published biodiversity data. You are responsible for compliance with GBIF's terms and the licence of each source dataset.

### Notes

Original clean-room implementation. Not affiliated with GBIF. Data is contributed by GBIF's publishing network and made available under open licences; cite the original datasets where required.

# Actor input Schema

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

What to search. "species" returns one row per taxon (scientific name, rank, full taxonomy, status). "occurrences" returns one row per recorded observation (coordinates, country, date, basis of record).

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

Free-text search term, typically a scientific or common name, e.g. "Panthera leo", "oak", "Apis mellifera". Leave empty to browse the full dataset (occurrences mode) filtered by the options below.

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

Species mode only: restrict results to a single taxonomic rank. Leave empty for all ranks.

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

Occurrences mode only: 2-letter ISO 3166-1 alpha-2 country code to filter records by where the observation was made, e.g. "KE" for Kenya, "US", "SG". Leave empty for all countries.

## `year` (type: `integer`):

Occurrences mode only: filter records to a single observation year, e.g. 2013. Leave empty for all years.

## `hasCoordinate` (type: `boolean`):

Occurrences mode only: when enabled, return only observation records that carry decimal latitude/longitude coordinates.

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

Maximum number of records to return across all pages.

## Actor input object example

```json
{
  "mode": "species",
  "query": "Panthera leo",
  "rank": "",
  "country": "KE",
  "hasCoordinate": false,
  "maxItems": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

The scraped results as dataset items.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("hipersoft/gbif-species-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("hipersoft/gbif-species-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 '{}' |
apify call hipersoft/gbif-species-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hipersoft/gbif-species-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/pzKikXT7OPTp21Pef/builds/6G8JTwH0TdV8dsWZL/openapi.json