| name | historical-air-quality |
| description | Use when a user wants to see air quality trends over days or weeks, including daily averages, min/max, and CSV export. |
Retrieve Historical Air Quality
Fetch pollutant concentrations for a location across a date range. Summarize daily means, min/max, and data gaps; optionally export as CSV.
When to use
- User asks "what was air quality like last week in [city]?"
- User wants to analyze pollution trends over a date range
- User needs to export historical data for external analysis
- User is investigating air quality during a specific event or period
Inputs to gather
- Location: City name, address, or
lat,lon
- Start date: ISO 8601 format (YYYY-MM-DD) or human-readable (e.g., "7 days ago", "last Monday")
- End date: ISO 8601 or human-readable; defaults to today if not provided
- Pollutant filter (optional): PM2.5, PM10, O3, NO2, SO2, CO — if not specified, return all available
Procedure
- Load config from
${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/air-quality-toolkit/config.json.
- Convert dates to ISO 8601 format; stop if end date is in the future.
- Prefer OpenAQ v3 for historical data (best coverage and granularity):
GET https://api.openaq.org/v3/locations?coordinates={lat},{lon}&radius=10000 to get location ID.GET https://api.openaq.org/v3/measurements?locationId={id}&dateFrom={YYYY-MM-DD}T00:00:00Z&dateTo={YYYY-MM-DD}T23:59:59Z&limit=10000 (paginate if needed).
- Fall back to WAQI
/historic/ endpoint if OpenAQ fails (limited to 30 days):
GET https://api.waqi.info/feed/geo:{lat};{lon}/history/?token={TOKEN}&month={YYYY-MM} (WAQI provides monthly data).
- Cache full responses under
${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/air-quality-toolkit/cache/historic/{source}_{location_slug}_{YYYYMM}.json.
- Aggregate data: compute daily means, min/max per pollutant; count missing days.
- If pollutant filter is provided, return only those columns.
Output / side effects
Print a markdown table of daily summary:
| Date | PM2.5 (µg/m³) | PM10 (µg/m³) | O3 (ppb) | Notes |
|------------|---------------|--------------|----------|-----------------|
| 2026-04-20 | 32 (28–41) | 54 (48–62) | 18 (15–22) | |
| 2026-04-21 | 28 (24–35) | 50 (42–61) | 22 (19–26) | PM10 peak |
| 2026-04-22 | — | — | — | No data |
Include a summary:
- Mean concentrations per pollutant across the period
- Peak / min values per pollutant and dates
- Days with missing data: [count and dates]
- Data source: [openaq | waqi]
Offer to write raw data as CSV:
- Prompt user for output path (default: current working directory).
- CSV columns:
date, pollutant, value, unit, source.
- Write to
{user_path}/{location_slug}_{YYYYMMDD}_{YYYYMMDD}.csv.
Safety / constraints
- If the requested date range exceeds 90 days and the user hasn't provided an API key, warn that OpenAQ free tier may have limits; offer to limit the query to 30 days.
- If a date has no coverage from any source, report it clearly rather than interpolating.
- Do not extrapolate or smooth data without explicit user consent.
