historical-air-quality

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

1. Load config from ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/air-quality-toolkit/config.json.
2. Convert dates to ISO 8601 format; stop if end date is in the future.
3. 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).
4. 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).
5. 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.
6. Aggregate data: compute daily means, min/max per pollutant; count missing days.
7. 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.