omnilab/obis API reference

Omnilab\Obis

ObisSource class

final class ObisSource extends HttpSource ObisSource.php:33

OBIS, the Ocean Biodiversity Information System (IOC-UNESCO), through its API v3 (api.obis.org/v3): a marine taxon by its WoRMS AphiaID or its name - OBIS's taxonomy is WoRMS' - with its rank, status, classification, vernacular names, NCBI id, habitat flags and how many records OBIS holds of it; and the occurrences of a place and a period (occurrences()), each with its time, its place, its depth, the sea surface temperature and salinity OBIS gives its place, its taxon related; a record by its UUID.

No key, no published rate; OBIS pages a query by the id of its last record (after), 10,000 a page at most.

const BASE_URI = 'https://api.obis.org/v3/'

const MAX_PER_PAGE = 10000

The most records one page holds (OBIS's 400 beyond).

const MIN_DEPTH = 'min_depth'

OBIS's own filters: the depth in metres (min, max), a dataset's UUID, Red List species only.

const MAX_DEPTH = 'max_depth'

const DATASET = 'dataset'

const RED_LIST = 'red_list'

ObisSource::__construct()

public function __construct(HttpClientInterface $http, readonly bool $statistics = true, readonly float $radius = 10.0, string $baseUri = self::BASE_URI, array $headers = [], float $throttle = 0.0)

$statistics

entity() asks for the taxon's records too (a second call; up to 8 s for a kingdom)

$radius

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

ObisSource::getName()

public function getName(): string

ObisSource::capabilities()

public function capabilities(): array

ObisSource::entity()

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

A taxon by its AphiaID (137094, worms:137094, its LSID, its WoRMS page) or its scientific name as OBIS writes it (an unaccepted name gives its own record, the accepted taxon related); a record by its UUID (obis.occurrence:...). One call, two with the taxon's statistics.

ObisSource::occurrences()

public function occurrences(OccurrenceQuery $query): Page

The records of the place and the period, each an entity with its time and its place, its taxon related; present records only (OBIS leaves out absences and the records its quality control dropped).

A BBox is the box (across the antimeridian, its east past 180°); a Point, the circle of the query's radius (10 km by default) as a polygon of 64 sides; no place, the ocean. The period: whole days (OBIS takes no time), on the records' start and end. Filters: OccurrenceQuery::TAXON (an AphiaID, an Identifier of worms - its subordinate taxa included -, or a scientific name), min_depth and max_depth (metres), dataset (an OBIS dataset's UUID), red_list (true: the IUCN Red List's species). No sort: OBIS's order, by id, the next page after the last one. 10,000 a page at most; the total is OBIS's.

ObisSourceFactory class

final class ObisSourceFactory extends SourceFactory ObisSourceFactory.php:21

OBIS: marine taxa by AphiaID or name, and the occurrences of a place and a period - no key needed.

options: mailto: 'support@glitchr.io' # in the User-Agent statistics: true # entity() asks for the taxon's records too (a second call) radius_km: 10 # the circle around a Point, for occurrences() when the query gives none throttle: 0 # seconds between two calls: OBIS publishes no rate base_uri: 'https://api.obis.org/v3/'

Options