全国城市空气质量查询：在微信小程序 / 智能设备中展示空气质量
# 全国城市空气质量查询：在微信小程序 / 智能设备中展示空气质量
> 接口/接入点：全国城市空气质量查询（apiCode=104）· 104-41/104-42 · 免费 · 返回 JSON · 适用人群：小程序/嵌入式开发者 · 阅读时间：约 7 分钟
## 核心要点
- 免费接口适合做轻量「空气卡片」：小程序首页挂件、智能屏/音箱播报、净化器状态页。
- 严禁在小程序/设备前端硬编码 AppKey：走自有后端代理，避免密钥泄露与免费额度被刷。
- 配合定时拉取 + 短时缓存（见系列第 7 篇），既能实时又能控额度。
## Why：嵌入式/小程序场景的价值
用户不需要打开专业气象站，只要一眼看到「今天空气好不好、要不要戴口罩」。小程序挂件、智能音箱早报、带屏设备状态栏，都是低成本增强体验的好场景——而这个接口免费、字段齐全，正好兜底。
## What：接口速览
| 项 | 内容 |
|----|------|
| 单城查询 104-42 | `https://route.showapi.com/104-42?appKey={your_appKey}`，必填 `area` |
| 排行榜 104-41 | `https://route.showapi.com/104-41?appKey={your_appKey}`，无必填参数 |
| 计费 | 免费（每次调用计 1 额度） |
## How：小程序侧最小实现
### 后端代理（Node.js / Express 示例）
```js
// 服务端：代理查询，保护 AppKey
app.get("/api/air/:city", async (req, res) => {
const url = `https://route.showapi.com/104-42?appKey=${process.env.SHOWAPI_KEY}`;
const r = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ area: req.params.city }),
});
const json = await r.json();
const b = json.showapi_res_body;
if (b.ret_code !== 0) return res.status(502).json({ error: b.remark });
res.json({
city: b.area, aqi: +b.aqi, pm25: +b.pm2_5,
quality: b.quality, pollutant: b.primary_pollutant || null,
});
});
```
### 小程序 WXML 卡片
```xml
<view class="air-card">
<text>{{city}} · {{quality}}</text>
<text>AQI {{aqi}} PM2.5 {{pm25}}</text>
</view>
```
### cURL 速测（后端调试）
```bash
curl -X POST "https://route.showapi.com/104-42?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" -d "area=%E5%B9%BF%E5%B7%9E"
```
## 返回示例与解析
查「广州」实测 `quality=优质`、`aqi=15`、`pm2_5=9`；返回体 `area` 为实际城市（小地区回退），展示时用它。设备端可据此决定播报文本，如「当前空气优质，适宜户外活动」。
## 进阶 / 边界
- **AppKey 安全**：小程序包体会被反编译，绝不可内置 AppKey；一律走自有后端，密钥存环境变量。
- **刷新节奏**：空气质量半小时级变化，设备可每 30 分钟拉一次 + 本地缓存，避免频繁调用耗尽免费额度。
- **离线兜底**：缓存失效时展示「上次更新于 xx」，不要空白或报错。
- **无障碍播报**：`quality` 文字可直接用于 TTS（如「空气优质」），无需额外映射。
## FAQ
**Q1：小程序能直连 route.showapi.com 吗？**
技术上可以，但会暴露 AppKey 且难以控额度，强烈建议经自有后端代理。
**Q2：设备离线时怎么展示？**
依赖本地缓存的上一次结果并标注更新时间；无缓存时显示「空气质量暂不可用」。
**Q3：免费额度够一个设备用吗？**
单设备半小时一次压力很小；但若前端直连或多设备共享同一 AppKey 无缓存，会快速耗尽，务必代理+缓存。
**Q4：能否做「空气差就提醒」？**
可以：`quality` 为「轻度污染」及以上时触发提醒；阈值由你的产品定义，接口只给等级文字。
## 相关能力 / 下一步阅读
- [全国城市空气质量查询：单城市实时查询集成指南（从请求到 UI 展示）](https://www.showapi.com/guides/air-quality-query-integration-104)
- [全国城市空气质量查询：城市空气质量排行榜接入与可视化指南](https://www.showapi.com/guides/air-quality-ranking-integration-104)
- [全国城市空气质量查询：免费额度下如何设计缓存策略节省调用](https://www.showapi.com/guides/air-quality-cache-strategy-104)
- **本系列共 11 篇**：查看[全国城市空气质量查询 · 指南总目录](https://www.showapi.com/guides/air-quality-guides-104)
