redlistapi 0.4.0

A Python client for the IUCN Red List API

redlistapi

IUCN Red List API python interface

Description

A python interface and library for the IUCN Red List API https://api.iucnredlist.org/

Installation

Non-spatial

pip install redlistapi

Spatial

The Python GDAL library requires system-level libraries. Install GDAL headers before using:

Ubuntu/Debian

# first install the OS GDAL binaries
sudo apt install libgdal-dev
# then install the python GDAL version that matches your OS binaries
pip install gdal==`gdal-config --version`
# then install the package with spatial dependencies
pip install redlistapi[spatial]

macOS (Homebrew) **untested

# first install the OS GDAL binaries
brew install gdal
# then install the package with spatial dependencies
pip install redlistapi[spatial]

Windows **untested

# first use the Python GDAL Installer on PyPI, which automates the downloading and installing of the correct pre-compiled wheel for your system
pip install gdal-installer
gdal-installer
# then install the package with spatial dependencies:
pip install redlistapi[spatial]

Usage

To use this library you must first obtain a personal IUCN Red List API token.

The library has 3 main use approaches:

Direct API endpoints

For direct endpoints the return value is the raw API response to allow parsing pages.

Openapi endpoints fall in 3 categories.

File-like endpoints  
  Note there is no trailing "/".  
  e.g.: api/v4/information/api_version

Folder-like endpoints
    Note there is a trailing "/".
    e.g.: api/v4/taxa/kingdom/
 
Parametrized endpoints
    Note there can be several file-like endpoints.
    e.g.: api/v4/taxa/kingdom/{kingdom_name}

File-like endpoints

import redlistapi

redlistapi.api.v4.information.api_version(token=token).json()
redlistapi.api.v4.information.red_list_version(token=token).json()

Folder-like and Parametrized endpoints split in list and by_ endpoints

import redlistapi

redlistapi.api.v4.taxa.family.list(token=token).json()
redlistapi.api.v4.taxa.kingdom.list(token=token).json()
redlistapi.api.v4.taxa.kingdom.by_kingdom_name(token=token, kingdom_name='CHROMISTA', year_published='2023').json()

Simplified user-end interface

The simplified user-end interface simply eliminates the need to enter the token.
This is useful for interactive use.

import redlistapi

interface = redlistapi.V4_Interface(token)  
interface.information.api_version().json()  
animalia = interface.taxa.kingdom.by_kingdom_name(kingdom_name='animalia')  
animalia

Assessment Class and Factory

The Assessment Factory is a class that returns Assessment Classes.

The Assessment Class exposes all data available from a Red List Assessment.

import redlistapi

assessment_factory = redlistapi.AssessmentFactory(token=token)  

upupa = assessment_factory.from_assessment_id(assessment_id=181836360)  
upupa = assessment_factory.from_scientific_name(genus_name='Upupa', species_name='epops')  
upupa = assessment_factory.from_taxid(taxid=22682655)  

help(upupa)  
upupa.assessment_as_pandas()

Extras

Extra functionalities are included in the extras submodule, and generally use the simplified interface as an input.

Catalogs

Catalogs are brief descriptors of Red List assessments detailing key variables. The catalogs submodule allows the retrieval of a list of catalogs. This can be saved locally as an index of all available assessments on the Red List API, either for the latest published Red List, or including historical ones.

{
    "year_published": "2020",
    "latest": true,
    "possibly_extinct": false,
    "possibly_extinct_in_the_wild": false,
    "sis_taxon_id": 10030,
    "url": "https://www.iucnredlist.org/species/10030/495630",
    "taxon_scientific_name": "Hexanchus griseus",
    "red_list_category_code": "NT",
    "assessment_id": 495630,
    "scopes": [
        {
            "description": {
                "en": "Global"
            },
            "code": "1"
        }
    ]
}

import redlistapi

# instantiate the interface
interface = redlistapi.V4_Interface(token)

# get a list of all catalogs for currently published assessments
catalogs_latest = redlistapi.extras.catalogs.latest(interface = interface, verbose = True)

# get a list of all catalogs for current and historical assessments
catalogs_all = redlistapi.extras.catalogs.all(interface = interface, verbose = True)

Support

Submit requests and bugs on the repository's git page (https://gitlab.com/daniele.baisero/redlistapi).
Or contact Daniele Baisero (daniele.baisero-at-gmail.com).

Contributing

Contribution and collaboration offers are always welcome!

GitLab CI/CD Setup

The automated tests in GitLab CI/CD require a valid IUCN Red List API token to be accessible in your GitLab environment.

1. Navigate to your GitLab project:

   • Settings → CI/CD → Variables

2. Click Add Variable and configure it as follows:

   • Type: Variable
   • Environments: All
   • Visibility: Masked and hidden
   • Flags - Protect Variable: False ⬜️
   • Flags - Expand Variable Reference: True ✅
   • Key: REDLIST_API_TOKEN
   • Value: Your personal IUCN Red List API token goes here

Once saved, the variable will be available to all CI/CD pipelines and environments that require it.

Authors and acknowledgment

Daniele Baisero, 2025-2026.

Contributors

• Michael Winston Dales [e-mail]

License

MIT license - see LICENSE.

Project status

Ongoing development.