birdfyi 0.1.1

Bird species encyclopedia API client — birdfyi.com

birdfyi

Python API client for the world's bird species data. Access 11,251 bird species across 40 orders and 258 families, with taxonomic classification, habitat information, regional distribution, conservation status, and field identification data — all through a clean REST API with zero core dependencies.

Extracted from BirdFYI, an ornithology reference platform cataloging every known bird species with taxonomy, geographic range, habitat preferences, and conservation assessments based on the IOC World Bird List and BirdLife International data.

Explore bird data at birdfyi.com — browse birds, orders, families, habitats, and field guides.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Bird Taxonomy
  • Orders and Families
  • Habitats and Regional Presence
  • Species Comparison
  • Field Identification
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About Birds
• Nature FYI Family
• FYIPedia Developer Tools
• License

Install

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

Or run instantly without installing:

uvx --from birdfyi birdfyi search "bald eagle"

Quick Start

from birdfyi.api import BirdFYI

with BirdFYI() as api:
    # Search across all bird species
    results = api.search("robin")
    print(results)

    # Get detailed information for a specific bird
    bird = api.get_bird("american-robin")
    print(bird["name"])  # American Robin

    # Browse bird families — 258 families worldwide
    families = api.list_families()
    print(families["count"])  # 258

    # Explore taxonomic orders — 40 orders of birds
    orders = api.list_orders()
    print(orders["count"])  # 40

What You Can Do

Bird Taxonomy

Modern bird taxonomy recognizes approximately 11,251 species organized into 40 orders and 258 families. The classification follows the IOC World Bird List, which is updated annually based on molecular phylogenetics and morphological studies. BirdFYI provides the complete taxonomic tree from order down to individual species.

Taxonomic Level	Count	Description
Orders	40	Highest grouping (e.g., Passeriformes, Accipitriformes)
Families	258	Morphological/genetic groupings within orders
Species	11,251	Distinct species recognized by the IOC

The largest order, Passeriformes (perching birds), contains over 6,500 species — more than half of all birds. It includes familiar families like warblers (Parulidae), finches (Fringillidae), and crows (Corvidae).

from birdfyi.api import BirdFYI

with BirdFYI() as api:
    # Browse all 40 bird orders
    orders = api.list_orders()
    for order in orders["results"][:5]:
        print(f"{order['name']}: {order.get('species_count', 'N/A')} species")

    # Get all families within an order
    families = api.list_families()
    print(families["count"])  # 258 families worldwide

Learn more: Bird Orders · Bird Families · Ornithology Glossary

Orders and Families

Bird orders represent major evolutionary lineages that diverged millions of years ago. Each order shares fundamental anatomical and behavioral traits that distinguish it from other orders.

Order	Common Name	Species	Key Feature
Passeriformes	Perching birds	~6,500	Anisodactyl feet (3 toes forward, 1 back)
Apodiformes	Swifts & hummingbirds	~490	Rapid wingbeats, aerial specialists
Accipitriformes	Hawks & eagles	~266	Hooked beaks, powerful talons
Psittaciformes	Parrots	~400	Zygodactyl feet (2+2), curved bills
Charadriiformes	Shorebirds	~390	Wading specialists, diverse bill shapes
Piciformes	Woodpeckers	~450	Chisel-like bills, stiff tail feathers
Strigiformes	Owls	~260	Nocturnal, binocular vision, silent flight
Columbiformes	Pigeons & doves	~350	Crop milk, powerful flight muscles
Anseriformes	Waterfowl	~180	Webbed feet, flat bills, waterproofing
Pelecaniformes	Pelicans & herons	~120	Throat pouches, wading/diving

from birdfyi.api import BirdFYI

with BirdFYI() as api:
    # Get details for a specific order
    raptors = api.get_order("accipitriformes")
    print(raptors["name"])  # Accipitriformes

    # Browse families — each family groups closely related genera
    family = api.get_family("accipitridae")
    print(family["name"])  # Accipitridae (hawks, eagles, kites)

Learn more: Browse All Orders · Family Encyclopedia

Habitats and Regional Presence

Birds occupy every continent and nearly every habitat on Earth — from Arctic tundra to tropical rainforests, open oceans to urban centers. Understanding habitat preferences is essential for conservation planning and birdwatching.

Habitat Type	Example Species	Characteristics
Tropical Forest	Toucans, birds-of-paradise	Dense canopy, high species diversity
Temperate Forest	Woodpeckers, warblers	Seasonal, deciduous or coniferous
Grassland/Savanna	Ostriches, bustards	Open terrain, ground-nesting
Wetland/Marsh	Herons, rails	Shallow water, emergent vegetation
Marine/Pelagic	Albatrosses, petrels	Open ocean, salt gland adaptation
Desert/Arid	Roadrunners, sandgrouse	Water conservation, heat tolerance
Arctic/Alpine	Ptarmigans, snow buntings	Extreme cold, seasonal plumage

from birdfyi.api import BirdFYI

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

    # Regional presence — which birds live where
    regions = api.list_regional_presences()
    print(regions["count"])

    # Browse birds by country
    countries = api.list_countries()
    country = api.get_country("costa-rica")
    print(country["name"])  # Costa Rica — 900+ bird species

Learn more: Bird Habitats · Countries · Guides

Species Comparison

BirdFYI provides side-by-side comparison data for similar or commonly confused species. Comparisons cover size, plumage, range overlap, vocalizations, and behavioral differences — essential for field identification.

from birdfyi.api import BirdFYI

with BirdFYI() as api:
    # Browse featured species comparisons
    comparisons = api.list_comparisons()
    for comp in comparisons["results"][:3]:
        print(comp["name"])

    # Get a specific comparison
    comparison = api.get_comparison("bald-eagle-vs-golden-eagle")
    print(comparison["name"])  # Bald Eagle vs Golden Eagle

Learn more: Species Comparisons · Field Guides

Field Identification

Identifying birds in the field relies on multiple clues: size and shape (silhouette), plumage color and pattern, bill shape, flight style, habitat, song, and geographic range. BirdFYI's field guide data provides these identification markers for each species.

Identification Clue	What to Look For
Silhouette	Overall body shape, tail length, wing shape
Plumage	Color patterns, seasonal changes, age/sex differences
Bill Shape	Seed-cracking (finch), probing (shorebird), tearing (raptor)
Flight Pattern	Soaring, flapping, undulating, hovering
Habitat	Forest canopy vs understory, open water vs shoreline
Vocalization	Songs (territorial) vs calls (contact/alarm)

from birdfyi.api import BirdFYI

with BirdFYI() as api:
    # Search by physical or behavioral traits
    results = api.search("red breast songbird")
    for r in results["results"][:3]:
        print(r["name"])

Learn more: Bird Glossary · Identification Guides

Command-Line Interface

pip install "birdfyi[cli]"

birdfyi search "peregrine falcon"     # Search across all bird species

MCP Server (Claude, Cursor, Windsurf)

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

pip install "birdfyi[mcp]"

Add to your claude_desktop_config.json:

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

REST API Client

from birdfyi.api import BirdFYI

with BirdFYI() as api:
    birds = api.list_birds()              # Browse all 11,251 species
    families = api.list_families()        # Browse 258 families
    orders = api.list_orders()            # Browse 40 orders
    results = api.search("hummingbird")   # Full-text search

API Endpoints

Method	Endpoint	Description
GET	/api/v1/birds/	List all birds
GET	/api/v1/birds/{slug}/	Bird detail
GET	/api/v1/orders/	List all orders
GET	/api/v1/orders/{slug}/	Order detail
GET	/api/v1/families/	List all families
GET	/api/v1/families/{slug}/	Family detail
GET	/api/v1/habitats/	List all habitats
GET	/api/v1/countries/	List countries
GET	/api/v1/comparisons/	List species comparisons
GET	/api/v1/regional-presences/	List regional presences
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://birdfyi.com/api/v1/birds/?limit=3"

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

API Reference

Function	Description
BirdFYI()	Create API client (base_url, timeout)
list_birds(**params)	List all bird species
get_bird(slug)	Get bird detail
list_orders(**params)	List all orders
get_order(slug)	Get order detail
list_families(**params)	List all families
get_family(slug)	Get family detail
list_habitats(**params)	List all habitats
get_habitat(slug)	Get habitat detail
list_countries(**params)	List countries
get_country(slug)	Get country detail
list_comparisons(**params)	List species comparisons
list_regional_presences(**params)	List regional presences
list_glossary(**params)	List glossary terms
list_guides(**params)	List guides
search(query)	Search across all content

Learn More About Birds

• Browse: Bird Species Encyclopedia · Orders · Families
• Reference: Habitats · Countries
• Guides: Glossary · 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
birdfyi	PyPI	—	Bird species encyclopedia — birdfyi.com
speciesfyi	PyPI	—	Species taxonomy & biodiversity — speciesfyi.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