Metadata-Version: 2.4
Name: redlistapi
Version: 0.4.0
Summary: A Python client for the IUCN Red List API
Author-email: Daniele Baisero <daniele.baisero@gmail.com>
License-Expression: MIT
Project-URL: homepage, https://gitlab.com/daniele.baisero/redlistapi
Project-URL: repository, https://gitlab.com/daniele.baisero/redlistapi
Project-URL: bugtracker, https://gitlab.com/daniele.baisero/redlistapi/issues
Keywords: IUCN,Red List,Red-List,KBA,Key Biodiversity Area,Key Biodiversity Areas
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: PyYAML
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tqdm
Provides-Extra: spatial
Requires-Dist: shapely; extra == "spatial"
Requires-Dist: geopandas; extra == "spatial"
Requires-Dist: geojson; extra == "spatial"
Requires-Dist: gdal; extra == "spatial"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: ruff; extra == "test"
Dynamic: license-file

# redlistapi

## IUCN Red List API python interface

## Description
A python interface and library for the IUCN Red List API [https://api.iucnredlist.org/](https://api.iucnredlist.org/)

## Installation

### Non-spatial
```shell
pip install redlistapi
```

### Spatial

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

#### Ubuntu/Debian
```shell
# 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
```shell
# first install the OS GDAL binaries
brew install gdal
# then install the package with spatial dependencies
pip install redlistapi[spatial]
```

#### Windows **untested
```shell
# 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](https://api.iucnredlist.org/).

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.
 
```text
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
```python
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
```python
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.

```python
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.

```python
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.

```json
{
    "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"
        }
    ]
}
```

```shell
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 <mwd24@cam.ac.uk>

## License
MIT license - see [LICENSE](LICENSE).

## Project status
Ongoing development.
