IUCN Red List quickstart — species assessments¶

Fetch a species' Red List assessments through the EarthLens facade as a tidy table.

IUCN is the cluster's only tabular backend: download() returns a pandas.DataFrame of assessment records (category, criteria, population trend, year), fetched from the IUCN Red List v4 API.

Token. The Red List v4 API needs a Bearer token (sign up at https://api.iucnredlist.org/users/sign_up). Set it as the IUCN_TOKEN environment variable. The backend uses core requests — there is no SDK extra to install.

Setup¶

In [ ]:

from earthlens import EarthLens

from earthlens import EarthLens

Download a species assessment¶

variables=["species:Panthera leo"] runs the two-step taxon lookup (the binomial is split into genus + species). Reads IUCN_TOKEN from the environment.

In [ ]:

frame = EarthLens(
    data_source="iucn",
    variables=["species:Panthera leo"],
    start="2024-01-01",
    end="2024-12-31",
    lat_lim=[-90.0, 90.0],
    lon_lim=[-180.0, 180.0],
    path="out/iucn",
).download()

frame[["scientific_name", "category", "criteria", "population_trend", "year_published"]]

frame = EarthLens( data_source="iucn", variables=["species:Panthera leo"], start="2024-01-01", end="2024-12-31", lat_lim=[-90.0, 90.0], lon_lim=[-180.0, 180.0], path="out/iucn", ).download() frame[["scientific_name", "category", "criteria", "population_trend", "year_published"]]

Country assessments¶

List every assessment for a country with an ISO alpha-2 selector ("country:KE" or a friendly name like "Kenya").

In [ ]:

kenya = EarthLens(
    data_source="iucn",
    variables=["country:KE"],
    start="2024-01-01",
    end="2024-12-31",
    lat_lim=[-90.0, 90.0],
    lon_lim=[-180.0, 180.0],
    path="out/iucn",
).download()

print(f"{len(kenya)} assessments")
kenya["category"].value_counts()

kenya = EarthLens( data_source="iucn", variables=["country:KE"], start="2024-01-01", end="2024-12-31", lat_lim=[-90.0, 90.0], lon_lim=[-180.0, 180.0], path="out/iucn", ).download() print(f"{len(kenya)} assessments") kenya["category"].value_counts()

Licensing¶

Red List data is CC-BY-NC and may not be redistributed without a written IUCN waiver, so every download raises a LicenseWarning. The data is never bundled with earthlens — you fetch under your own token and agreement. Cite the Red List as its Terms of Use require.