speciesfyi 0.1.1

Species taxonomy and biodiversity API client — speciesfyi.com

speciesfyi

Python API client for the world's species taxonomy and biodiversity data. Access 49,112 species records, 17,982 taxa across the full Linnaean hierarchy, 846 ecoregions mapped to WWF biomes, and habitat classification data — all through a clean REST API with zero core dependencies.

Extracted from SpeciesFYI, a species taxonomy reference platform cataloging biodiversity across all kingdoms of life with taxonomic classification, IUCN conservation status, geographic distribution, and ecological data used by researchers, educators, and conservation professionals.

Explore species data at speciesfyi.com — browse species, taxa, ecoregions, habitats, and field guides.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Taxonomic Classification
  • IUCN Conservation Status
  • Ecoregions and Biomes
  • Habitats and Ecosystems
  • Food Webs and Ecology
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About Species
• Nature FYI Family
• FYIPedia Developer Tools
• License

Install

pip install speciesfyi                # Core (zero deps)
pip install "speciesfyi[cli]"         # + Command-line interface (typer, rich)
pip install "speciesfyi[mcp]"         # + MCP server for AI assistants
pip install "speciesfyi[api]"         # + HTTP client for speciesfyi.com API
pip install "speciesfyi[all]"         # Everything

Or run instantly without installing:

uvx --from speciesfyi speciesfyi search "bald eagle"

Quick Start

from speciesfyi.api import SpeciesFYI

with SpeciesFYI() as api:
    # Search across all species, taxa, and ecoregions
    results = api.search("gray wolf")
    print(results)

    # Get detailed species information
    species = api.get_specy("gray-wolf")
    print(species["name"])  # Gray Wolf

    # Browse taxonomic ranks
    taxa = api.list_taxa()
    print(taxa["count"])  # 17,982 taxa records

    # Explore ecoregions mapped to WWF biomes
    ecoregions = api.list_ecoregions()
    print(ecoregions["count"])  # 846 ecoregions

What You Can Do

Taxonomic Classification

All life on Earth is organized through the Linnaean taxonomic hierarchy, a system developed by Carl Linnaeus in 1735 and refined over nearly three centuries. SpeciesFYI catalogs 17,982 taxa across all 8 major ranks, from the broadest domains down to individual species.

Rank	Description	Example
Domain	Highest level of classification	Eukarya
Kingdom	Major groups of organisms	Animalia, Plantae, Fungi
Phylum	Body plan organization	Chordata (vertebrates), Arthropoda
Class	Shared physiological traits	Mammalia, Aves, Reptilia
Order	Groupings within classes	Carnivora, Primates, Passeriformes
Family	Closely related genera	Canidae (dogs), Felidae (cats)
Genus	Group of closely related species	Canis, Panthera, Aquila
Species	Fundamental unit of classification	Canis lupus, Panthera leo

from speciesfyi.api import SpeciesFYI

with SpeciesFYI() as api:
    # Browse all taxonomic ranks in the hierarchy
    ranks = api.list_ranks()
    print(ranks["count"])  # 8 major ranks

    # Get all taxa — families, orders, classes, and more
    taxa = api.list_taxa()
    for taxon in taxa["results"][:3]:
        print(f"{taxon['rank']}: {taxon['name']}")

Learn more: Species Encyclopedia · Taxonomic Ranks · Field Guides

IUCN Conservation Status

The IUCN Red List is the world's most comprehensive inventory of the global conservation status of species. Each species is evaluated against quantitative criteria (population size, rate of decline, geographic range) and assigned one of 9 categories.

Category	Code	Description
Extinct	EX	No known living individuals
Extinct in the Wild	EW	Survives only in captivity
Critically Endangered	CR	Extremely high risk of extinction
Endangered	EN	Very high risk of extinction
Vulnerable	VU	High risk of extinction
Near Threatened	NT	Close to qualifying for a threatened category
Least Concern	LC	Low risk, widespread and abundant
Data Deficient	DD	Insufficient data to assess
Not Evaluated	NE	Not yet assessed against criteria

from speciesfyi.api import SpeciesFYI

with SpeciesFYI() as api:
    # Search for endangered species
    results = api.search("endangered")
    for item in results["results"][:3]:
        print(f"{item['name']}: {item.get('conservation_status', 'N/A')}")

Learn more: Species by Conservation Status · Biodiversity Glossary

Ecoregions and Biomes

An ecoregion is a large area of land or water with a geographically distinct assemblage of species, communities, and environmental conditions. The WWF system divides the terrestrial world into 14 biomes containing 867 ecoregions. SpeciesFYI catalogs 846 ecoregions with their biome classification, geographic extent, and associated species.

Biome	Ecoregion Examples	Climate
Tropical Moist Forests	Amazon, Congo Basin, Borneo lowlands	Hot, wet year-round
Temperate Broadleaf Forests	Appalachian, Western European	Moderate, seasonal
Boreal Forests/Taiga	Canadian boreal, Siberian taiga	Cold, long winters
Tropical Grasslands	Serengeti, Cerrado, Llanos	Hot, seasonal rainfall
Deserts and Xeric Shrublands	Sahara, Sonoran, Namib	Arid, extreme temperatures
Tundra	Arctic coastal, alpine meadows	Frozen, permafrost

from speciesfyi.api import SpeciesFYI

with SpeciesFYI() as api:
    # Browse all 846 ecoregions
    ecoregions = api.list_ecoregions()
    print(ecoregions["count"])  # 846

    # Get details for a specific ecoregion
    eco = api.get_ecoregion("amazon-basin")
    print(eco["name"])  # Amazon Basin

Learn more: Ecoregion Explorer · Habitat Guide

Habitats and Ecosystems

Habitats define where species live — from deep ocean trenches to alpine meadows. SpeciesFYI classifies habitats into hierarchical categories that map to species distribution patterns, helping researchers understand which environments support the greatest biodiversity.

from speciesfyi.api import SpeciesFYI

with SpeciesFYI() as api:
    # Browse habitat types
    habitats = api.list_habitats()
    for h in habitats["results"][:5]:
        print(h["name"])

    # Get species associated with a habitat
    habitat = api.get_habitat("coral-reef")
    print(habitat["name"])  # Coral Reef

Learn more: Habitat Types · Guides

Food Webs and Ecology

Food webs describe the feeding relationships in an ecosystem — who eats whom. Understanding trophic levels (producers, primary consumers, apex predators) reveals how energy flows through ecosystems and why the loss of a single species can cascade through an entire community.

from speciesfyi.api import SpeciesFYI

with SpeciesFYI() as api:
    # Explore food web relationships
    food_webs = api.list_food_webs()
    print(food_webs["count"])

    # Get a specific food web
    web = api.get_food_web("african-savanna")
    print(web["name"])  # African Savanna

Learn more: Food Webs · Field Guides

Command-Line Interface

pip install "speciesfyi[cli]"

speciesfyi search "bald eagle"     # Search across all species and taxa

MCP Server (Claude, Cursor, Windsurf)

Add species data to any AI assistant that supports Model Context Protocol.

pip install "speciesfyi[mcp]"

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "speciesfyi": {
            "command": "uvx",
            "args": ["--from", "speciesfyi[mcp]", "python", "-m", "speciesfyi.mcp_server"]
        }
    }
}

REST API Client

from speciesfyi.api import SpeciesFYI

with SpeciesFYI() as api:
    species = api.list_species()          # Browse all 49,112 species
    taxa = api.list_taxa()                # Browse 17,982 taxa
    ecoregions = api.list_ecoregions()    # Browse 846 ecoregions
    results = api.search("polar bear")    # Full-text search

API Endpoints

Method	Endpoint	Description
GET	/api/v1/species/	List all species
GET	/api/v1/species/{slug}/	Species detail
GET	/api/v1/taxa/	List all taxa
GET	/api/v1/taxa/{slug}/	Taxon detail
GET	/api/v1/ecoregions/	List all ecoregions
GET	/api/v1/ecoregions/{slug}/	Ecoregion detail
GET	/api/v1/habitats/	List all habitats
GET	/api/v1/habitats/{slug}/	Habitat detail
GET	/api/v1/ranks/	List taxonomic ranks
GET	/api/v1/countries/	List countries
GET	/api/v1/food-webs/	List food webs
GET	/api/v1/discoveries/	List species discoveries
GET	/api/v1/field-guides/	List field guides
GET	/api/v1/glossary/	List glossary terms
GET	/api/v1/guides/	List guides
GET	/api/v1/search/?q={query}	Search across all content

curl -s "https://speciesfyi.com/api/v1/species/?limit=3"

Full API documentation at speciesfyi.com/developers/. OpenAPI 3.1.0 spec: speciesfyi.com/api/openapi.json.

API Reference

Function	Description
SpeciesFYI()	Create API client (base_url, timeout)
list_species(**params)	List all species
get_specy(slug)	Get species detail
list_taxa(**params)	List all taxa
get_taxa(slug)	Get taxon detail
list_ecoregions(**params)	List all ecoregions
get_ecoregion(slug)	Get ecoregion detail
list_habitats(**params)	List all habitats
get_habitat(slug)	Get habitat detail
list_ranks(**params)	List taxonomic ranks
list_countries(**params)	List countries
list_food_webs(**params)	List food webs
list_discoveries(**params)	List species discoveries
list_field_guides(**params)	List field guides
list_glossary(**params)	List glossary terms
list_guides(**params)	List guides
search(query)	Search across all content

Learn More About Species

• Browse: Species Encyclopedia · Taxonomic Tree · Ecoregions
• Reference: Habitats · Countries · Discoveries
• Guides: Glossary · Guides · Field Guides
• API: REST API Docs · OpenAPI Spec

Nature FYI Family

Part of the FYIPedia open-source developer tools ecosystem — living organisms, wildlife, and natural history.

Package	PyPI	Description
speciesfyi	PyPI	49,112 species, 17,982 taxa, 846 ecoregions — speciesfyi.com
birdfyi	PyPI	11,251 birds, 40 orders, 258 families — birdfyi.com
fishfyi	PyPI	78 fish species, 48 orders, 188 families — fishfyi.com
plantfyi	PyPI	379,774 plants, 734 families, 50 orders — plantfyi.com
dinofyi	PyPI	6,142 dinosaurs, 15 periods, 198 countries — dinofyi.com

FYIPedia Developer Tools

Package	PyPI	npm	Description
colorfyi	PyPI	npm	Color conversion, WCAG contrast, harmonies — colorfyi.com
emojifyi	PyPI	npm	Emoji encoding & metadata for 3,953 emojis — emojifyi.com
symbolfyi	PyPI	npm	Symbol encoding in 11 formats — symbolfyi.com
unicodefyi	PyPI	npm	Unicode lookup with 17 encodings — unicodefyi.com
fontfyi	PyPI	npm	Google Fonts metadata & CSS — fontfyi.com
speciesfyi	PyPI	—	Species taxonomy & biodiversity — speciesfyi.com
birdfyi	PyPI	—	Bird species encyclopedia — birdfyi.com
fishfyi	PyPI	—	Fish species & marine biology — fishfyi.com
plantfyi	PyPI	—	Plant taxonomy & cultivation — plantfyi.com
dinofyi	PyPI	—	Dinosaur paleontology & fossil record — dinofyi.com

License

MIT