全国城市空气质量查询：空气质量等级（优质/良好/污染）判定与配色指南
# 全国城市空气质量查询：空气质量等级（优质/良好/污染）判定与配色指南
> 接口/接入点：全国城市空气质量查询（apiCode=104）· 104-41/104-42 · 免费 · 返回 JSON · 适用人群：前端/全栈开发者、产品 · 阅读时间：约 6 分钟
## 核心要点
- 等级字段 `quality` 共 6 类：优质、良好、轻度污染、中度污染、重度污染、严重污染（以线上实际返回文字为准）。
- 接口直接给等级文字，无需自行按 AQI 反推；但做配色/图标映射时建议以 `quality` 字符串做 switch。
- 配色遵循国内通行约定：优→绿、良→黄、轻/中/重/严重污染→橙/红/紫/褐红。
## Why：为什么专门讲等级
用户看不懂 AQI 数值，但能秒懂「绿/黄/红」。等级是连接数据与用户情绪的桥梁，也是健康提醒的触发开关。把等级文字稳定地映射成颜色、图标、话术，是空气质量产品的核心一环。
## What：等级与字段
| 项 | 内容 |
|----|------|
| 等级字段 | `quality`（String，6 类文本） |
| 数值字段 | `aqi`（AQI 指数，字符串） |
| 首要污染物 | `primary_pollutant`（优/良时为空） |
## How：等级 → 颜色/话术映射
```js
// 以 quality 文字做映射，避免依赖数值反推
const LEVEL = {
"优质": { color: "#00e400", label: "空气优质", advice: "适宜户外活动" },
"良好": { color: "#ffd700", label: "空气良好", advice: "可正常活动" },
"轻度污染": { color: "#ff7e00", label: "轻度污染", advice: "敏感人群减少户外" },
"中度污染": { color: "#ff0000", label: "中度污染", advice: "减少户外活动" },
"重度污染": { color: "#8f3f97", label: "重度污染", advice: "避免户外活动" },
"严重污染": { color: "#7e0023", label: "严重污染", advice: "尽量留室内" },
};
function render(quality) {
const lv = LEVEL[quality] || LEVEL["良好"];
return { color: lv.color, text: lv.label, advice: lv.advice };
}
```
### Python 判定（用 quality 直接分支）
```python
def advice(quality: str) -> str:
return {
"优质": "适宜户外活动",
"良好": "可正常活动",
"轻度污染": "敏感人群减少户外",
"中度污染": "减少户外活动",
"重度污染": "避免户外活动",
"严重污染": "尽量留室内",
}.get(quality, "数据异常")
```
## 返回示例与解析
实测「北京」`quality=优质`、`aqi=18`；「成都」`quality=良好`、`aqi=52`、`primary_pollutant=细颗粒物(PM2.5)`；「和田」`quality=轻度污染`、`aqi=140`。可见等级与 `aqi` 方向一致，但接口已直接给文字，优先用 `quality`。
## 进阶 / 边界
- **以 `quality` 为准**：虽 AQI 与等级有对应区间，但接口已给等级文字，直接用最稳；自算阈值易与官方口径偏差。
- **文案一致性**：线上返回为「优质」（非「优」），UI 文案与接口保持一致，避免「优/优质」混用。
- **空首要污染物**：优/良时 `primary_pollutant` 为空，提醒话术里不要出现「首要污染物：无」这类误导表述。
- **权限提醒**：健康建议仅作参考，敏感人群请以官方发布为准，避免过度承诺。
## FAQ
**Q1：等级是「优」还是「优质」？**
线上实际返回为「优质」（6 类：优质/良好/轻度污染/中度污染/重度污染/严重污染），以线上返回为准。
**Q2：能只靠 AQI 数值自己算等级吗？**
可以但不推荐；接口已直接给出 `quality` 文字，优先使用，避免阈值口径与官方不一致。
**Q3：配色有标准吗？**
参考国内通行的空气质量色阶（绿/黄/橙/红/紫/褐红），上表给出一组可直接用的映射。
**Q4：首要污染物为空时要怎么展示？**
优/良时为空属正常，建议隐藏「首要污染物」一行，而非显示「无」。
## 相关能力 / 下一步阅读
- [全国城市空气质量查询：返回字段全解（AQI/PM2.5/质量等级一文读懂）](https://www.showapi.com/guides/air-quality-response-fields-104)
- [全国城市空气质量查询：旅游 / 健康类应用的落地方案](https://www.showapi.com/guides/air-quality-travel-health-104)
- [全国城市空气质量查询：环境监测与智能设备的低成本集成](https://www.showapi.com/guides/air-quality-iot-monitor-104)
- **本系列共 11 篇**：查看[全国城市空气质量查询 · 指南总目录](https://www.showapi.com/guides/air-quality-guides-104)
