[go: up one dir, main page]

GBIF API Reference

320

The GBIF API provides a programmatic way to query and publish data on GBIF.org. It can be useful or necessary to use the API to

  • make advanced queries, not supported by the website,

  • include the results of GBIF queries in scripts, workflows or analyses, which can then be repeated reliably and automatically,

  • embed GBIF data into other websites.

The GBIF API is RESTful and most queries return data in JSON format. The base URL is https://api.gbif.org/.

The API should be considered stable, as should this accompanying documentation.

API Sections

The API is split into logical sections to ease understanding:

  • The Registry provides means to create, edit, update and search for information about the datasets, publishing organizations, 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, including the Global Register of Scientific Collections (GRSciColl).

  • 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, search services to do real-time paged search and asynchronous download services to request large, batch downloads.

  • Maps provides services to show maps of GBIF-mobilized content.

  • Literature provides access to peer-reviewed papers and other literature indexed by GBIF, citing GBIF datasets and downloads.

  • Validator allows running data structure and quality checks against a dataset before publication to GBIF.

  • Vocabularies are used during data interpretation to align some terms such as Life Stage to a limited set of values.

Communication

You can 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.

You can also post questions to the GBIF Community Forum or using the feedback buttons at the top of the pages on GBIF.org.

Please report any issues you find with the API to GitHub (recommended if you already have a GitHub account), using the "feedback" button on an appropriate page on gbif.org, or by email to the Helpdesk. Errors, omissions or improvements to the documentation can be made in the same way, or with the "Edit this page" links on this site.

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 40 will retrieve the third page of 20 results.

Repeatable parameters

Many search parameters are repeatable, for example the country parameter in the occurrence search. Repeating the parameter with different values will search for records matching any value. For example, https://api.gbif.org/v1/occurrence/search?country=GB&country=IE&country=IM.

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: https://api.gbif.org/v1/occurrence/search?year=1800,1899.

In most cases, where a parameter can either be repeated, or used as a range, but not queried with multiple ranges.

Authentication

POST, PUT, and DELETE requests require authentication. The GBIF API uses HTTP Basic Authentication with any existing GBIF user account.

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:yourPassword -H "Content-Type: application/json" -X POST -d @filter.json https://api.gbif.org/v1/occurrence/download/request`

Enumerations

Many parts of the GBIF API make use of enumerations, i.e. controlled vocabularies for specific topics. Often these are based on existing standards such as ISO or TDWG. The enumerations are part of the GBIF Java API, but the currently active version can also be dynamically accessed through our JSON webservices to support more dynamic clients.

Resource URL Method Response Description

/enumeration/basic

GET

Enumeration list

Lists all available enumerations

/enumeration/basic/{ENUMERATION}

GET

Enumeration values

Lists all available values for a given enumeration

/enumeration/country

GET

Country and area list

Lists all countries and areas with their code and title

/enumeration/license

GET

License list

Lists all supported GBIF licenses using the License URL or just the enum name if no URL exists.

Roadmap to v2

Most of the GBIF API is currently at version 1 which means:

  1. The API is stable – 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.

The Maps API is at version 2, with the same expectations (as far as is possible, Maps API version 1 continues to work).

Feedback from developers on the API can be sent to informatics@gbif.org. (For questions and help see above).