# GBIF Species Occurrences Scraper (`compute-edge/gbif-species-occurrences-scraper`) Actor Extract species occurrence records from GBIF, the Global Biodiversity Information Facility (2B+ records). Filter by scientific name, country, taxon, year, and basis of record. Returns taxonomy, coordinates, dates, dataset provenance, and collector metadata for biodiversity and ESG research. - **URL**: https://apify.com/compute-edge/gbif-species-occurrences-scraper.md - **Developed by:** [Compute Edge](https://apify.com/compute-edge) (community) - **Categories:** Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Species Occurrences Scraper Extract structured biodiversity occurrence records from the **Global Biodiversity Information Facility (GBIF)** — the world's largest open-access repository of species occurrence data. This Actor queries the free GBIF API and returns clean JSON records with taxonomic classification, geographic coordinates, collection dates, and dataset provenance for conservation research, ecological analysis, and species distribution modeling. GBIF aggregates occurrence records from thousands of institutions worldwide — museums, herbaria, citizen science initiatives, and research organizations. A single search can return millions of historical and contemporary observations spanning centuries of biodiversity data. ### Key Features - **Global occurrence database access** — Query 2+ billion species observations with no authentication required - **Taxonomic filtering** — Filter by scientific name, taxon key, or multiple ranks (kingdom, phylum, class, order, family, genus, species) - **Geographic filtering** — Restrict results by country, coordinates, or location polygon - **Temporal filtering** — Filter by year or year range (e.g., "2020" or "2010,2020") - **Record type filtering** — Isolate human observations, museum specimens, fossil records, or experimental observations - **Coordinate validation** — Option to return only records with verified GPS coordinates - **Pagination handling** — Automatic batching with GBIF's 300-record-per-page limit; respects 100k deep-paging offset cap - **Dataset provenance** — Retain dataset name, publication key, institution code, and license for proper attribution - **Clean JSON output** — All fields mapped to safe names (e.g., `taxonClass` instead of `class`) ready for analysis pipelines ### Output Data Fields | Field | Type | Description | |-------|------|-------------| | `key` | integer | GBIF unique occurrence identifier | | `scientificName` | string | Species scientific name (e.g., Panthera leo) | | `kingdom` | string | Kingdom classification (e.g., Animalia, Plantae, Fungi) | | `phylum` | string | Phylum classification | | `taxonClass` | string | Class classification (mapped from `class`) | | `taxonOrder` | string | Order classification (mapped from `order`) | | `family` | string | Family name | | `genus` | string | Genus name | | `species` | string | Species epithet | | `taxonRank` | string | Taxonomic rank of the record | | `country` | string | Country name | | `countryCode` | string | 2-letter ISO country code | | `stateProvince` | string | State or province | | `locality` | string | Specific locality description | | `decimalLatitude` | number | Latitude (WGS84) | | `decimalLongitude` | number | Longitude (WGS84) | | `elevation` | number | Elevation in meters (above sea level) | | `depth` | number | Depth in meters (below water surface) | | `eventDate` | string | Date of observation (ISO format) | | `year` | integer | Year of observation | | `month` | integer | Month of observation (1-12) | | `day` | integer | Day of observation | | `basisOfRecord` | string | Record type (HUMAN_OBSERVATION, SPECIMEN, OBSERVATION, FOSSIL_SPECIMEN, etc.) | | `occurrenceStatus` | string | Status (PRESENT, ABSENT) | | `individualCount` | integer | Number of individuals observed | | `datasetName` | string | Name of the dataset contributing the record | | `datasetKey` | string | GBIF dataset UUID | | `publishingOrgKey` | string | GBIF organization UUID of the data publisher | | `institutionCode` | string | Museum/institution acronym | | `collectionCode` | string | Collection identifier within the institution | | `catalogNumber` | string | Catalog ID within the collection | | `recordedBy` | string | Observer/collector name | | `identifiedBy` | string | Person who identified the specimen | | `license` | string | Data license (e.g., CC_BY_4_0, CC0_1_0) | | `lastInterpreted` | string | Date GBIF last interpreted/validated the record | ### How to Scrape GBIF Species Occurrence Data 1. Navigate to the **GBIF Species Occurrences Scraper** Actor page on Apify Store. 2. Click **Start** to open the input configuration form. 3. (Optional) Enter a **Scientific Name** to filter by species (e.g., "Panthera leo", "Quercus", "Drosophila"). 4. (Optional) Enter a **Country** ISO code to limit results to one country (e.g., "US", "BR", "ZA"). 5. (Optional) Enter a **Taxon Key** to filter by GBIF's unique taxon identifier. 6. (Optional) Enter a **Year Range** to filter by observation date (e.g., "2020" for a single year or "2010,2020" for a range). 7. (Optional) Toggle **Has Coordinates** to only return records with GPS coordinates. 8. (Optional) Enter a **Basis of Record** filter (e.g., "HUMAN_OBSERVATION", "SPECIMEN"). 9. Set **Max Results** to control output size (default: 1000, set to 0 for unlimited, max 100000). 10. Click **Start** to run the Actor. 11. Download results as JSON, CSV, or Excel from the **Dataset** tab. ### Input Example ```json { "scientificName": "Panthera leo", "country": "ZA", "year": "2015,2024", "hasCoordinate": true, "basisOfRecord": "HUMAN_OBSERVATION", "maxResults": 500 } ```` ### Output Example ```json { "key": 4156523045, "scientificName": "Panthera leo", "kingdom": "Animalia", "phylum": "Chordata", "taxonClass": "Mammalia", "taxonOrder": "Carnivora", "family": "Felidae", "genus": "Panthera", "species": "leo", "taxonRank": "SPECIES", "country": "South Africa", "countryCode": "ZA", "stateProvince": "Kruger National Park", "locality": "Central section", "decimalLatitude": -24.56, "decimalLongitude": 31.82, "elevation": 380, "depth": null, "eventDate": "2020-06-15", "year": 2020, "month": 6, "day": 15, "basisOfRecord": "HUMAN_OBSERVATION", "occurrenceStatus": "PRESENT", "individualCount": 1, "datasetName": "African Mammal Sightings", "datasetKey": "98e50e68-6ecb-4dca-ab8b-b0e3eabc1234", "publishingOrgKey": "1234a5bc-d67e-8f90-1234-567a890123ab", "institutionCode": "SANBI", "collectionCode": "MAMMAL", "catalogNumber": "ZA2020-06-15-001", "recordedBy": "Jane Smith", "identifiedBy": "Dr. John Doe", "license": "CC_BY_4_0", "lastInterpreted": "2021-03-10T12:34:56" } ``` ### Pricing This Actor queries the free GBIF API with automatic pagination. Compute costs depend on result volume. - **Cost per run**: ~$0.001 for small queries (< 1000 records), ~$0.005-0.01 for large queries (10k+ records) - **Actor start event**: Default platform rate - **Per-result pricing**: $0.003/result Typical run time is 30 seconds for 1000 records, up to several minutes for 50k+ records due to pagination. ### Use Cases - **Conservation planning** — Map species distributions by country/region to inform protected area designation - **Climate change research** — Analyze occurrence trends over time to assess range shifts in response to warming - **Invasive species monitoring** — Track the geographic spread of non-native species using historical records - **Biodiversity assessment** — Quantify species richness and endemism in target regions - **Museum collection analytics** — Export specimen metadata from natural history collections for cataloging - **Citizen science validation** — Retrieve expert-verified occurrence records to train models on observation quality - **Ecological niche modeling** — Feed occurrence records into MaxEnt or other ENM algorithms - **Taxonomic research** — Gather all known specimens of a genus to study morphological variation ### FAQ #### Is it legal to scrape GBIF data? Yes. GBIF is a public, open-access repository of biodiversity data. The API is free and requires no authentication. Most records are published under open licenses (CC\_BY\_4\_0 or CC0\_1\_0). Always check the `license` field and cite the dataset and publishing organization per their requirements. #### How many records can I retrieve? GBIF hosts 2+ billion occurrence records. The API has a hard limit of 100,000 records per search (due to deep paging limitations). For larger datasets, filter by taxon, country, or date range to narrow results. Schedule multiple runs targeting different subsets. #### What does "Basis of Record" mean? It indicates the source type of the occurrence: - **HUMAN\_OBSERVATION** — Direct observation by a person (e.g., field sighting, photo) - **SPECIMEN** — Museum or herbarium specimen - **OBSERVATION** — Observation of unknown source - **FOSSIL\_SPECIMEN** — Fossilized remains - **LIVING\_SPECIMEN** — Alive specimen (e.g., in zoo or botanic garden) #### Can I export GBIF data to Excel or CSV? Yes. Apify supports exporting results in JSON, CSV, Excel, XML, and other formats directly from the Dataset tab after a run completes. #### What does a null value in `eventDate` mean? It means GBIF did not have a specific date for that occurrence record. Dates may be missing for historical specimens or citizen observations without timestamp metadata. The `year`, `month`, and `day` fields may also be null independently. #### How often is GBIF updated? GBIF receives new data continuously from connected institutions. Updates can happen daily. Schedule this Actor to run periodically to capture newly published occurrences. ### Other Scrapers by SeatSignal - [CISA Known Exploited Vulnerabilities Scraper](https://apify.com/seatsignal/cisa-kev-scraper) — Extract CVE threat intelligence - [NIST NVD Scraper](https://apify.com/seatsignal/nist-nvd-scraper) — Extract National Vulnerability Database records - [Hotfrog Business Directory Scraper](https://apify.com/seatsignal/hotfrog-scraper) — Extract business listings and contact info ### Legal Disclaimer This Actor extracts publicly available biodiversity data from the GBIF API. GBIF data is published by institutions under various open licenses (primarily CC\_BY\_4\_0 or CC0\_1\_0). Users are responsible for respecting individual dataset licenses and providing proper attribution to data publishers and GBIF. Ensure your use complies with applicable laws and the terms of any derived datasets. For support, contact the Actor developer through the Apify Store. # Actor input Schema ## `scientificName` (type: `string`): Filter by scientific name (full or partial). Examples: 'Panthera leo', 'Quercus', 'Drosophila'. ## `country` (type: `string`): Filter by country using 2-letter ISO country code. Examples: 'US', 'BR', 'ZA', 'AU'. ## `taxonKey` (type: `integer`): Filter by GBIF taxon key (unique identifier for a taxon). Look up on gbif.org. ## `year` (type: `string`): Filter by year or year range (YYYY or YYYY,YYYY). Examples: '2020' or '2010,2020' for range. ## `hasCoordinate` (type: `boolean`): If enabled, only include records with geographic coordinates (latitude/longitude). ## `basisOfRecord` (type: `string`): Filter by record type. Examples: 'HUMAN\_OBSERVATION', 'SPECIMEN', 'OBSERVATION', 'FOSSIL\_SPECIMEN'. ## `maxResults` (type: `integer`): Maximum number of occurrence records to return. Set to 0 for unlimited (capped at 100000 by GBIF). ## Actor input object example ```json { "scientificName": "", "country": "", "taxonKey": 0, "year": "", "hasCoordinate": false, "basisOfRecord": "", "maxResults": 1000 } ``` # Actor output Schema ## `dataset` (type: `string`): No description # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("compute-edge/gbif-species-occurrences-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("compute-edge/gbif-species-occurrences-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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 compute-edge/gbif-species-occurrences-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=compute-edge/gbif-species-occurrences-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "GBIF Species Occurrences Scraper", "description": "Extract species occurrence records from GBIF, the Global Biodiversity Information Facility (2B+ records). Filter by scientific name, country, taxon, year, and basis of record. Returns taxonomy, coordinates, dates, dataset provenance, and collector metadata for biodiversity and ESG research.", "version": "0.1", "x-build-id": "TT51c9UhCcoEPU2QP" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/compute-edge~gbif-species-occurrences-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-compute-edge-gbif-species-occurrences-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/compute-edge~gbif-species-occurrences-scraper/runs": { "post": { "operationId": "runs-sync-compute-edge-gbif-species-occurrences-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/compute-edge~gbif-species-occurrences-scraper/run-sync": { "post": { "operationId": "run-sync-compute-edge-gbif-species-occurrences-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "scientificName": { "title": "Scientific Name", "type": "string", "description": "Filter by scientific name (full or partial). Examples: 'Panthera leo', 'Quercus', 'Drosophila'.", "default": "" }, "country": { "title": "Country (ISO Code)", "type": "string", "description": "Filter by country using 2-letter ISO country code. Examples: 'US', 'BR', 'ZA', 'AU'.", "default": "" }, "taxonKey": { "title": "Taxon Key", "type": "integer", "description": "Filter by GBIF taxon key (unique identifier for a taxon). Look up on gbif.org.", "default": 0 }, "year": { "title": "Year Range", "type": "string", "description": "Filter by year or year range (YYYY or YYYY,YYYY). Examples: '2020' or '2010,2020' for range.", "default": "" }, "hasCoordinate": { "title": "Has Coordinates", "type": "boolean", "description": "If enabled, only include records with geographic coordinates (latitude/longitude).", "default": false }, "basisOfRecord": { "title": "Basis of Record", "type": "string", "description": "Filter by record type. Examples: 'HUMAN_OBSERVATION', 'SPECIMEN', 'OBSERVATION', 'FOSSIL_SPECIMEN'.", "default": "" }, "maxResults": { "title": "Max Results", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of occurrence records to return. Set to 0 for unlimited (capped at 100000 by GBIF).", "default": 1000 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```