全国城市空气质量查询：返回字段全解（AQI/PM2.5/质量等级一文读懂）
# 全国城市空气质量查询：返回字段全解（AQI/PM2.5/质量等级一文读懂）
> 接口/接入点：全国城市空气质量查询（apiCode=104）· 104-41 排行榜 / 104-42 单城查询 · 免费 · 返回 JSON · 适用人群：所有接入开发者 · 阅读时间：约 6 分钟
## 核心要点
- 业务数据统一包裹在 `showapi_res_body` 内；系统级字段 `showapi_res_code`/`showapi_res_error`/`showapi_fee_num` 在 body 外层。
- 核心字段：`aqi`、`pm2_5`、`pm10`、`co/no2/so2/o3/o3_8h`、`primary_pollutant`、`quality`、`ct`、`area`；排行榜额外含 `area_code`、`num`（排名）。
- 注意边界：`o3_8h` 无数据时返回 `"_"`；`primary_pollutant` 优/良时为空 `""`；`remark` 为系统附加说明字段。
## Why：为什么先搞懂字段
字段是后续一切解析、展示、配色、缓存的基础。空气质量接口的单位口径（μg/m³ vs mg/m³）、等级文字、空值占位都和「常规 JSON 直觉」不同。先把字段吃透，能少踩一半坑。
## What：接口速览
| 项 | 内容 |
|----|------|
| 单城查询地址 | `https://route.showapi.com/104-42?appKey={your_appKey}` |
| 排行榜地址 | `https://route.showapi.com/104-41?appKey={your_appKey}` |
| 公共封装 | `showapi_res_code`(0成功)、`showapi_res_error`、`showapi_fee_num`(消耗额度次数) |
| 业务封装 | `showapi_res_body`（所有业务字段在内） |
| 成功判定 | `showapi_res_body.ret_code == 0` |
## How：读懂一次返回
以 104-42 单城查询「北京」为例（实测节选）：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_fee_num": 1,
"showapi_res_body": {
"remark": "查询成功！",
"primary_pollutant": "",
"aqi": "18",
"pm2_5": "3",
"pm10": "11",
"co": "0.3",
"no2": "11",
"so2": "3",
"o3": "57",
"o3_8h": "_",
"quality": "优质",
"area": "北京",
"area_code": "beijing",
"num": "41",
"ct": "2026-08-31 11:10:00.012",
"ret_code": 0
}
}
```
## 返回示例与解析：字段对照表
| 字段 | 类型 | 单位/取值 | 说明 |
|------|------|----------|------|
| `aqi` | String | 整数文本 | 空气质量指数（AQI），无量纲 |
| `pm2_5` | String | μg/m³ | 细颗粒物（粒径 ≤2.5μm）1 小时平均 |
| `pm10` | String | μg/m³ | 颗粒物（粒径 ≤10μm）1 小时平均 |
| `co` | String | mg/m³ | 一氧化碳 1 小时平均 |
| `no2` | String | μg/m³ | 二氧化氮 1 小时平均 |
| `so2` | String | μg/m³ | 二氧化硫 1 小时平均 |
| `o3` | String | μg/m³ | 臭氧 1 小时平均 |
| `o3_8h` | String | μg/m³ 或 `"_"` | 臭氧 8 小时滑动平均；**无数据时返回 `"_"`（占位，非数字）** |
| `primary_pollutant` | String | 如「细颗粒物(PM2.5)」/ 空 | 首要污染物；**优/良等级时为空字符串 `""`** |
| `quality` | String | 6 类文本 | 空气质量等级：优质/良好/轻度污染/中度污染/重度污染/严重污染 |
| `ct` | String | 时间文本 | 数据发布时间 |
| `area` | String | 城市名 | 实际返回的城市（小地区会回退到上级城市） |
| `area_code` | String | 拼音 | 城市编码，如 `beijing` |
| `num` | String | 整数文本 | 排行榜名次（仅 104-41 列表项含此字段） |
| `remark` | String | 说明文本 | 系统附加说明（如「查询成功！」），非核心业务字段 |
| `ret_code` | Number/String | 0 成功 | 业务状态码，在 `showapi_res_body` 内 |
> 104-41 排行榜返回 `showapi_res_body.list` 数组，数组每一项即上表中的单条记录（含 `area_code`、`num`）。
## 进阶 / 边界
- **值为字符串**：所有数值字段都是字符串（如 `"18"`），解析时按需 `int()` 转换，避免直接做数值比较。
- **`o3_8h == "_"` 处理**：展示前先判断是否为 `"_"`，是则显示「暂无」而非 0 或 NaN。
- **`primary_pollutant` 空值**：优/良时为空，UI 上不要显示「首要污染物：无」造成歧义，可直接隐藏该行。
- **排行榜数量**：文档表述「最多 367 城」，实测返回约 340 条，按上限口径理解即可，名次以 `num` 为准。
## FAQ
**Q1：为什么 o3_8h 有时是下划线 `_`？**
该字段无监测数据时以 `"_"` 占位（非数字）。展示前需做空值/占位判断，不要直接当作数值。
**Q2：quality 的 6 类具体是哪 6 类？**
优质、良好、轻度污染、中度污染、重度污染、严重污染（以线上实际返回文字为准）。
**Q3：ret_code 和 showapi_res_code 有什么区别？**
`showapi_res_code` 是系统级（0 表示接口调用层成功），`ret_code` 在 `showapi_res_body` 内表示业务结果（0 成功）；建议两者都为 0 再使用数据。
**Q4：字段都是字符串，能直接排序/比较吗？**
不能。AQI、PM 等均为字符串文本，使用前先转换为数值类型；排行榜的 `num` 同理。
**Q5：area_code 有什么用？**
可作为城市唯一键用于缓存 key 或地图/图标映射；不同输入（如「北京」「北京市」）回退后 `area_code` 稳定。
## 相关能力 / 下一步阅读
- [全国城市空气质量查询：空气质量等级（优质/良好/污染）判定与配色指南](https://www.showapi.com/guides/air-quality-quality-levels-104)
- [全国城市空气质量查询：单城市实时查询集成指南（从请求到 UI 展示）](https://www.showapi.com/guides/air-quality-query-integration-104)
- **本系列共 11 篇**：查看[全国城市空气质量查询 · 指南总目录](https://www.showapi.com/guides/air-quality-guides-104)
