Occurrence API

version v0.9

Introduction

Quick links

This API works against the GBIF Occurrence Store, which handles occurrence records and makes them available through the web service and download files. In addition we also provide a Map API that offers spatial services.

Internally we use a Java web service client for the consumption of these HTTP-based, RESTful web services. It may be of interest to those coding against the API, and can be found in the occurrence-ws-client.

Occurrences

This API provides services related to the retrieval of single occurrence records.

Resource URL Method Response Description
/occurrence/{key} GET Occurrence Gets details for a single, interpreted occurrence
/occurrence/{key}/fragment GET Occurrence Get a single occurrence fragment in its raw form (xml or json)
/occurrence/{key}/verbatim GET VerbatimOccurrence Gets the verbatim occurrence record without any interpretation

Occurrence Downloads

This API provides services to download occurrence records and retrieve information about those downloads.

Occurrence downloads are created asynchronously - the user requests a download and, once complete, is sent and email with a link to the resulting file.

Internally we use a Java web service client for the consumption of these HTTP-based, RESTful web services. It may be of interest to those coding against the API, and can be found in the occurrence-download-ws-client.

Resource URL Method Response Description Auth Paging
/occurrence/download/request POST Download key Starts the process of creating a download file. See the predicates section to consult the requests accepted by this service. true false
/occurrence/download/request/{key} GET Download file Retrieves the download file if it is available. false false
/occurrence/download/request/{key} DELETE Cancels the download process. true false
/occurrence/download GET Download Page Lists all the downloads. This operation can be executed by the role ADMIN only. true true
/occurrence/download/{key} GET Download Retrieves the occurrence download metadata by its unique key. false false
/occurrence/download/{key} PUT Updates the status of an existing occurrence download. This operation can be executed by the role ADMIN only. true false
/occurrence/download/{key} POST Creates the metadata about an occurrence download. This operation can be executed by the role ADMIN only. true false
/occurrence/download/user/{user} GET Download Page Lists the downloads created by a user. Only role ADMIN can list downloads of other users. true true

Occurrence Metrics

This API provides services to retrieve various counts and metrics provided about occurrence records. The kind of counts that are currently supported are listed by the schema method, see below for details.

Resource URL Method Response Description Parameters
/count GET Count Returns occurrence counts for a predefined set of dimensions. The supported dimensions are enumerated in the /occurrence/count/schema service. An example for the count of georeferenced observations from Canada: /occurrence/count?country=CANADA&georeferenced=true&basisOfRecord=OBSERVATION. Note that country is the full name, not ISO code. This will change to ISO code in v1.0 of the API.
/count/schema GET Count List the supported metrics by the service.
/counts/basis_of_record GET Counts Lists occurrence counts by basis of record.
/counts/countries GET Counts Lists occurrence counts by publishing country. publishingCountry
/counts/year GET Counts Lists occurrence counts by year. from, to

Occurrence Inventories

This API provides services that list all distinct values together with their occurrence count for a given occurrence property. Only a few properties are supported, each with its own service to call.

Resource URL Method Response Description Parameters
/occurrence/counts/datasets GET UUID Counts Returns occurrence counts for datasets that cover a given taxon or country. country, taxonKey
/occurrence/counts/countries GET Country Counts Returns occurrence counts for all countries covered by the data published by the given country. publishingCountry
/occurrence/counts/publishingCountry GET Country Counts Returns occurrence counts for all countries that publish data about the given country. country

Query parameters explained

The following parameters are for use exclusively with the Occurrence API described above.

Parameter Description
basisOfRecord Basis of record, as defined in our BasisOfRecord enum
catalogNumber An identifier of any form assigned by the source within a physical collection or digital dataset for the record which may not be unique, but should be fairly unique in combination with the institution and collection code.
collectionCode An identifier of any form assigned by the source to identify the physical collection or digital dataset uniquely within the context of an institution.
continent Continent, as defined in our Continent enum
country The 2-letter country code (as per ISO-3166-1) of the country in which the occurrence was recorded.
datasetKey The occurrence dataset key (a uuid)
decimalLatitude Latitude in decimals between -90 and 90 based on WGS 84.. Supports range queries.
decimalLongitude Longitude in decimals between -180 and 180 based on WGS 84.. Supports range queries.
depth Depth in meters relative to altitude. For example 10 meters below a lake surface with given altitude. Supports range queries.
elevation Elevation (altitude) in meters above sea level. Supports range queries.
eventDate Occurrence date in ISO 8601 format: yyyy, yyyy-MM, yyyy-MM-dd, or MM-dd. Supports range queries.
from The minimum year for which to return occurrence counts. Deprecated and will be replaced by a standard range query soon.
geometry Searches for occurrences inside a polygon described in Well Known Text (WKT) format. A WKT shape written as POLYGON ((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1)) would be queried as is, i.e. /occurrence/search?geometry=POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1)).
hasCoordinate Limits searches to occurrence records which contain a value in both latitude and longitude (i.e. georeferenced=true limits to occurrence records with coordinate values and georeferenced=false limits to occurrence records without coordinate values).
institutionCode An identifier of any form assigned by the source to identify the institution the record belongs to. Not guaranteed to be unique.
issue A specific interpretation issue as defined in our OccurrenceIssue enum
lastInterpreted This date the record was last modified in GBIF, in ISO 8601 format: yyyy, yyyy-MM, yyyy-MM-dd, or MM-dd. Supports range queries.
limit The maximum number of results to return. This can't be greater than 300, any value greater is set to 300.
month The month of the year, starting with 1 for January. Supports range queries.
publishingCountry The 2-letter country code (as per ISO-3166-1) of the country in which the occurrence was recorded.
q Simple search parameter. The value for this parameter can be a simple word or a phrase.
recordedBy The person who recorded the occurrence.
recordedNumber The person who recorded the occurrence.
scientificName A scientific name from the GBIF backbone. All included and synonym taxa are included in the search.
spatialIssues Includes/excludes occurrence records which contain spatial issues (as determined in our record interpretation), i.e. spatialIssues=true returns only those records with spatial issues while spatialIssues=false includes only records without spatial issues. The absence of this parameter returns any record with or without spatial issues.
taxonKey A taxon key from the GBIF backbone. All included and synonym taxa are included in the search, so a search for aves with taxonKey=212 (i.e. /occurrence/search?taxonKey=212) will match all birds, no matter which species.
to The maximum year for which to return occurrence counts. Deprecated and will be replaced by a standard range query soon.
year The 4 digit year. A year of 98 will be interpreted as AD 98. Supports range queries.

Occurrence Download Predicates

A download predicate is an query expression to retrieve occurrence record downloads.

If you are interested in seeing some examples of how to use the Java API to build predicates, there are some test cases that can be used as a reference.

The table below lists the supported predicates that can be combined to build download requests.

Predicate Description Example
equals equality comparison {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"equals",
    "key":"BASIS_OF_RECORD",
    "value":"LITERATURE"
  }
}
and logical AND(conjuction) {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"and",
    "predicates":       [{"type":"equals","key":"SPATIAL_ISSUES","value":"false"},
      {"type":"equals","key":"TAXON_KEY","value":"2440447"}]
  }
}
or logical OR(disjunction) {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"or",
    "predicates":       [{"type":"equals","key":"SPATIAL_ISSUES","value":"false"},
      {"type":"equals","key":"TAXON_KEY","value":"2440447"}]
  }
}
lessThan is less than {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"lessThan",
    "key":"YEAR",
    "value":"1900"
  }
}
lessThanOrEquals is less than or equals {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"lessThanOrEquals",
    "key":"ALTITUDE",
    "value":"1000"
  }
}
greaterThan is greater than {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"greaterThan",
    "key":"YEAR",
    "value":"1900"
  }
}
greaterThanOrEquals is greater than or equals {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"greaterThanOrEquals",
    "key":"ALTITUDE",
    "value":"1000"
  }
}
in specify multiple values to be compared {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"in",
    "key":"CATALOG_NUMBER",
    "values":["cat1","cat2","cat3"]
  }
}
within geospatial predicate that checks if the coordinates are inside a POLYGON {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "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))"
  }
}
not logical negation {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"not",
        "predicate":
        {
          "type":"equals",
          "key":"CATALOG_NUMBER",
          "value":"cat1"
        }
  }
}
like search for a pattern {
  "creator":"userName",
  "notification_address": ["userName@gbif.org"],
  "predicate":
  {
    "type":"like",
    "key":"CATALOG_NUMBER",
    "value":"PAPS5-560%"
  }
}