API Summary
https://api.gbif.org/v1/
The GBIF API is a RESTful JSON based API. The base URL for v1 you should use is: https://api.gbif.org/v1/
The API should be considered stable, as should this accompanying documentation. It is also available with HTTPS. Please report any issues you find with either the API itself or the documentation using the "feedback" button on the top right.
API Sections
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.
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 button at the top of the page.
Bug reports should also be submitted using the feedback button at the top of the page.
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:
https://api.gbif.org/v1/occurrence/search?year=1800,1899
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:yourPassword -H "Content-Type:
application/json" -H "Accept: 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 List | Lists all countries with their country 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
The GBIF API is currently at v1 which means:
- 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.
- 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.
- 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.
- The base URL includes the version as appropriate.
Feedback from developers on the API can be sent to informatics@gbif.org. (For questions and help see
