omnilab/iucn API reference

Omnilab\Iucn

IucnSource class

final class IucnSource extends HttpSource IucnSource.php:33

The IUCN Red List of Threatened Species, through its API v4 (api.iucnredlist.org/api/v4), with the user's token: a taxon by its SIS id or its scientific name - its classification, authority, common names, synonyms, the IUCN groups that assess it - and its latest global assessment: its Red List category (written as GBIF and iNaturalist write it, "Endangered (EN)"), criteria, population trend, year, whether it is possibly extinct, and the citation the IUCN asks for. An assessment by its id (assessment(), outside the contract).

The token is the user's to obtain from the IUCN (an account at api.iucnredlist.org, under the Red List's terms of use) and to pass as the "key" option; it is sent in the Authorization header, as the IUCN's own R client, rredlist, sends it. Without it every call is refused before it is made. The IUCN asks for half a second at least between two calls.

const BASE_URI = 'https://api.iucnredlist.org/api/v4/'

const THROTTLE = 0.5

Seconds between two calls: the IUCN recommends 0.5 at least.

const GLOBAL_SCOPE = '1'

The scope of the global assessments (the IUCN's code "1").

IucnSource::__construct()

public function __construct(HttpClientInterface $http, readonly ?string $key = null, readonly bool $assessment = true, readonly string $language = 'eng', string $baseUri = self::BASE_URI, array $headers = [], float $throttle = self::THROTTLE)

IucnSource::getName()

public function getName(): string

IucnSource::capabilities()

public function capabilities(): array

IucnSource::entity()

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

A taxon by its SIS id (134817215, iucn:134817215, its page) or its scientific name (genus and species, and a subspecies or variety after them: Gorilla gorilla, Gorilla gorilla diehli), with its latest global assessment read whole (a second call; the "assessment" option leaves it out).

IucnSource::assessment()

public function assessment(int|string $id): ?Entity

An assessment by its id, outside the contract: the taxon it assesses, with what that assessment says (any scope: a regional one, an older one); null when unknown.

IucnSourceFactory class

final class IucnSourceFactory extends SourceFactory IucnSourceFactory.php:22

The IUCN Red List: a taxon by SIS id or name with its latest global assessment, with the user's API token.

options: key: '%env(IUCN_API_KEY)%' # the user's Red List API token (an account at api.iucnredlist.org); every call needs it assessment: true # entity() reads the latest global assessment too (a second call) language: eng # the common name kept (ISO 639-3) throttle: 0.5 # seconds between two calls: the IUCN asks for 0.5 at least mailto: 'support@glitchr.io' # in the User-Agent base_uri: 'https://api.iucnredlist.org/api/v4/'

Options