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