Webservice API

version v1

Introduction

Quick links

The GBIF API provides registration, discovery and access and information services.

The API is a RESTful JSON based API. The base URL for v1 you should use is:

  • http://api.gbif.org/v1

The API is split into logical sections to ease understanding:

  • Registry: Provides means to create, edit, update and search for information about the datasets, organizations (e.g. data publishers), networks and the means to access them (technical endpoints). The registered content controls what is crawled and indexed in the GBIF data portal, but as a shared API may also be used for other initiatives
  • Species: Provides services to discover and access information about species and higher taxa, and utility services for interpreting names and looking up the identifiers and complete scientific names used for species in the GBIF portal.
  • Occurrence: Provides access to occurrence information crawled and indexed by GBIF and search services to do real time paged search and asynchronous download services to do large batch downloads.
  • Maps: Provides simple services to show the maps of GBIF mobilized content on other sites.
  • News: Provides services to stream useful information such as papers published using GBIF mobilized content for various themes.

For the Registry, Species, Occurrence, and Maps sections, Java web service clients exist. Please see each section's introduction for more information.

You can also sign up to the GBIF API users mailing list to post your questions, and to keep informed about the API. We will announce new versions, and scheduled maintenance downtimes before they happen.

We welcome any example uses of the API to guest feature on the GBIF developer blog.

The API should be considered stable, as should this accompanying documentation. Please report any issues you find with either the API itself or the documentation using the "feedback" button on the right.

Common operations

The following details common cross-cutting parameters used in the API

Paging

For requests that support paging the following parameters are used:

Parameter Details
limit Controls the number of results in the page. Using too high a value will be overwritten with the default maximum threshold, depending on the service. Sensible defaults are used so this may be omitted.
offset Determines the offset for the search results. A limit of 20 and offset of 20, will get the second page of 20 results.

Range queries

Some search parameters support range queries, for example the year parameter in the occurrence search. In general ranges are given as a single parameter value by concatenating a lower and an upper value with a comma. For example: http://api.gbif.org/v1/occurrence/search?year=1800,1899

Authentication

Authentication

POST, PUT, and DELETE requests require authentication. The GBIF API uses HTTP Basic Authentication with any GBIF user account that you have created before.

For example to issue a new download programmatically using curl with a query filter as JSON in a file called filter.json: $ curl -i --user yourUserName: -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @filter.json http://api.gbif.org/v1/occurrence/download/request

Roadmap to v2

The GBIF API is currently at v1 which means:

  1. The API is stable - this means we won't rename or remove any REST resources or response properties to ensure backwards compatibility, but we might add new resources to the API. Any additions will be announced via the API mailing list.
  2. Any bug fixes or additions will result in minor version changes which are not reflected in the API URL, only in the documentation and our Java client code.
  3. If and when the need for breaking changes arises we will document our intent here and on the mailing list, and give considerable warning before moving to a future v2.
  4. The base URL includes the version as appropriate.

Feedback from developers on the API can be sent to dev@gbif.org