- name
- birdweather-puc
- description
- Access BirdWeather PUC station data — species detections, sensor readings (AQI, temperature, humidity, pressure, eCO₂, sound dB), and historical trends. Use when the user asks about backyard birds, what species were detected recently, air quality from a BirdWeather station, new species arrivals, or wants alerts when a species is detected for the first time. Requires a BirdWeather station token (free from app.birdweather.com). Triggers on phrases like "what birds have I heard", "new species today", "BirdWeather detections", "backyard birds", "PUC sensor readings".
BirdWeather PUC
Fetch bird detections, species lists, and environmental sensor data from a BirdWeather PUC station.
Setup
BirdWeather tokens are public (no auth required for read access). Find yours at: app.birdweather.com → Station Settings → Token
Store token in environment or pass directly:
export BIRDWEATHER_TOKEN=your_token_hereCore Script
Use scripts/birdweather.py for all data access:
# Daily summary — detections, species count, top birds, sensors
python3 scripts/birdweather.py summary --token TOKEN
# Recent detections (last N, default 10)
python3 scripts/birdweather.py detections --token TOKEN --limit 20
# Top species for a time period
python3 scripts/birdweather.py species --token TOKEN --period week
# Current sensor readings (AQI, temp, humidity, pressure, eCO₂, sound dB)
python3 scripts/birdweather.py sensors --token TOKEN
# Log sensor snapshot to SQLite (for history/trends)
python3 scripts/birdweather.py log --token TOKEN --db PATH_TO_DB
# Check for new species (first-ever detections vs. known catalog)
python3 scripts/birdweather.py new-species --token TOKEN --db PATH_TO_DBAll commands output JSON. Parse with json.loads() or pipe to jq.
Workflows
New Species Alert
- Run
new-species— compares live species list against DB catalog - If new species found: alert user with common name, scientific name, confidence, timestamp
- Update DB with
logcommand
Daily Summary
- Run
summaryfor today's counts and top birds - Run
sensorsfor current environmental readings - Combine into a brief — detections, species count, top 3-5 birds, AQI/temp
Sensor Trend Analysis
- Log regularly with
log --db(add to cron/heartbeat) - Query SQLite
birdweather_sensor_historytable for trends - Look for AQI spikes, temperature patterns, sound level changes
SQLite Schema
When using --db, two tables are maintained:
birdweather_species — cumulative species catalog:
species_id INTEGER, common_name TEXT, scientific_name TEXT,
color TEXT, thumbnail_url TEXT, first_detected_at TEXT,
detection_count INTEGERbirdweather_sensor_history — time-series sensor log:
id INTEGER PRIMARY KEY, recorded_at TEXT,
temp_f REAL, humidity REAL, pressure REAL,
aqi REAL, eco2 REAL, sound_db REAL, voc REALAPI Reference
See references/api.md for full endpoint documentation.
System Access
- Network:
app.birdweather.com/api/v1/stations/{token}/*(read-only, no auth) - Disk: SQLite DB at user-specified path (optional, only with
--db) - No credentials stored — token is passed per-invocation