---
title: Perch
emoji: 🐦
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Ask questions about bird distributions in plain language
---

# Perch

Plain-language questions about bird distribution, range and abundance, answered
over [eBird Status and Trends](https://science.ebird.org/en/status-and-trends)
data from the Cornell Lab of Ornithology.

Ask something like *"animate how Ruby-throated Hummingbird abundance shifts
through the year"* and Perch picks the datasets, writes the SQL, runs it, and
returns a map, a chart and an explanation. No GIS software, no SQL.

## What's inside

- **16 species across six continents** — 82 datasets covering weekly abundance,
  seasonal ranges and regional statistics, on an H3 hexagon grid.
- **A tool-calling agent** (Gemini) that searches the catalog, inspects schemas,
  writes DuckDB SQL, and fans out to parallel sub-agents for multi-species
  questions.
- **Spatial joins** against Natural Earth country and state boundaries.

The API and the frontend are served by the same FastAPI process, so there is one
origin and no CORS.

## Configuration

Set `GOOGLE_API_KEY` as a Space secret. Without it the app loads but cannot
answer questions.

## Data and attribution

Bird data: eBird Status and Trends, Cornell Lab of Ornithology (2023 release).
Boundaries: Natural Earth. Species photographs and recordings come from Wikimedia
Commons under Creative Commons licences, each credited in the app beside the
image and the audio player.