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