# @reng/air-quality

全球空气质量快照：AQI、污染物、花粉、天气。

## Intent

给人和 agent 一个**零密钥**的户外空气快照，字段对齐 Home Assistant 集成 [`yahooor/air_quality_cn`](https://github.com/yahooor/air_quality_cn)：可选 AQI 标准、PM2.5/PM10/O3/NO2/CO/SO2、花粉类型与过敏风险、温湿度风力紫外线。主数据源是对 [air-quality.com](https://air-quality.com) 的 **HTML 抓取**（搜索 `search_places` + 解析 place 页，与该 HA 集成相同思路）。**抓取可能因上游改版随时失效**——失败时可选回退到 Open-Meteo（全球污染物/AQI；花粉偏欧洲）以及北京花粉监测平台（北京各区）。托管小页可输入城市看完整快照。非医疗建议。

## Usage

```ts
import { getSnapshot, getAirQuality, getPollen, searchPlaces } from 'kody:@reng/air-quality'

const bj = await getSnapshot({ location: '北京', standard: 'aqi_cn' })
// { aqi, level, pollutants, pollen, weather, source: 'air-quality.com', summary, ... }

const sh = await getAirQuality({ location: '上海' })
const pollen = await getPollen({ location: 'Berlin' })
const hits = await searchPlaces({ term: '海淀', limit: 5 })
```

### Options

| Field | Notes |
| --- | --- |
| `location` | 中/英地名，先走 air-quality.com 搜索 |
| `place` | 直接路径，如 `china/beijing/ec8399ca` |
| `standard` | `aqi_cn`（默认）/`aqi_us`/`caqi_eu`/… |
| `fallback` | 默认 `true`：抓取失败则 Open-Meteo（+ 北京花粉） |

## Scraping warning

Primary upstream is **scraped**. air-quality.com may change markup, block bots, or invalidate `place_id`s. Expect breakage; check `warnings` / `source`. Do not rely on this for clinical or regulatory decisions.

## Fallbacks

1. Open-Meteo air-quality + forecast APIs (no key).
2. For 北京 / 海淀等区：北京花粉监测公共服务平台（思路参考 [RuochenLyu/beijing-pollen-monitor](https://github.com/RuochenLyu/beijing-pollen-monitor)）。
3. Japan Weathernews opendata **skipped**: ToS asks prior contact for internet publishing of results.

## Prerequisites

- Outbound HTTPS to `air-quality.com`, and optionally Open-Meteo / `pollenwechat.bjpws.com`.
- No secrets / OAuth.