omnilab/iucn

The IUCN Red List API v4 (https://api.iucnredlist.org/api/v4/) for omnisense/omnilab: a taxon by its SIS id or its scientific name, with its latest global assessment - category, criteria, population trend, citation -, as an entity. The user's token is required. Not tested live.

Installation

composer require omnilab/iucn

use Omnilab\Iucn\IucnSourceFactory;

$iucn = (new IucnSourceFactory($httpClient))->create([
    'key' => getenv('IUCN_API_KEY'),  // the user's Red List API token
]);

With the Symfony bundle, the factory is registered as iucn (see the core's docs); keep the token in an environment variable or the secrets vault.

Credentials

Every call needs the user's Red List API token: an account at api.iucnredlist.org, under the IUCN Red List Terms of Use, gives it. It is given as key and sent in the Authorization header, as the IUCN's R client rredlist sends it. Without it the source is built and every call is refused before it is made. Keep the token in an environment variable or the secrets vault.

Options

The factory's options, with the defaults it applies (IucnSourceFactory):

Capabilities

capabilities() answers entity; an operation it does not answer throws NotSupportedException before any call.

Outside the contract, on Omnilab\Iucn\IucnSource: assessment(int|string $id): ?Entity, the taxon with what one assessment (of any scope: a regional one) says.

Which API

The IUCN Red List API v4, https://api.iucnredlist.org/api/v4/. The token goes in the Authorization header, as the IUCN's R client rredlist sends it. Its documentation (api.iucnredlist.org/api-docs) sat behind a browser challenge on 2026-10-16 (403 to a script): the calls and the shape of the answers are taken from rredlist (its source and its recorded test fixtures, 2024-09-18).

Calls

No search(): the API has no search of names. An unknown taxon is null (404). An identifier of another scheme is refused before any call; a name of one word is null without a call.

What an entity holds

id (iucn: its SIS id), label, domain taxonomy, kind (species, subpopulation, infrarank), synonyms (its common names, then its synonyms), url (its assessment's page), related (child: its subspecies and subpopulations), and:

Which assessment: the one marked latest among those of the global scope (code 1); a taxon assessed only regionally has none here (assessment() reads a regional one by its id).

What the Red List does not give here

• Not read: threats, habitats, conservation actions, use and trade, locations and countries, realms, stresses, references and credits of an assessment; the lists by country, family, category or threat; the range maps (spatial data are distributed apart, under their own terms).

Example

<?php

require __DIR__.'/vendor/autoload.php';

use Omnilab\Exception\InvalidConfigException;
use Omnilab\Iucn\IucnSourceFactory;
use Symfony\Component\HttpClient\HttpClient;

$iucn = (new IucnSourceFactory(HttpClient::create()))->create([
    'key' => getenv('IUCN_API_KEY') ?: null,   // the user's Red List API token: every call needs it
    'mailto' => 'you@example.org',
]);

try {
    $gorilla = $iucn->entity('Gorilla gorilla');
    echo $gorilla?->label, ': ', $gorilla?->value('iucn_status'), ' (', $gorilla?->value('red_list_criteria'), '), ', $gorilla?->value('population_trend'), "\n";
    echo $gorilla?->value('citation'), "\n";
} catch (InvalidConfigException $e) {
    echo $e->getMessage(), "\n";
}

Without a token (run on 2026-10-27, no network needed: the call is refused before it is made):

[iucn] An IUCN Red List API token (the "key" option, from an account at api.iucnredlist.org) is needed for every call.

With a token it prints the gorilla's category, criteria, trend and the assessment's citation: not run here (no token).

# config/packages/omnilab.yaml
omnilab:
    sources:
        iucn: { factory: iucn, options: { key: '%env(IUCN_API_KEY)%', mailto: '%env(OMNILAB_MAILTO)%' } }

Errors

Every call goes through HttpSource: a 404 or a 410 (and a 204) is null - an empty page for a list -; a 429 is a RateLimitedException (retryAfter from Retry-After); a 5xx, a time-out or a host that does not answer an UnavailableException; any other 4xx a ProviderException with its status and what the service said; an answer that is not JSON a ProviderException, a web page answered for JSON an UnavailableException.

Before any call: no token (InvalidConfigException), an identifier of another scheme (NotSupportedException). The API's 403 (no token, a wrong one) is a ProviderException; an unknown taxon its 404, null.

Verified, and not

Not tested live: no token was used (an account and the acceptance of the terms of use are the user's). On 2026-10-16 the API answered 403 to a call without a token, and its documentation sat behind a browser challenge. WoRMS gave the IUCN id of the common dolphin (134817215) that day.

The tests answer the bodies the API v4 gave rredlist on 2024-09-18 (Tests/Constructed/): the gorilla's taxon (SIS 9404, twelve assessments, its latest global one chosen) by id and by name, the Atlantic Puffin's Europe assessment (Endangered, A2abcde+4abcde, decreasing). Whether today's answers keep that shape, and whether the token is sent as rredlist sends it, is to be checked by a user with a token.

On 2026-10-27 the example below ran without a token: the refusal before any call, as tested.

Responsibility

This package is an independent, unofficial client: it is not affiliated with, endorsed by or sponsored by the IUCN. The token is the user's, under the IUCN Red List Terms of Use: conservation, education and research that is not commercial (a commercial use needs the IUCN's licence), no redistribution of the data as a dataset, the Red List and each assessment cited, as the README's Terms of use says. Whoever runs the package is responsible for complying with them and for any use made of what it returns: see the README's Responsibility section.