API Downloads
The GBIF Occurrence Download API provides a service to download occurrence records and retrieve information about those downloads.
Occurrence downloads are created asynchronously — the user requests a download and, once the download is prepared, is sent an email with a link to the resulting file.
It is necessary to register as a user on GBIF.org to create a download request, and to authenticate using the username (not the email) and password.
Complete technical details are provided in the API reference documentation.
Requesting an occurrence download
A download request includes your username, email address, the download format, and a filter for the required data in the form of a predicate.
A basic example using the curl command to make the request:
Put this in a file called query.json, replacing userName with your username and [email protected] with your email address:
{
"creator": "userName",
"notificationAddresses": [
"[email protected]"
],
"sendNotification": true,
"format": "SIMPLE_CSV",
"predicate": {
"type": "and",
"predicates": [
{
"type": "equals",
"key": "BASIS_OF_RECORD",
"value": "PRESERVED_SPECIMEN"
},
{
"type": "in",
"key": "COUNTRY",
"values": [ "VC", "GD" ]
}
]
}
}format can be changed to one of SIMPLE_CSV, DWCA or SPECIES_LIST, see information about download formats.
Then use this Curl command:
curl --include --user userName:PASSWORD --header "Content-Type: application/json" --data @query.json https://api.gbif.org/v1/occurrence/download/requestA download key is returned. Querying that download key shows the download information, including the download link and DOI once the download is ready. Run this repeatedly, until you see SUCCEEDED, replacing the key with the key for your download:
curl -Ss https://api.gbif.org/v1/occurrence/download/0001005-130906152512535You can then download the resulting file:
curl --location --remote-name https://api.gbif.org/occurrence/download/request/0001005-130906152512535.zipDownloads using predicates can also be made through the website at create new download.
Occurrence search parameters
Most of the predicates below use a key which specifies the field to search on.
The keys are listed and described on the /occurrence/search API call, and in the Java documentation. Note they must be provided in UPPER_CASE_WITH_UNDERSCORES for the download APIs.
Occurrence download predicates
These are the supported predicates that can be combined to build download requests.
equals
Equality comparison. Tests for exact equality of the term and the value, or case-sensitive equality if matchCase is set to true.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "equals",
"key": "BASIS_OF_RECORD",
"value": "LITERATURE"
}
}or
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "equals",
"key": "HAS_COORDINATE",
"value": "true"
}
}or
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "equals",
"key": "CATALOG_NUMBER",
"value": "Ax1",
"matchCase":"true"
}
}and
Logical conjuction, "and". The sub-predicates must all be true.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "and",
"predicates": [
{ "type": "equals", "key": "HAS_GEOSPATIAL_ISSUE", "value": "false"},
{ "type": "equals", "key": "TAXON_KEY", "value": "2440447"}
]
}
}or
Logical disjunction, "or". At least one of the sub-predicates must be true.
When requesting many values of the same field (for example, multiple taxa or countries) the in predicate (just below) is more appropriate.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "or",
"predicates": [
{ "type": "equals", "key": "HAS_GEOSPATIAL_ISSUE", "value": "false"},
{ "type": "equals", "key": "TAXON_KEY", "value": "2440447"}
]
}
}in
Specify multiple values to be compared. "matchCase": true can be added if required.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "in",
"key": "CATALOG_NUMBER",
"values": ["cat1", "cat2", "cat3"]
}
}lessThan
Less than. Returns occurrences with term values strictly less than the provided value.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "lessThan",
"key": "YEAR",
"value": "1900"
}
}lessThanOrEquals
Less than or equals. Returns occurrences with term values less than or equal to the provided value.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "lessThanOrEquals",
"key": "ELEVATION",
"value": "1000"
}
}greaterThan
Greater than. Returns occurrences with term values strictly greater than the provided value.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "greaterThan",
"key": "YEAR",
"value": "1900"
}
}greaterThanOrEquals
Greater than or equals. Returns occurrences with term values greater than or equal to the provided value
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "greaterThanOrEquals",
"key": "ELEVATION",
"value": "1000"
}
}within
Geospatial predicate that checks if the coordinates are inside a polygon.
The polygon should be specified in Well-known text (WKT) format. If you have problems, first check your polygon with Wicket — ensure the points are ordered anti-clockwise. (A polygon with clockwise points represents the opposite: the whole world except the polygon.)
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "within",
"geometry": "POLYGON((-130.78125 51.179342,
-130.78125 22.593726,
-62.578125 22.593726,
-62.578125 51.179342,
-130.78125 51.179342))"
}
}geoDistance
Geospatial distance. This predicate checks if coordinates are within a specified distance of a geographical coordinate. The distance is specified with a unit, e.g. 5km or 1250m.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "geoDistance",
"latitude": "90",
"longitude": "100",
"distance": "5km"
}
}not
Logical negation. Gives the opposite of the sub-predicate.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "not",
"predicate": {
"type": "equals",
"key": "DATASET_KEY",
"value": "4fa7b334-ce0d-4e88-aaae-2e0c138d049e"
}
}
}like
Search for a pattern. ? matches exactly one character, * matches zero or more characters. "matchCase": true can be added if required.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "like",
"key": "CATALOG_NUMBER",
"value": "PAPS5-560*"
}
}isNull
Has an empty (null) value.
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "isNull",
"parameter": "CONTINENT"
}
}isNotNull
Has a non-empty value
{
"creator": "userName",
"notificationAddresses": ["[email protected]"],
"predicate": {
"type": "isNotNull",
"parameter":"ISSUE"
}
}Verbatim extension data
A download in Darwin Core Archive (DWCA) format includes three tables by default, as described in detail on Occurrence download formats.
Additional Darwin Core extension data can also be included in the archive. These data tables are not processed by GBIF; they are as-published.
The extension tables available for download are provided using this API call, under verbatimExtensions. They can be requested by adding a verbatimExtensions property to the download request:
{
"format": "DWCA",
"predicate": {
…
},
"verbatimExtensions": [
"https://rs.gbif.org/terms/1.0/DNADerivedData",
"https://rs.tdwg.org/dwc/terms/MeasurementOrFact"
]
}For descriptions of the extensions and their terms, see GBIF Registered Extensions.