Metadata-Version: 2.4
Name: birdfyi
Version: 0.1.1
Summary: Bird species encyclopedia API client — birdfyi.com
Project-URL: Homepage, https://birdfyi.com
Project-URL: Documentation, https://birdfyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/birdfyi
Project-URL: Issues, https://github.com/fyipedia/birdfyi/issues
Project-URL: Changelog, https://github.com/fyipedia/birdfyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: avian,bird,birdwatching,conservation,habitat,ornithology,species,wildlife
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# birdfyi

[![PyPI version](https://agentgif.com/badge/pypi/birdfyi/version.svg)](https://pypi.org/project/birdfyi/)
[![Python](https://img.shields.io/pypi/pyversions/birdfyi)](https://pypi.org/project/birdfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/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](https://birdfyi.com/), 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](https://www.worldbirdnames.org/) and [BirdLife International](https://www.birdlife.org/) data.

> **Explore bird data at [birdfyi.com](https://birdfyi.com/)** — browse [birds](https://birdfyi.com/birds/), [orders](https://birdfyi.com/orders/), [families](https://birdfyi.com/families/), [habitats](https://birdfyi.com/habitats/), and [field guides](https://birdfyi.com/guides/).

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/birdfyi/main/demo.gif" alt="birdfyi demo — bird species lookup, taxonomy browsing, and ornithology search in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Bird Taxonomy](#bird-taxonomy)
  - [Orders and Families](#orders-and-families)
  - [Habitats and Regional Presence](#habitats-and-regional-presence)
  - [Species Comparison](#species-comparison)
  - [Field Identification](#field-identification)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Birds](#learn-more-about-birds)
- [Nature FYI Family](#nature-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
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:

```bash
uvx --from birdfyi birdfyi search "bald eagle"
```

## Quick Start

```python
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](https://www.worldbirdnames.org/), 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).

```python
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](https://birdfyi.com/orders/) · [Bird Families](https://birdfyi.com/families/) · [Ornithology Glossary](https://birdfyi.com/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 |

```python
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](https://birdfyi.com/orders/) · [Family Encyclopedia](https://birdfyi.com/families/)

### 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 |

```python
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](https://birdfyi.com/habitats/) · [Countries](https://birdfyi.com/countries/) · [Guides](https://birdfyi.com/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.

```python
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](https://birdfyi.com/glossary/) · [Field Guides](https://birdfyi.com/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) |

```python
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](https://birdfyi.com/glossary/) · [Identification Guides](https://birdfyi.com/guides/)

## Command-Line Interface

```bash
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](https://modelcontextprotocol.io/).

```bash
pip install "birdfyi[mcp]"
```

Add to your `claude_desktop_config.json`:

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

## REST API Client

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

```bash
curl -s "https://birdfyi.com/api/v1/birds/?limit=3"
```

Full API documentation at [birdfyi.com/developers/](https://birdfyi.com/developers/).
OpenAPI 3.1.0 spec: [birdfyi.com/api/openapi.json](https://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](https://birdfyi.com/birds/) · [Orders](https://birdfyi.com/orders/) · [Families](https://birdfyi.com/families/)
- **Reference**: [Habitats](https://birdfyi.com/habitats/) · [Countries](https://birdfyi.com/countries/)
- **Guides**: [Glossary](https://birdfyi.com/glossary/) · [Guides](https://birdfyi.com/guides/)
- **API**: [REST API Docs](https://birdfyi.com/developers/) · [OpenAPI Spec](https://birdfyi.com/api/openapi.json)

## Nature FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — living organisms, wildlife, and natural history.

| Package | PyPI | Description |
|---------|------|-------------|
| speciesfyi | [PyPI](https://pypi.org/project/speciesfyi/) | 49,112 species, 17,982 taxa, 846 ecoregions — [speciesfyi.com](https://speciesfyi.com/) |
| **birdfyi** | [PyPI](https://pypi.org/project/birdfyi/) | **11,251 birds, 40 orders, 258 families — [birdfyi.com](https://birdfyi.com/)** |
| fishfyi | [PyPI](https://pypi.org/project/fishfyi/) | 78 fish species, 48 orders, 188 families — [fishfyi.com](https://fishfyi.com/) |
| plantfyi | [PyPI](https://pypi.org/project/plantfyi/) | 379,774 plants, 734 families, 50 orders — [plantfyi.com](https://plantfyi.com/) |
| dinofyi | [PyPI](https://pypi.org/project/dinofyi/) | 6,142 dinosaurs, 15 periods, 198 countries — [dinofyi.com](https://dinofyi.com/) |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies — [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata for 3,953 emojis — [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats — [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings — [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS — [fontfyi.com](https://fontfyi.com/) |
| **birdfyi** | [PyPI](https://pypi.org/project/birdfyi/) | — | Bird species encyclopedia — [birdfyi.com](https://birdfyi.com/) |
| speciesfyi | [PyPI](https://pypi.org/project/speciesfyi/) | — | Species taxonomy & biodiversity — [speciesfyi.com](https://speciesfyi.com/) |
| fishfyi | [PyPI](https://pypi.org/project/fishfyi/) | — | Fish species & marine biology — [fishfyi.com](https://fishfyi.com/) |
| plantfyi | [PyPI](https://pypi.org/project/plantfyi/) | — | Plant taxonomy & cultivation — [plantfyi.com](https://plantfyi.com/) |
| dinofyi | [PyPI](https://pypi.org/project/dinofyi/) | — | Dinosaur paleontology & fossil record — [dinofyi.com](https://dinofyi.com/) |

## License

MIT
