Photo: Stephanie Rinehart-Joseph / Macaulay Library ML37851091
CLI tool to check for recent snowy owl observations using the eBird API.
uv sync
export EBIRD_API_KEY=your-key-here
Get an API key by signing up at https://ebird.org/api/keygen.
For email alerts, set up Gmail SMTP credentials:
export GMAIL_USER=you@gmail.com
export GMAIL_APP_PASSWORD=your-app-password
Generate an app password at https://myaccount.google.com/apppasswords (requires 2FA).
List recent sightings:
uv run snowy sightings
Defaults to Salem, MA with a 30-mile radius over the last 14 days. Override with options:
uv run snowy sightings --lat 40.71 --lng -74.01 --dist 50 --days 30
Check for new sightings and send email alerts:
uv run snowy check --to "you@gmail.com,spouse@gmail.com"
This tool uses the eBird API 2.0 endpoint GET /v2/data/obs/geo/recent/{speciesCode} to fetch recent nearby observations of a species.
| Parameter | Description |
|---|---|
lat |
Latitude |
lng |
Longitude |
dist |
Search radius in km (max 50) |
back |
Number of days back to search (max 30) |
Authentication is via the X-eBirdApiToken header.
Each observation is returned as a JSON object with these fields:
| Field | Description |
|---|---|
speciesCode |
eBird species code (e.g. snoowl1) |
comName |
Common name (e.g. "Snowy Owl") |
sciName |
Scientific name |
locName |
Location name |
obsDt |
Observation date and time |
howMany |
Number of birds observed |
lat |
Latitude of observation |
lng |
Longitude of observation |
subId |
Checklist submission ID (e.g. S304358788) |
Checklist URLs can be constructed as https://ebird.org/checklist/{subId}.
A scheduled workflow (.github/workflows/check.yml) runs the check command automatically. It checks hourly between 6am–6pm EST, October through April (snowy owl season), and can also be triggered manually.
The workflow requires the following repository configuration:
Secrets: EBIRD_API_KEY, GMAIL_USER, GMAIL_APP_PASSWORD
Variables: EMAIL_TO (comma-separated recipient addresses)
Previously seen sightings are tracked in a GitHub Actions cache to avoid duplicate alerts.
The check command stores state in a GitHub Actions cache to avoid duplicate alerts. To reset it and re-send alerts for all current sightings:
gh cache delete snowy-state