GBIF Getting Started: API Access and First Request (2026)

Getting started overview

The Global Biodiversity Information Facility (GBIF) offers free and open access to biodiversity data through its API. This guide outlines the process for developers to quickly begin interacting with the GBIF API, covering account creation, understanding authentication requirements, and executing a foundational data request. The GBIF API primarily serves data consumption, which generally does not require an API key or authentication for read-only access. Authentication is primarily needed for publishing data or managing user-specific services.

To get started with GBIF, developers typically follow these steps:

1. Understand API access: Confirm that most data consumption does not require authentication.
2. Create a GBIF account: Essential for publishing data, managing certain services, and accessing user-specific features.
3. Make your first unauthenticated request: Query the GBIF API for public data without credentials to verify connectivity and understand the data structure.
4. Explore authenticated requests (if needed): For data publishing or advanced services, learn how to use HTTP Basic Authentication.

This reference focuses on the initial setup and a basic data retrieval call. For comprehensive details on the API's capabilities and data models, consult the GBIF developer documentation and the GBIF API Swagger definition.

Quick reference table

Create an account and get keys

For most data retrieval operations from the GBIF API, an account or API key is not required. The GBIF API is designed for open access to biodiversity data, allowing developers to query and retrieve information without prior registration or authentication for read-only actions. This open access model differentiates it from many commercial APIs that mandate API keys for all requests.

However, a GBIF account becomes necessary for specific actions:

• Publishing data: If you intend to contribute biodiversity data to GBIF, you will need a registered account and potentially associated credentials to manage your datasets.
• Accessing user-specific services: Certain advanced features or personalized services may require a login.
• Managing data downloads: While direct downloads are often open, managing large or complex download requests might be linked to a user account.

To create a GBIF account, navigate to the GBIF user registration page. The process typically involves providing an email address, creating a username and password, and agreeing to the terms of service. Once registered, you will have access to the GBIF portal's personalized features, but these credentials are distinct from typical API keys used for authenticating individual API requests for data consumption.

Authentication for data publishing

When publishing data to GBIF or interacting with endpoints that modify data, HTTP Basic Authentication is used. This method involves sending a username and password with each request, encoded in the Authorization header. For example, if your username is myuser and password is mypassword, the header would look like Authorization: Basic BASE64_ENCODING_OF_myuser:mypassword. This is detailed in the GBIF developer documentation on authentication.

Your first request

Since most GBIF API data retrieval does not require authentication, you can make your first request using standard HTTP client tools like curl or a web browser. This example demonstrates how to retrieve information about a specific species occurrence, specifically the common house sparrow (Passer domesticus).

Using curl (command line)

To query for occurrences of Passer domesticus, you can use the following curl command. This example searches for occurrences by the scientific name and limits the results to one to keep the output concise.

curl -X GET "https://api.gbif.org/v1/occurrence/search?scientificName=Passer%20domesticus&limit=1" \
     -H "Accept: application/json"

Expected output (abbreviated for brevity):

{
  "offset": 0,
  "limit": 1,
  "endOfRecords": false,
  "results": [
    {
      "key": 2707328905,
      "datasetKey": "50c9509d-22c7-4a22-a47d-8c48425ef4a7",
      "publishingOrgKey": "e149463e-f14d-11e2-a031-00145eb45e9a",
      "networkKeys": [
        "cdd1966e-2139-4d56-8b2b-102555c48b7a"
      ],
      "installationKey": "10a3406f-657d-411a-b09e-3151b7529431",
      "decimalLatitude": 41.87811,
      "decimalLongitude": -87.629798,
      "countryCode": "US",
      "stateProvince": "Illinois",
      "year": 2011,
      "month": 5,
      "day": 10,
      "eventDate": "2011-05-10T11:00:00",
      "taxonKey": 2494645,
      "kingdomKey": 1,
      "phylumKey": 44,
      "classKey": 212,
      "orderKey": 719,
      "familyKey": 9370,
      "genusKey": 2494644,
      "speciesKey": 2494645,
      "scientificName": "Passer domesticus (Linnaeus, 1758)",
      ...
    }
  ],
  "facets": []
}

Using Python

For a programmatic approach, Python is a common choice for interacting with web APIs. The requests library simplifies HTTP requests.

import requests
import json

url = "https://api.gbif.org/v1/occurrence/search"
params = {
    "scientificName": "Passer domesticus",
    "limit": 1
}
headers = {
    "Accept": "application/json"
}

response = requests.get(url, params=params, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

Using R

R is widely used in scientific computing and has excellent packages for API interaction. The httr package facilitates HTTP requests.

library(httr)
library(jsonlite)

url <- "https://api.gbif.org/v1/occurrence/search"
query_params <- list(
  scientificName = "Passer domesticus",
  limit = 1
)

response <- GET(url, query = query_params, accept_json())

if (http_status(response)$category == "Success") {
  content <- content(response, "text", encoding = "UTF-8")
  data <- fromJSON(content)
  print(jsonlite::prettify(toJSON(data)))
} else {
  message(paste("Error:", http_status(response)$status_code, "-", content(response, "text")))
}

These examples demonstrate a basic query for species occurrence data. The GBIF API offers numerous other endpoints for taxonomic data, datasets, and publishing organizations, all discoverable via the OpenAPI specification.

Common next steps

After successfully making your first API request, consider these common next steps to further your integration with GBIF:

• Explore more specific endpoints: The GBIF API offers detailed endpoints for various data types, including taxonomy (GBIF Taxon endpoint), datasets (GBIF Dataset endpoint), and literature. Familiarize yourself with the full API documentation to find relevant data.
• Implement pagination: For queries that return a large number of results, implement pagination using the offset and limit parameters to retrieve data in manageable chunks.
• Understand data filtering: GBIF allows extensive filtering of occurrence data by geographic area, date ranges, dataset keys, and more. Experiment with these parameters to refine your queries.
• Utilize community SDKs: While GBIF does not officially provide SDKs, community-maintained libraries for languages like R (rgbif) and Python (pygbif) can simplify API interactions significantly. These libraries often handle common tasks such as pagination and data parsing. For example, the rgbif package documentation provides specific examples for R users.
• Handle rate limits: Although GBIF's rate limits are generally generous for research and non-commercial use, be mindful of making excessive requests in a short period. Implement exponential backoff or caching strategies if you anticipate high-volume data retrieval.
• Explore data downloads: For very large datasets, using the GBIF data download service may be more efficient than repeated API calls. This service allows you to define a query and receive a customized dataset in formats like Darwin Core Archive.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for GBIF API requests:

• Check URL and endpoint validity: Ensure the API endpoint URL is correct (e.g., https://api.gbif.org/v1/occurrence/search). Typographical errors are a frequent cause of 404 Not Found errors.
• Verify query parameters: Double-check the spelling and format of your query parameters (e.g., scientificName=Passer%20domesticus). Incorrect parameter names or values can lead to empty results or server errors. Refer to the OpenAPI specification for exact parameter names.
• Inspect HTTP status codes:
  • 200 OK: The request was successful. If data is empty, your query might be too restrictive or there are no matching records.
  • 400 Bad Request: Often indicates an issue with your query parameters, such as invalid values or missing required fields.
  • 404 Not Found: The requested resource (endpoint) does not exist. Verify the URL path.
  • 5xx Server Error: An issue on the GBIF server side. These are less common but can occur. If persistent, check the GBIF News page for service announcements.
• Review response body for error messages: When an error occurs (especially 4xx codes), the API often returns a JSON response containing a detailed error message. Parse this message to understand the specific problem.
• Check network connectivity: Ensure your machine has active internet access and is not blocked by a firewall from reaching api.gbif.org.
• Consult GBIF Developer Resources: The GBIF developer documentation provides extensive guidance and examples. The GBIF Help Desk is another resource for support.