omnilab/gbif API reference

Omnilab\Gbif

GbifSource class

final class GbifSource extends HttpSource GbifSource.php:47

GBIF's taxonomy, through its API (api.gbif.org): a taxon by its key, by its legacy GBIF Backbone number, by its NCBI Taxonomy id or by a scientific name GBIF matches; its name, authorship, rank, status, IUCN Red List category, common name, place of publication and classification; its legacy key and its NCBI id as cross-references, its parent (and, for a synonym, the accepted taxon) as related things; and a search. And the occurrences of a place and a period - the records of an organism found there then, observed or collected -, each an entity with its time and its place, its taxon related (occurrences(), entity() by its key).

Since June 2026 GBIF's taxonomy is the Catalogue of Life eXtended Release (checklist 7ddf754f-d193-4cc9-b351-99906754a03b), its keys alphanumeric (4CGXP, Panthera leo); the GBIF Backbone it replaces, frozen since 2023, kept numbers (5219404, the same lion), which most of the world - Wikidata's P846, NCBI's links - still cites. The source answers with the new key and gives the legacy one beside it; GBIF's API still takes both, but a call without a checklist key answers with the legacy Backbone: every call here names the checklist.

No key. A taxon costs three calls: GBIF's name match (the usage, its classification, its IUCN status), the checklist's record (its common name, its publication, its legacy number), the records related to the legacy one in the European Nucleotide Archive's taxonomy (its NCBI id). An occurrence, or a page of them, one.

const BASE_URI = 'https://api.gbif.org/'

const CHECKLIST = '7ddf754f-d193-4cc9-b351-99906754a03b'

The Catalogue of Life eXtended Release in GBIF: its taxonomy since June 2026.

const ENA = '6b6b2923-0a10-4708-b170-5b7c611aceef'

The European Nucleotide Archive's taxonomy in GBIF: NCBI Taxonomy's ids.

const MAX_PER_PAGE = 1000

The most taxa one search page is asked for (GBIF stops at 1000).

const MAX_OCCURRENCES_PER_PAGE = 300

The most occurrences one page holds (GBIF answers 300 for more).

const MAX_OCCURRENCE_DEPTH = 100000

How deep the occurrence search pages: offset and limit together (GBIF's 400 beyond; its downloads go further).

GbifSource::__construct()

public function __construct(HttpClientInterface $http, readonly string $checklist = self::CHECKLIST, readonly bool $ncbi = true, readonly string $language = 'eng', readonly float $radius = 10.0, string $baseUri = self::BASE_URI, array $headers = [], float $throttle = 0.0)

$checklist

the GBIF checklist to answer from (the Catalogue of Life eXtended Release)

$ncbi

whether the NCBI id is read (one call more)

$language

the language of the common name, ISO 639-2 ("eng", "fra"), for a search's results

$radius

the radius around a Point, in kilometres, for occurrences() when the query gives none

GbifSource::getName()

public function getName(): string

GbifSource::capabilities()

public function capabilities(): array

GbifSource::entity()

public function entity(Identifier|string $id): ?Entity

A taxon by its key (4CGXP, gbif:4CGXP, its page), its legacy number (5219404, its page gbif.org/species/), its NCBI id (an Identifier of ncbi.taxon, taxonomy:9689) or a scientific name ("Panthera leo"; a synonym gives the accepted taxon). A common name is no scientific name: GBIF matches none ("lion"). An occurrence by its key (gbif.occurrence:5938104699, its page): one call.

GbifSource::search()

public function search(Query $query): Page

GBIF's search of the checklist: its names, common names included, matching the text ("Panthera", "lion"), page by offset. A domain other than taxonomy answers nothing.

GbifSource::occurrences()

public function occurrences(OccurrenceQuery $query): Page

The occurrences of the place and the period - the records of an organism found there then, observed, collected or sampled, as GBIF's occurrence search gives them -, each an entity with its time and its place, its taxon related. Only the records GBIF has placed and dated, of an organism present (not a recorded absence), are asked for.

A BBox is the box (across the antimeridian, two polygons); a Point, the circle of the query's radius around it (the configured one, 10 km, by default); no place, the world. The period is in whole days: a time stands for its day. Filters: OccurrenceQuery::TAXON (a key, 4CGXP, which takes its subordinate taxa and synonyms; a legacy number, 5219404, read in the frozen Backbone; or a scientific name, matched in the checklist), COUNTRY (ISO 3166-1 alpha-2, or a list) and KIND (GBIF's basis of record, or a list: human_observation, preserved_specimen, machine_observation, material_sample...). GBIF sorts nothing: a sort is refused. 300 a page at most, 100,000 deep; the total is GBIF's count.

GbifSourceFactory class

final class GbifSourceFactory extends SourceFactory GbifSourceFactory.php:24

GBIF's taxonomy (the Catalogue of Life eXtended Release since June 2026): taxa by key, legacy Backbone number, NCBI id or scientific name; the occurrences of a place and a period - no key needed.

options: mailto: 'support@glitchr.io' # in the User-Agent, as GBIF asks: whom it writes to before it slows a caller down ncbi: true # read a taxon's NCBI id (one call more) language: 'eng' # the common name a search result keeps, ISO 639-2 radius_km: 10 # the circle around a Point, for occurrences() when the query gives none checklist: '7ddf754f-d193-4cc9-b351-99906754a03b' # the checklist answered from throttle: 0 # seconds between two calls: GBIF publishes no figure, and slows a caller down with 429 base_uri: 'https://api.gbif.org/'

Options