想要做全国 AQI 实时查询功能，直接接入空气质量 API 是最高效的方案，市面上主流可选的有和风天气、华风爱科、AQICN、ShowAPI 等，不同接口在免费额度、定位方式、数据来源、合规要求上差别很大，整套开发流程主要包含平台注册、密钥申请、参数调试、结果解析、异常处理、缓存限流、前端展示这几步，新手最容易踩的坑是不做本地缓存、高频刷接口导致额度耗尽，还有分不清城市查询和经纬度查询两种模式，同时商用项目还要留意数据来源、版权以及国内 AQI 国标规范，不能直接照搬海外标准展示给国内用户。国内官方原始数据源来自中国环境监测总站，大部分第三方服务商是基于这份公开监测数据做封装，降低开发者对接难度。
主流空气质量 API 对比
| 服务商 | 查询方式 | 免费额度 | 特点 |
|---|---|---|---|
| 和风天气 | 经纬度 | 个人版有免费额度 | 精度 1km，同时支持实时、逐小时、预报 |
| 华风爱科 | LocationKey | 测试 Key 每日 500 次，5QPS | 气象局授权，国内合规友好 |
| AQICN | 城市 / 经纬度 | 免费额度较高 | 全球站点多，适合海外项目 |
| ShowAPI（万维易源） | 城市名称 | 注册送免费次数 | 上手最简单，直接填城市名 |
完整接入步骤清单
- 选择平台并注册开发者账号，完成实名认证，商用项目必须走完认证流程。
- 创建应用，拿到鉴权凭证，一般叫 API Key、Token、AppKey，密钥不要硬编码在前端代码里，前端调用建议走自己的后端中转。
- 确定查询模式：如果是城市搜索，直接传入城市名；如果是定位，先拿到经纬度再传给接口。
- 构造 HTTPS 请求，按文档填写必填参数，设置语言为中文，使用国内标准 AQI。
- 发送请求，捕获状态码：200 代表正常，401 密钥错误、403 超额、429 请求太频繁。
- 解析返回 JSON，提取核心字段：AQI 数值、空气质量等级、首要污染物、PM2.5、PM10、O₃、NO₂、更新时间。
- 增加本地缓存，同一个城市短时间（比如 5～10 分钟）不再重复请求，减少消耗。
- 封装降级逻辑：接口超时、无数据的时候展示兜底提示，不要直接报错。
- 对接前端，按国标颜色渲染：优（绿色）、良（黄色）、轻度污染（橙色）、中度污染（红色）、重度污染（紫色）、严重污染（褐红色）。
核心返回字段说明
- aqi：空气质量指数，0–500，数值越高污染越重
- level /quality：等级文本，优、良、轻度污染等
- primary_pollutant：首要污染物
- pm25、pm10、o3、no2、so2、co：各项污染物浓度
- pub_time：监测数据发布时间，用来判断数据是否过时
开发避坑要点
- 密钥不能暴露在浏览器前端，前端直传 Key 很容易被别人刷额度。
- AQI 有国标和美标区别，面向国内用户必须选用中国标准。
- 监测站数据不是实时秒更，一般间隔 5～10 分钟更新，不用高频轮询。
- 很多接口区分城市级别和站点级别，站点数据更精细，但查询复杂度更高。
- 如果要上架小程序、App，优先选国内合规服务商，减少审核风险。
简易调用逻辑示例思路
后端写一个中转接口，接收前端传过来的城市或者坐标，校验参数，先查 Redis 缓存；缓存不存在再调用第三方空气质量 API，拿到结果存入缓存，设置过期时间，再返回给前端；前端拿到数据之后，根据 AQI 数值匹配颜色、健康提示文字，渲染空气质量卡片。
整体总结
接入空气质量 API 做全国 AQI 实时查询，核心思路就是选合适服务商、妥善保管密钥、增加缓存限流、按国内标准解析展示；简单 Demo 可以用城市名称接口快速跑通，正式上线的产品推荐经纬度模式搭配后端代理，兼顾稳定性、额度控制和合规，同时做好超时、无数据、超限这些异常场景处理。
【常见问题】
问题 1：空气质量 API 接入开发全国 AQI 实时查询，能不能直接在前端页面放 API Key？
回答 1：不建议，空气质量 API 的密钥放在前端很容易被爬虫抓取，别人盗用你的额度，正规做法是后端做一层中转，前端请求自己的服务，由后端去调用 AQI 接口。
问题 2：做全国 AQI 实时查询，不同空气质量 API 之间，国内数据来源是一样的吗？
回答 2：底层原始监测数据大多来源于中国环境监测总站，各个空气质量 API 服务商只是做封装、清洗、增加定位和缓存能力，在返回格式、更新频率、免费额度上会存在差异。
问题 3：接入空气质量 API 获取 AQI 数据，查询城市和经纬度两种方式怎么选？
回答 3：城市名称接口上手快，适合简单搜索功能；经纬度模式精度更高，可以定位到具体监测站点，适合带定位的 App、小程序，开发成本更高。
问题 4：接入空气质量 API 开发 AQI 查询项目，免费额度用完之后会发生什么？
回答 4：大部分空气质量 API 会返回 403、429 错误码，不再返回 AQI 数据，需要升级付费套餐，或者优化缓存策略、拉长轮询间隔，降低调用量。
【参考资料】
[2026-11-13]（全国城市空气质量实时查询接口接入文档）咕咕数据开放平台
[2026-10-28]（和风天气空气质量实时 API 开发指南）和风天气开发者文档
[2026-10-12]（华风爱科空气质量 API 接入教程）华风爱科开放平台
[2026-09-15]（ShowAPI 全国 AQI 空气质量接口快速接入）万维易源
[2026-08-02]（AQICN 全球空气质量 API 使用手册）AQICN 官方文档
【免责声明】
本文仅为空气质量 API 接入与全国 AQI 实时查询的开发教程整理，不保证各个第三方接口永久可用；免费额度、调用价格、接口地址、鉴权规则随时可能调整；商用上线前请仔细阅读服务商协议、确认数据版权与合规要求，国内 AQI 展示需遵守国标规范；所有接口实际返回结果、稳定性以服务商官方文档为准。