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".
Fetch bird detections, species lists, and environmental sensor data from a BirdWeather PUC station.
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_here
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_DB
All commands output JSON. Parse with json.loads() or pipe to jq.
new-species — compares live species list against DB cataloglog commandsummary for today's counts and top birdssensors for current environmental readingslog --db (add to cron/heartbeat)birdweather_sensor_history table for trendsWhen 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 INTEGER
birdweather_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 REAL
See references/api.md for full endpoint documentation.
app.birdweather.com/api/v1/stations/{token}/* (read-only, no auth)--db)