GBIF Biodiversity Search

Search the Global Biodiversity Information Facility (GBIF) -- the world's largest open biodiversity database with over 2.5 billion occurrence records from more than 80,000 datasets. This Apify actor lets you search for species taxonomy information and geographic occurrence records without writing any code or managing API pagination. Whether you are tracking endangered species distributions, building ecological datasets, or monitoring biodiversity patterns, this actor delivers structured, export-ready data from GBIF's taxonomic backbone and occurrence index.

---

Why use GBIF Biodiversity Search?

GBIF aggregates biodiversity data from natural history museums, citizen science platforms like iNaturalist and eBird, government agencies, and research institutions worldwide. It is the single most comprehensive source of species occurrence data on the planet -- but working with its API directly requires handling pagination logic, taxon key resolution, and response normalization.

This actor eliminates that complexity. Enter a species name -- common or scientific -- and choose between two search modes: species search for taxonomy and classification data, or occurrence search for individual sighting and specimen records with GPS coordinates, dates, and collection metadata.

The output is clean, flat JSON ready for analysis in spreadsheets, databases, GIS tools, or downstream data pipelines. Every record includes a direct link back to the original GBIF page for verification and citation.

No API key is required. GBIF's public API is free and open, and this actor handles all the pagination, name resolution, and data transformation for you automatically.

---

Key features

• Dual search modes -- Search for species taxonomy information or individual occurrence (sighting/specimen) records from the same actor.
• Automatic taxon resolution -- When searching occurrences, the actor first resolves your query against GBIF's taxonomic backbone to find the correct taxon key, ensuring accurate results even with common names.
• Full taxonomic hierarchy -- Species results include the complete classification chain: kingdom, phylum, class, order, family, genus, and rank.
• English common names -- The actor prefers English vernacular names when available, falling back to the first available common name in any language.
• Geographic occurrence data -- Occurrence results include latitude and longitude coordinates, country, event date, and basis of record (preserved specimen, human observation, machine observation, etc.).
• Country and year filtering -- Narrow occurrence searches to a specific ISO country code or year range to focus on the data you need.
• Taxonomic rank filtering -- Filter species results by rank (kingdom, phylum, class, order, family, genus, or species) to control the scope of your search.
• Automatic pagination -- The actor handles GBIF's pagination limits (100 per page for species, 300 per page for occurrences) transparently, collecting up to 500 results per run.
• Direct GBIF links -- Every output record includes a gbifUrl field linking directly to the record on gbif.org for citation and verification.
• No API key required -- GBIF's API is completely free and open. No registration or authentication needed.

---

How to use

Using the Apify Console

1. Navigate to the GBIF Biodiversity Search actor page on Apify.
2. Click the Try for free button to open the actor in the Apify Console.
3. Enter a species name in the Species Name field -- for example, Panthera tigris or tiger.
4. Select the Search Type -- choose Species Info for taxonomy data or Occurrence Records for sighting and specimen records.
5. Optionally set filters: Country Code (e.g., IN for India), Taxonomic Rank, or Year (e.g., 2024 or 2020,2024).
6. Set the Max Results to control how many records to return (1--500, default 50).
7. Click Start to run the actor.
8. When the run finishes, view your results in the Dataset tab. Export to JSON, CSV, Excel, or connect via API.

Using the API

curl "https://api.apify.com/v2/acts/ryanclinton~gbif-species-search/runs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "query": "Panthera tigris",
    "searchType": "species",
    "maxResults": 50
  }'

Replace YOUR_API_TOKEN with your Apify API token. The response includes a defaultDatasetId you can use to fetch results at https://api.apify.com/v2/datasets/{datasetId}/items?format=json.

---

Input parameters

Name	Type	Required	Default	Description
query	String	Yes	"Panthera tigris"	Species name to search for -- accepts both common names (e.g., "tiger") and scientific names (e.g., "Panthera tigris").
searchType	String	No	"species"	Search mode: "species" for taxonomy and classification data, or "occurrences" for individual sighting and specimen records.
country	String	No	--	Two-letter ISO 3166-1 alpha-2 country code to filter occurrence records (e.g., "US", "GB", "BR"). Only applies to occurrence search.
rank	String	No	--	Filter species results by taxonomic rank: KINGDOM, PHYLUM, CLASS, ORDER, FAMILY, GENUS, or SPECIES. Only applies to species search.
year	String	No	--	Year or year range for occurrence records. Use a single year like "2024" or a range like "2020,2024". Only applies to occurrence search.
maxResults	Integer	No	50	Maximum number of results to return. Minimum 1, maximum 500.

Example input (species search):

{
    "query": "Ursus arctos",
    "searchType": "species",
    "rank": "SPECIES",
    "maxResults": 25
}

Example input (occurrence search):

{
    "query": "Canis lupus",
    "searchType": "occurrences",
    "country": "US",
    "year": "2023,2025",
    "maxResults": 100
}

Practical tips:

• Use scientific names for the most precise results. Common names like "eagle" or "oak" may match many species across different families and genera.
• When searching occurrences, the actor resolves your query to a GBIF taxon key first. If the name cannot be matched, it falls back to a raw scientificName search, which may return fewer or less accurate results.
• The year parameter supports GBIF's range syntax -- use "2020,2024" to search from 2020 through 2024 inclusive.

---

Output

The actor produces different output fields depending on the search type.

Species search output example:

{
    "gbifKey": 5219404,
    "scientificName": "Panthera tigris (Linnaeus, 1758)",
    "canonicalName": "Panthera tigris",
    "commonName": "Tiger",
    "kingdom": "Animalia",
    "phylum": "Chordata",
    "className": "Mammalia",
    "order": "Carnivora",
    "family": "Felidae",
    "genus": "Panthera",
    "rank": "SPECIES",
    "taxonomicStatus": "ACCEPTED",
    "numOccurrences": 38542,
    "gbifUrl": "https://www.gbif.org/species/5219404",
    "extractedAt": "2026-02-19T10:30:00.000Z"
}

Species output fields:

Field	Type	Description
gbifKey	Number	Unique GBIF species key identifier.
scientificName	String	Full scientific name including author citation.
canonicalName	String	Scientific name without author citation (e.g., "Panthera tigris").
commonName	String	English vernacular name if available, otherwise the first available common name.
kingdom	String	Taxonomic kingdom (e.g., "Animalia", "Plantae").
phylum	String	Taxonomic phylum (e.g., "Chordata", "Magnoliophyta").
className	String	Taxonomic class (e.g., "Mammalia", "Aves").
order	String	Taxonomic order (e.g., "Carnivora", "Primates").
family	String	Taxonomic family (e.g., "Felidae", "Canidae").
genus	String	Taxonomic genus (e.g., "Panthera", "Ursus").
rank	String	Taxonomic rank of this record (KINGDOM, PHYLUM, CLASS, ORDER, FAMILY, GENUS, SPECIES).
taxonomicStatus	String	Status in the GBIF backbone: ACCEPTED, SYNONYM, DOUBTFUL, etc.
numOccurrences	Number	Total number of occurrence records in GBIF for this taxon.
gbifUrl	String	Direct link to the species page on gbif.org.
extractedAt	String	ISO 8601 timestamp of when the record was extracted.

Occurrence search output example:

{
    "gbifKey": 4518907623,
    "scientificName": "Panthera tigris (Linnaeus, 1758)",
    "country": "India",
    "latitude": 23.4891,
    "longitude": 80.3321,
    "eventDate": "2024-03-15",
    "basisOfRecord": "HUMAN_OBSERVATION",
    "datasetName": "iNaturalist Research-grade Observations",
    "institutionCode": "iNaturalist",
    "catalogNumber": "182345678",
    "recordedBy": "",
    "gbifUrl": "https://www.gbif.org/occurrence/4518907623",
    "extractedAt": "2026-02-19T10:30:00.000Z"
}

Occurrence output fields:

Field	Type	Description
gbifKey	Number	Unique GBIF occurrence key identifier.
scientificName	String	Scientific name of the observed or collected organism.
country	String	Country where the occurrence was recorded.
latitude	Number or null	Decimal latitude of the occurrence location (null if not georeferenced).
longitude	Number or null	Decimal longitude of the occurrence location (null if not georeferenced).
eventDate	String	Date of the observation or collection event (ISO format or year-month-day).
basisOfRecord	String	Type of record: HUMAN_OBSERVATION, PRESERVED_SPECIMEN, MACHINE_OBSERVATION, FOSSIL_SPECIMEN, MATERIAL_SAMPLE, LIVING_SPECIMEN, or LITERATURE.
datasetName	String	Name of the GBIF dataset this record belongs to.
institutionCode	String	Code of the institution holding the specimen or managing the observation.
catalogNumber	String	Catalog number assigned by the holding institution.
recordedBy	String	Name of the person who recorded the observation or collected the specimen.
gbifUrl	String	Direct link to the occurrence record on gbif.org.
extractedAt	String	ISO 8601 timestamp of when the record was extracted.

---

Use cases

• Conservation research -- Track the geographic distribution of endangered species like the Amur leopard (Panthera pardus orientalis) or California condor (Gymnogyps californianus) by querying occurrence records filtered by country and year.
• Ecological modeling -- Extract georeferenced occurrence data with latitude and longitude coordinates for species distribution modeling (SDM) and niche analysis.
• Invasive species monitoring -- Search for occurrence records of invasive species like the Asian giant hornet (Vespa mandarinia) in specific countries to track range expansion over time.
• Taxonomic reference -- Look up the full classification hierarchy, accepted name, and synonym status of any species in the GBIF taxonomic backbone.
• Biodiversity assessments -- Quantify species richness for a taxonomic group (e.g., all species in family Orchidaceae) by searching with rank filters and examining occurrence counts.
• Citizen science data analysis -- Extract iNaturalist and eBird observation records aggregated through GBIF to analyze volunteer contribution patterns and data quality.
• Museum collection audits -- Search occurrence records filtered by basisOfRecord to find PRESERVED_SPECIMEN records from natural history museum collections worldwide.
• Environmental impact studies -- Gather baseline biodiversity data for a geographic area by searching for occurrences within a specific country and timeframe before and after a development project.
• Academic publications -- Retrieve GBIF data with direct citation links (gbifUrl) for use in peer-reviewed research papers and reports.
• Education and outreach -- Build interactive species databases or biodiversity dashboards using the structured output from this actor.

---

API & integration

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run_input = {
    "query": "Aquila chrysaetos",
    "searchType": "occurrences",
    "country": "US",
    "year": "2024",
    "maxResults": 100,
}

run = client.actor("ryanclinton/gbif-species-search").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['scientificName']} -- {item['country']} ({item['latitude']}, {item['longitude']})")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("ryanclinton/gbif-species-search").call({
    query: "Gorilla gorilla",
    searchType: "species",
    rank: "SPECIES",
    maxResults: 25,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.log(`${item.commonName} (${item.scientificName}) -- ${item.numOccurrences} occurrences`);
});

cURL

# Start the actor run
curl "https://api.apify.com/v2/acts/ryanclinton~gbif-species-search/runs?token=YOUR_API_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Humpback whale",
    "searchType": "occurrences",
    "country": "AU",
    "maxResults": 50
  }'

# Fetch results (replace DATASET_ID with defaultDatasetId from the run response)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?format=json&token=YOUR_API_TOKEN"

This actor integrates with all Apify platform features including scheduled runs, webhooks, and direct integrations with tools like Google Sheets, Slack, Zapier, Make (Integromat), and custom APIs. Set up a scheduled run to monitor occurrence records for a species on a weekly or monthly basis and get notified when new data appears.

---

How it works

1. Input validation -- The actor reads your input parameters and validates that a species name query has been provided. It selects the appropriate search pipeline based on the searchType parameter.

2. Species search pipeline -- For species searches, the actor queries GBIF's /species/search endpoint with your query string. It applies optional rank filtering and handles pagination in batches of up to 100 records per request until the requested number of results is collected or no more records remain.

3. Taxon key resolution -- For occurrence searches, the actor first calls GBIF's /species/match endpoint to resolve your query (common or scientific name) to a precise taxon key in the GBIF taxonomic backbone. This ensures that occurrence results are accurate and include child taxa.

4. Occurrence search pipeline -- Using the resolved taxon key (or falling back to a raw scientific name query), the actor queries the /occurrence/search endpoint. It applies optional country and year filters and paginates in batches of up to 300 records per request.

5. Data transformation -- Each raw GBIF record is normalized into a clean, flat output object. Species records get their best available English common name extracted from vernacular name arrays. Occurrence records get their dates normalized and coordinates extracted.

6. Output delivery -- All transformed records are pushed to the Apify dataset, ready for export in JSON, CSV, Excel, XML, or RSS formats, or for consumption via the Apify API.

+------------------+
                        |   Input: query,  |
                        |   searchType,    |
                        |   filters        |
                        +--------+---------+
                                 |
                    +------------+------------+
                    |                         |
             searchType =              searchType =
              "species"               "occurrences"
                    |                         |
                    v                         v
          +------------------+    +---------------------+
          | /species/search  |    | /species/match      |
          | ?q=query         |    | ?name=query         |
          | &rank=RANK       |    | (resolve taxon key) |
          +--------+---------+    +----------+----------+
                   |                         |
                   |                         v
                   |              +---------------------+
                   |              | /occurrence/search  |
                   |              | ?taxonKey=N         |
                   |              | &country=XX         |
                   |              | &year=YYYY          |
                   |              +----------+----------+
                   |                         |
                   v                         v
          +------------------+    +---------------------+
          | Paginate batches |    | Paginate batches    |
          | (100 per page)   |    | (300 per page)      |
          +--------+---------+    +----------+----------+
                   |                         |
                   +------------+------------+
                                |
                                v
                   +------------------------+
                   | Transform & normalize  |
                   | records to flat JSON   |
                   +------------+-----------+
                                |
                                v
                   +------------------------+
                   | Push to Apify dataset  |
                   +------------------------+

---

Performance & cost

Metric	Details
Average run time	5--15 seconds for 50 results; 15--45 seconds for 500 results. Occurrence searches with taxon resolution add 1--2 seconds for the initial match request.
Compute units	Approximately 0.001--0.005 CU per run depending on result count. Runs well within Apify's free tier for moderate usage.
Memory usage	Minimal -- the actor uses the default 256 MB memory allocation. No browser or headless rendering is required.
API rate limits	GBIF does not enforce strict rate limits for reasonable usage, but the actor processes requests sequentially to be a responsible API consumer.
Network requests	1 request per 100 species results or per 300 occurrence results, plus 1 additional request for taxon key resolution in occurrence mode. A 500-result species search makes approximately 5 requests.
Cost estimate	Most runs cost less than $0.01 in Apify platform credits. Free tier users get enough monthly credits for hundreds of runs.

---

Limitations

• Maximum 500 results per run -- GBIF contains millions of records for common species. This actor caps output at 500 results per run to keep runs fast and predictable. For larger datasets, use multiple runs with different filters or access the GBIF API directly.
• No geographic bounding box filter -- Occurrence searches can be filtered by country code but not by arbitrary latitude/longitude bounding boxes. Use the country parameter or post-process coordinates from the output.
• Taxon resolution depends on GBIF backbone -- If your query does not match any name in the GBIF taxonomic backbone (e.g., misspelled names or very obscure taxa), occurrence search falls back to a raw scientific name query which may return fewer results.
• Occurrence coordinate availability varies -- Not all occurrence records in GBIF are georeferenced. Some records will have null values for latitude and longitude, particularly older museum specimen records.
• No media or image data -- The actor returns metadata fields only. It does not extract images, sounds, or other media associated with occurrence records.
• Year filter applies to occurrence search only -- The year and country parameters are ignored when performing a species search. Similarly, the rank parameter is ignored for occurrence searches.
• GBIF data quality varies -- GBIF aggregates data from thousands of sources with varying quality standards. Some records may contain coordinate errors, taxonomic misidentifications, or incomplete metadata.

---

Responsible use

• Cite GBIF in publications -- If you use data from this actor in research or publications, cite GBIF as the data source. Each record's gbifUrl links to the original page with full citation information and DOI references.
• Respect data licensing -- GBIF data is published under Creative Commons licenses (CC0, CC BY, or CC BY-NC). Individual datasets may have specific usage terms. Check the dataset page on gbif.org before commercial use.
• Use reasonable result limits -- While GBIF's API is free and open, requesting large volumes of data consumes shared infrastructure. Use appropriate maxResults values and apply filters to narrow your queries.
• Do not redistribute raw data without attribution -- If you share or republish GBIF-derived datasets, provide proper attribution to the original data publishers and GBIF as the aggregation platform.
• Verify critical identifications -- For conservation decisions, environmental assessments, or regulatory purposes, verify species identifications and occurrence locations against primary sources rather than relying solely on aggregated GBIF data.

---

FAQ

Q: Do I need a GBIF account or API key to use this actor? A: No. GBIF's API is completely free and open -- no registration, API key, or authentication is required. This actor accesses the same public API endpoints available to anyone.

Q: Can I search using common names like "tiger" instead of scientific names? A: Yes. Both common names and scientific names work in the query field. For species searches, GBIF matches against both scientific and vernacular names. For occurrence searches, the actor first resolves your query to a taxon key, which works with common names that GBIF recognizes.

Q: What is the difference between species search and occurrence search? A: Species search returns taxonomy and classification information -- one record per matching taxon with its scientific name, common name, full taxonomic hierarchy, and total occurrence count. Occurrence search returns individual sighting and specimen records -- each with GPS coordinates, date, collector information, and the source dataset.

Q: How do I search for occurrences in a specific country? A: Set the country parameter to a two-letter ISO 3166-1 alpha-2 country code. For example, use "US" for the United States, "BR" for Brazil, "IN" for India, "AU" for Australia, or "KE" for Kenya.

Q: What does basisOfRecord mean in occurrence results? A: The basisOfRecord field describes what type of evidence the occurrence is based on. Common values include HUMAN_OBSERVATION (someone saw the organism, including iNaturalist and eBird records), PRESERVED_SPECIMEN (a physical specimen in a museum collection), MACHINE_OBSERVATION (camera trap, acoustic sensor, or satellite data), FOSSIL_SPECIMEN, MATERIAL_SAMPLE (DNA or tissue), and LIVING_SPECIMEN (zoo or botanical garden record).

Q: Why do some occurrence records have null coordinates? A: Not all GBIF records are georeferenced. Older museum specimens, literature-based records, and some citizen science observations may lack precise GPS coordinates. The country field is usually still populated even when coordinates are missing.

Q: How do I filter by a year range? A: Use the year parameter with GBIF's range syntax. A single year like "2024" returns records from that year only. A range like "2020,2024" returns records from 2020 through 2024 inclusive. This parameter only applies to occurrence searches.

Q: Can I get more than 500 results? A: The actor caps results at 500 per run for performance reasons. To collect more data, run the actor multiple times with different filters (e.g., different countries or year ranges) and combine the outputs. For very large downloads (millions of records), consider using GBIF's native download service at gbif.org.

Q: What is taxonomicStatus and why does it matter? A: The taxonomicStatus field indicates whether a species name is currently accepted in the GBIF taxonomic backbone. ACCEPTED means it is the current valid name. SYNONYM means the name exists but has been superseded by an accepted name. DOUBTFUL means the name's status is uncertain. This is important for ensuring you are working with current taxonomy.

Q: How current is the GBIF data? A: GBIF receives new data continuously as publishers update their datasets. Major citizen science platforms like iNaturalist and eBird push new observations regularly. However, there is typically a lag of days to weeks between an observation being recorded and it appearing in GBIF's search index.

Q: Can I use the output data for commercial purposes? A: GBIF data is published under open licenses, but individual datasets may use CC BY or CC BY-NC licenses that require attribution or restrict commercial use. Check the specific dataset's license on gbif.org before using data commercially.

Q: How does the actor handle misspelled species names? A: For species searches, GBIF's search endpoint performs fuzzy matching and will return close matches. For occurrence searches, the /species/match endpoint attempts to resolve the name but may return a NONE match type for severely misspelled names, in which case the actor falls back to a raw scientific name query.

---

Related actors

Actor	Description	Link
IUCN Red List Search	Search the IUCN Red List for threatened species conservation status, population trends, and habitat information.	ryanclinton/iucn-red-list-search
OpenAQ Air Quality	Search the OpenAQ platform for real-time and historical air quality measurements from monitoring stations worldwide.	ryanclinton/openaq-air-quality
WHO Global Health Observatory	Search the WHO Global Health Observatory for health statistics, disease data, and epidemiological indicators.	ryanclinton/who-gho-search
World Bank Development Indicators	Search the World Bank for development indicators covering economics, health, education, and environment across 200+ countries.	ryanclinton/world-bank-indicators
OpenAlex Research Search	Search OpenAlex for academic research papers, authors, and institutions across all fields of study.	ryanclinton/openalex-research-search