全国城市空气质量查询：城市空气质量排行榜接入与可视化指南
# 全国城市空气质量查询：城市空气质量排行榜接入与可视化指南
> 接口/接入点：全国城市空气质量查询（apiCode=104）· 104-41 排行榜 · 免费 · POST/GET · 返回 JSON · 适用人群：全栈工程师、数据可视化开发者 · 阅读时间：约 8 分钟
## 核心要点
- 104-41 返回 `showapi_res_body.list` 数组，每项含 `area`/`area_code`/`num`(排名)/`aqi`/`pm2_5`/`quality` 等。
- 列表按 AQI 升序（越靠前空气越好），`num` 即名次；实测约 340 条，文档上限「最多 367 城」。
- 可视化要点：取 Top N、按 `quality` 等级配色、处理 `o3_8h:"_"` 占位。
## Why：什么时候用排行榜
做「全国空气最好/最差城市榜」「呼吸指数排行榜」「空气质量大屏」，需要的是一组城市而非单城。104-41 一次返回全国主要城市的排名列表，适合做榜单、地图热力、大屏轮播。
## What：接口速览
| 项 | 内容 |
|----|------|
| 地址 | `https://route.showapi.com/104-41?appKey={your_appKey}` |
| 必填参数 | 无（返回全量排行榜） |
| 返回结构 | `showapi_res_body.list` 数组 |
| 成功判定 | `showapi_res_body.ret_code == 0` |
## How：取榜 + 取 Top N + 渲染
### Python：取全国最佳 Top 10
```python
import requests
url = "https://route.showapi.com/104-41"
resp = requests.post(url, params={"appKey": "YOUR_APPKEY"}, timeout=10).json()
body = resp.get("showapi_res_body", {})
if body.get("ret_code") != 0:
raise RuntimeError(body.get("remark") or "查询失败")
rank = body["list"] # 已是按 AQI 升序的排名列表
top10 = [
{
"rank": int(c["num"]),
"city": c["area"],
"aqi": int(c["aqi"]),
"pm25": int(c["pm2_5"]),
"quality": c["quality"],
}
for c in rank[:10]
]
print(top10)
```
### 前端：榜单行渲染（含等级配色）
```html
<tr class="q-{{ quality }}">
<td>{{ rank }}</td>
<td>{{ city }}</td>
<td>{{ aqi }}</td>
<td>{{ pm25 }}</td>
<td>{{ quality }}</td>
</tr>
```
### cURL 速测
```bash
curl -X POST "https://route.showapi.com/104-41?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
## 返回示例与解析
实测 `list` 首项为 `{"area":"伊春","num":"1","aqi":"10","quality":"优质", ...}`，末段出现 `quality=轻度污染`（如和田 AQI=140）。`num` 连续递增即名次；`area_code` 为拼音（如 `yichunshi`），可作稳定 key。
## 进阶 / 边界
- **数量口径**：文档写「最多 367 城」，实测当前约 340 条；按上限理解，名次以 `num` 为准，不要硬编码总数。
- **疑似重复行**：实测榜单中「咸阳」「安庆」等出现 2 次（不同 `num`），建议前端按 `area_code` 去重后再展示，或向官方反馈数据去重。
- **数据新鲜度**：全列表 `ct` 时间戳一致（同一批次），适合按固定节奏（如每半小时）整表缓存刷新。
- **配色映射**：等级 → 颜色建议见系列第 6 篇。
## FAQ
**Q1：排行榜是按 AQI 升序还是降序？**
实测按 AQI 升序，`num=1` 为空气最好（AQI 最小）的城市；越靠后污染越重。
**Q2：为什么有的城市出现两次？**
实测观察到个别城市重复（如咸阳、安庆），疑似数据未去重；展示前建议按 `area_code` 去重。
**Q3：list 一次全返回，数据量大吗？**
约 340 条，单次返回体积可控；配合缓存整表刷新即可，无需逐城查询。
**Q4：能做地图热力图吗？**
接口返回 `area_code`（拼音）但不含经纬度；地图标点需另接地理编码，把城市名/编码映射到坐标。
## 相关能力 / 下一步阅读
- [全国城市空气质量查询：返回字段全解（AQI/PM2.5/质量等级一文读懂）](https://www.showapi.com/guides/air-quality-response-fields-104)
- [全国城市空气质量查询：单城市实时查询集成指南（从请求到 UI 展示）](https://www.showapi.com/guides/air-quality-query-integration-104)
- [全国城市空气质量查询：空气质量等级（优质/良好/污染）判定与配色指南](https://www.showapi.com/guides/air-quality-quality-levels-104)
- **本系列共 11 篇**：查看[全国城市空气质量查询 · 指南总目录](https://www.showapi.com/guides/air-quality-guides-104)
