想要做全国 AQI 实时查询功能，接入空气质量 API 并不是直接发请求就能稳定拿到数据，开发者首先要选合适的数据源接口，理解鉴权、额度、QPS 限流、数据更新频率这些基础规则，同时做好缓存、异常捕获、降级处理，不然很容易出现调用超限、返回空数据、跨域报错、城市识别失败等问题。市面上有商业气象平台、第三方数据聚合接口、生态环境公开数据接口几类，不同接口的鉴权方式、免费额度、数据颗粒度差别很大，有的支持按城市名称查询，有的需要传入行政区划 adcode 或者经纬度，返回字段包含 AQI 数值、等级、PM2.5、PM10、SO₂、NO₂、O₃、CO、首要污染物、数据更新时间。开发的时候优先做好 Key 保管，不要把密钥写在前端代码里暴露，再加上本地缓存减少高频请求，配套错误码判断，最后按照国标 HJ633 规范做 AQI 等级渲染，才能把实时空气质量查询做成稳定可用的线上功能。
一、主流全国 AQI 接口对比表
| 接口来源 | 鉴权方式 | 免费额度 | 入参方式 | 更新频率 | 适合场景 |
|---|---|---|---|---|---|
| 万维易源 ShowAPI | AppKey | 注册后有免费调用额度 | 城市名称 area | 小时级 | 快速 Demo、小程序、简单工具 |
| 华风爱科气象 API | API Key，Header 传参 | 测试 Key 每日 500 次，5QPS | LocationKey / 经纬度 | 1 小时内 | 正式商业项目、APP |
| AQICN 全球空气质量 API | Token | 免费额度，商用需授权 | 城市 ID / 经纬度 | 小时级 | 全球多城市空气质量查询 |
| 腾讯位置服务天气接口 | 开发 Key | 免费额度，有频率上限 | adcode 行政区划编码 | 小时级 | 和地图定位联动的项目 |
二、接口返回核心字段清单
- aqi：空气质量指数，0~500
- level：空气质量等级（优、良、轻度污染、中度污染、重度污染、严重污染）
- pm2_5：细颗粒物浓度，单位 μg/m³
- pm10：可吸入颗粒物浓度
- o3：臭氧浓度
- no2：二氧化氮
- so2：二氧化硫
- co：一氧化碳
- primary_pollutant：首要污染物
- update_time：数据最后更新时间戳
三、完整接入开发步骤
- 平台注册与密钥申请：选定接口服务商，注册开发者账号，完成实名认证，在控制台创建应用，拿到 API Key、AppKey 或者访问 Token，禁止前端硬编码密钥，后端转发请求。
- 接口调试：先在平台在线调试页面测试，确认入参格式，城市名、adcode、经纬度三者按接口要求选择，观察返回 JSON 结构，确认正常返回 200 成功状态码。
- 封装后端请求接口：前端请求自己的服务端，由服务端携带密钥去调用空气质量 API，解决跨域和密钥泄露风险。
- 增加缓存策略：设置缓存有效期，一般 30~60 分钟，同一个城市短时间重复请求直接返回缓存，减少额度消耗。
- 异常与错误码处理：对 401 密钥错误、429 请求超限、404 城市不存在、504 网关超时分别做兜底提示，缓存失效时返回上一次有效数据降级。
- 前端渲染与国标分级：按照 HJ633 标准映射颜色和文字提示，增加更新时间展示，标注数据来源。
- 上线压测和额度监控：控制台开启调用告警，监控 QPS，高峰期避免触发限流，业务量大提前升级付费套餐。
四、高频踩坑点
- 密钥直接写前端：抓包就能拿到 Key，被盗刷消耗额度，产生额外费用。
- 无缓存高频轮询：每几秒请求一次，很快触发 429 限流，返回空数据。
- 城市名称不标准：简写、别名、乡镇名称识别失败，接口返回上级城市或者无数据。
- 忽略数据延迟：实时 AQI 不是秒级更新，大多是小时级同步，不要用高频率刷新。
- 不做降级兜底：接口挂掉之后页面直接报错，没有缓存旧数据展示。
- 忽略合规要求：商用项目没有拿到对应数据服务商授权，直接对外展示、售卖数据。
五、AQI 国标分级参考
| AQI 数值区间 | 等级 | 推荐颜色 |
|---|---|---|
| 0~50 | 优 | 绿色 |
| 51~100 | 良 | 黄色 |
| 101~150 | 轻度污染 | 橙色 |
| 151~200 | 中度污染 | 红色 |
| 201~300 | 重度污染 | 紫色 |
| >300 | 严重污染 | 褐红色 |
【相关 FAQ】
问题 1：空气质量 API 接入开发全国 AQI 实时查询接口，能不能直接在前端 JS 调用接口？
回答 1：不建议，空气质量 API 接入开发全国 AQI 实时查询接口，如果直接前端调用，密钥会暴露，容易被盗刷，规范做法是搭建后端中转服务，密钥放在后端。
问题 2：空气质量 API 接入开发全国 AQI 实时查询接口，为什么有时候同一个城市拿到的 AQI 数据不变？
回答 2：空气质量 API 接入开发全国 AQI 实时查询接口，绝大多数数据源是小时级更新，不是实时秒刷新，加上我们做了缓存，短时间多次查询会返回相同数据，属于正常现象。
问题 3：空气质量 API 接入开发全国 AQI 实时查询接口，调用返回 429 报错是什么意思？
回答 3：空气质量 API 接入开发全国 AQI 实时查询接口，429 代表请求频率超限、调用额度用完，需要降低轮询频率，增加缓存，或者升级付费套餐。
【参考资料】
[2026-10-15]（全国城市空气质量查询快速接入指南）万维易源 ShowAPI
[2026-09-22]（华风爱科空气质量 API 开发文档）华风爱科开放平台
[2026-08-10]（AQICN 空气质量 API 使用规范）AQICN 官方文档
[2026-07-03]（腾讯位置服务天气空气质量接口说明）腾讯地图开放平台
[2026-06-11]（HJ 633 环境空气质量指数技术规定）生态环境部
【免责声明】
本内容为空气质量 API、全国 AQI 实时查询接口接入开发科普整理，不同服务商接口的免费额度、限流规则、商用授权条款各不相同；商用上线前务必阅读对应平台的服务协议，取得合法数据授权，做好额度监控和风控，本内容不代表接口服务商官方开发文档，不承担盗刷、数据错误、合规风险相关责任。
本文来自作者[尘波时序]投稿，不代表乌兰科技网立场，如若转载，请注明出处：https://www.wlcbnews.com/rgzn/202611/1853.html
评论列表（4条）
我是乌兰科技网的签约作者“尘波时序”！
希望本篇文章《空气质量 API 接入实操教程，全国 AQI 实时查询接口完整开发落地指南》能对你有所帮助！
本站[乌兰科技网]内容主要涵盖：互联网行业的追踪与探索
本文概览：想要做全国 AQI 实时查询功能，接入空气质量 API 并不是直接发请求就能稳定拿到数据，开发者首先要选合适的数据源接口，理解鉴权、额度、QPS 限流、数据更新频率这些基础规则，同时做好缓存、异常捕获、降级处理，不然很容易出现调用超限、返回空数据、跨域报错、城市识别失败等问题。市面上有商业气象平台、第三方数据聚合接口、生态环境公开数据接口几类，不同接口的鉴权方式、免费额度、数据颗粒度差别很大，有的支持按城市名称查询，有的需要传入行政区划 adcode 或者经纬度，返回字段包含 AQI 数值、等级、PM2.5、PM10、SO₂、NO₂、O₃、CO、首要污染物、数据更新时间。开发的时候优先做好 Key 保管，不要把密钥写在前端代码里暴露，再加上本地缓存减少高频请求，配套错误码判断，最后按照国标 HJ633 规范做 AQI 等级渲染，才能把实时空气质量查询做成稳定可用的线上功能。