retrieve-air-quality

name	retrieve-air-quality
description	Use when a user wants current air quality for their location or a specific place, including AQI, dominant pollutant, and health category.

Retrieve Current Air Quality

Fetch real-time air quality data for a location. Tries the user's favourite data source first, then falls back automatically to alternative sources if needed.

When to use

• User asks "what's the air quality in [city]?"
• User wants current AQI and pollutant levels
• User is checking air quality before outdoor activities
• No specific time range is requested (use historical-air-quality for time-series data)

Inputs to gather

• Location: City name (e.g., Jerusalem), address, or lat,lon (e.g., 31.7683,35.2137)
• If not provided, fall back to default_location from config; if that's also missing, ask the user.

Procedure

1. Load config from ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/air-quality-toolkit/config.json.
2. If no WAQI token and waqi is the favourite source, stop and point the user to the configure skill to add the token.
3. Determine location: use provided input, or fall back to default_location from config.
4. Try sources in order: favourite first, then waqi → openaq → airelibre.
5. For each source, attempt the API call:
   • WAQI: GET https://api.waqi.info/feed/{city}/?token={TOKEN} (city name) or https://api.waqi.info/feed/geo:{lat};{lon}/?token={TOKEN} (coordinates)
   • OpenAQ v3: GET https://api.openaq.org/v3/locations?coordinates={lat},{lon}&radius=10000 then fetch /measurements?locationId={id}&limit=100 (use first result)
   • AireLibre: GET https://rald-dev.greenbeats.com.py/api/data/ (Paraguay-focused; only use as last resort or if location is in Paraguay region)
6. On network error, rate limit, or missing data, try the next source silently.
7. Cache successful response in ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/air-quality-toolkit/cache/{source}_{location_slug}_{YYYYMMDDHH}.json (1-hour TTL); reuse if still valid.
8. Parse response and extract pollutants and AQI; if source does not provide AQI, use the calculate-aqi skill if pollutant concentrations are available.

Output / side effects

Print a clean markdown table:

| Pollutant   | Concentration | Unit   | AQI Contribution |
|-------------|----------------|--------|------------------|
| PM2.5       | 45.2           | µg/m³  | 120              |
| PM10        | 62.1           | µg/m³  | 95               |
| O3          | 28.5           | ppb    | 42               |

Then summarize:

• Overall AQI: [value]
• Category: Good / Moderate / Unhealthy for Sensitive Groups / Unhealthy / Very Unhealthy / Hazardous
• Dominant pollutant: [name]
• Data source: [waqi | openaq | airelibre]
• Timestamp: [ISO 8601]

Safety / constraints

• If all sources fail (network down, all tokens invalid, location not found), report which sources were attempted and suggest checking the configure skill or location spelling.
• Do not retry the same source immediately on transient errors; move to the next source.
• Cache entries older than 1 hour should be discarded; don't serve stale data without warning.