天气预报国际版：空气质量数据接入实战（AQI 与六项污染物指标）
# 天气预报国际版：空气质量数据接入实战（AQI 与六项污染物指标）
> 接口：天气预报国际版（apiCode=3540）接入点 1 查询当前天气 · 免费接口 · POST/GET · JSON · 适用人群：健康/出行类应用开发者 · 阅读时间：约 6 分钟
## 核心要点
- 空气质量数据在 `now.air_quality` 对象中，**只有 3540-1（当前天气）接入点返回**；24 小时与 14 天预报不含空气质量。
- 一次返回 7 项指标：`aqi`（空气质量指数）、`pm2_5`、`pm10`、`o3`、`so2`、`no2`、`co`，外加主要污染物 `primary_pollutant`。
- 实测提示：多城市实测 `aqi` 均为 500，接入后建议在业务侧做合理性校验再对外展示。
## Why
晨跑提醒、过敏人群出行建议、儿童户外活动时间规划——这类功能的决策依据就是空气质量数据。很多天气接口要单独购买空气质量能力，而天气预报国际版把它作为当前天气返回的一部分直接给出，免费接口里能一次拿到 AQI 与六项污染物浓度，接入成本低。
本文讲清 `air_quality` 的字段结构、单位与展示建议，并如实说明实测中观察到的数据特征。
## What
| 项目 | 说明 |
|------|------|
| 所在接入点 | [查询当前天气（3540-1）](https://www.showapi.com/apiGateway/view/3540/1)，路径 `showapi_res_body.now.air_quality` |
| 返回指标 | `aqi`、`pm2_5`、`pm10`、`o3`、`so2`、`no2`、`co`、`primary_pollutant` |
| 污染物单位 | μg/m³（文档字段说明标注） |
| 计费 | 免费接口（防滥用档次限制） |
`air_quality` 字段速查：
| 字段 | 类型 | 单位 | 说明 |
|------|------|------|------|
| `aqi` | Number | - | 空气质量指数 |
| `pm2_5` | Number | μg/m³ | PM2.5 浓度 |
| `pm10` | Number | μg/m³ | PM10 浓度 |
| `o3` | Number | μg/m³ | 臭氧浓度 |
| `so2` | Number | μg/m³ | 二氧化硫浓度 |
| `no2` | Number | μg/m³ | 二氧化氮浓度 |
| `co` | Number | μg/m³ | 一氧化碳浓度 |
| `primary_pollutant` | String | - | 主要污染物（实测取值如 `co`） |
## How
### 1. 拉取空气质量并做健康分级提示
Python：
```python
# pip install requests
import requests
APPKEY = "YOUR_APPKEY"
def fetch_air_quality(city: str) -> dict:
resp = requests.post(
"https://route.showapi.com/3540-1",
params={"appKey": APPKEY, "name": city},
timeout=10,
)
body = resp.json()["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(f"业务错误: {body.get('remark')}")
aq = body["now"]["air_quality"]
return {
"city": body["cityInfo"]["city"],
"aqi": aq.get("aqi"),
"primary": aq.get("primary_pollutant"),
"pm2_5": aq.get("pm2_5"),
"pm10": aq.get("pm10"),
}
def health_tip(aqi):
"""按国内通用 AQI 分级给提示（aqi 数值建议业务侧校验后使用）。"""
if aqi is None:
return "暂无数据"
if aqi <= 50: return "优，适合户外活动"
if aqi <= 100: return "良，正常活动"
if aqi <= 150: return "轻度污染，敏感人群减少户外"
if aqi <= 200: return "中度污染，外出戴口罩"
if aqi <= 300: return "重度污染，避免户外活动"
return "严重污染，请留在室内"
aq = fetch_air_quality("北京")
print(f'{aq["city"]} AQI={aq["aqi"]} 主要污染物={aq["primary"]} -> {health_tip(aq["aqi"])}')
```
> 注意：`health_tip` 的分级区间是 AQI 的通用分级常识，**不代表官方对返回 `aqi` 数值的保证**——见下文"进阶与边界"的实测观察。
cURL：
```bash
curl -X POST "https://route.showapi.com/3540-1?appKey=YOUR_APPKEY&name=London"
```
Node.js：
```js
const res = await fetch(
`https://route.showapi.com/3540-1?appKey=${process.env.APPKEY}&name=London`,
{ method: "POST" }
);
const body = (await res.json()).showapi_res_body;
const aq = body.now.air_quality;
console.log(`AQI=${aq.aqi} PM2.5=${aq.pm2_5} 主要污染物=${aq.primary_pollutant}`);
```
### 2. 展示建议
- **排序展示**：把六项污染物按浓度对健康的"相对关注度"排序意义不大，直接平铺 + 高亮 `primary_pollutant` 即可。
- **单位标注**：所有污染物都标 μg/m³，AQI 不带单位。
## 返回示例与解析
实测（name=北京，3540-1）：
```json
"now": {
"air_quality": {
"primary_pollutant": "co",
"aqi": 500,
"pm10": 26,
"o3": 150,
"so2": 2.2,
"no2": 40.3,
"co": 480,
"pm2_5": 25.1
}
}
```
实测（name=London）：`aqi=500, pm2_5=4.4, pm10=7.8, o3=38, so2=0.9, no2=15.7, co=141, primary_pollutant=co`。文档返回示例同样是 `aqi=500, primary_pollutant=co`。
## 进阶与边界
- **`aqi=500` 的实测观察（重要）**：本文在北京、伦敦两地实测，`aqi` 均返回 500 且 `primary_pollutant=co`，与文档示例一致；同时两地分项污染物（pm2_5 等）数值差异明显且随城市变化。这提示 `aqi` 字段的数值可靠性存疑。**建议**：业务侧对 `aqi` 做合理性校验，或以分项污染物自行计算/对照后再展示 AQI 分级；本文不对此下"数据错误"的结论，仅如实记录实测现象。
- **只有当前天气有空气质量**：`hourList` 与 `dayList` 中没有 `air_quality`，无法做空气质量预报。
- **判空**：取 `air_quality` 及其子字段时统一判空，避免个别城市缺失导致空指针。
## FAQ
**Q1：为什么我在 24 小时预报里找不到空气质量？**
空气质量块只随当前天气（3540-1）返回，预报类接入点不包含。需要空气质量请调用 3540-1。
**Q2：`aqi` 超过 500 是数据错误吗？**
本文不下此结论，仅记录实测现象：多城市实测均为 500，与文档示例一致。建议接入后与当地权威站点数据交叉验证，再决定对外展示策略。
**Q3：`co` 的单位是 μg/m³ 吗？**
按文档字段说明，污染物单位标注为 μg/m³（文档示例 `co=130`/`141`/`480`）。如需 mg/m³ 换算，按业务口径自行处理。
**Q4：`primary_pollutant` 的取值有哪些？**
文档未给枚举表，实测取值为 `co`。展示时对未知取值做兜底（直接显示原值或"主要污染物：—"）。
**Q5：能拿到空气质量的预报吗？**
文档未提供空气质量预报能力，`air_quality` 只出现在当前天气返回中。
## 下一步阅读
- [天气预报国际版：当前天气接入实战（气温、体感、风、降水概率全字段）](https://www.showapi.com/guides/global-weather-current-weather-3540)
- [天气预报国际版：返回字段全解（cityInfo / now / hourList / dayList 一文读懂）](https://www.showapi.com/guides/global-weather-response-fields-3540)
- [天气预报国际版：免费档位下的缓存策略设计（用 Redis 省调用量）](https://www.showapi.com/guides/global-weather-cache-cost-3540)
- **本系列共 12 篇**：查看[天气预报国际版指南总目录](https://www.showapi.com/guides/global-weather-guides-3540)
