Webservice API

version v0.9

Feedback sought

The API is currently at vesion v0.9 and is nearing stability - it powers all functions of this portal.

Please report issues to dev@gbif.org and help us move to a stable v1.0 (expected May 2014)

Introduction

Quick links

The GBIF API provides registration, discovery and access and information services in a RESTful manner.

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 feed: Provides services to stream useful information such as papers published using GBIF mobilized content for various themes.

The API is a RESTful JSON based API, and for all components Java libraries exist.

While the API is nearing stability for the first formal release, this documentation is also in first edition. Please consider reporting issues found with the documentation using the "feedback" button on the right to help improve the content.

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

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/v0.9/occurrence/search?year=1800,1899

Roadmap to v1.0

The GBIF api is currently at v0.9 which means:

  1. The API is nearing stability but changes might occur before v1.0
  2. Developers building applications using the API should be ready to follow any changes in the API, which will be announced
  3. v0.9 may not be maintained when v1.0 is released
  4. The base URL includes the version as appropriate

Known changes that will occur:

  1. The occurrence response will be reviewed to align closer to the Darwin Core
  2. The occurrence API will support searching by scientific name
  3. All query parameters for countries will be converted into ISO country codes where currently (e.g.) DENMARK is used
  4. Occurrence multimedia will be interpreted

Feedback is sought from developers on the API structure, before the frozen v1.0 will be released to dev@gbif.org

v1.0 is expected in May 2014 unless feedback received indicates it should be delayed