适用场景历史空气质量 API 为需要回溯特定城市某月空气质量变化的应用场景提供标准化数据。典型用例包括气候研究结合 PM2.5、PM10、O₃ 等时间序列分析大气污染趋势。健康管理 App展示用户所在城市的历史空气等级辅助出行决策。数据看板为企业内部环境报表提供月度汇总均值、最佳/最差日、优良天数分布。教学演示学习 RESTful API 调用与 JSON 解析时的简单示例。接口返回 2013 年 1 月至当前月含当月的数据覆盖全国主要城市。接口能力边界在编码之前需要明确以下几点请求方法POST非 GET主体为 JSON。请求地址https://v1.apizero.cn/api/air-historyQPS 限制5 次/秒。超出后会触发限流建议附带指数退避重试。鉴权方式支持匿名调用有限额也可在 Header 中携带Authorization: Bearer 你的 API Key以提升调用额度。为安全起见生产环境应始终使用 Key。数据来源声明空气质量数据基于国标 HJ 633-2012 计算 IAQI 指数仅供研究参考不应作为法律依据。请求参数与鉴权必填参数JSON Body字段类型说明示例citystring城市中文名北京monthstring年月格式 YYYYMM范围 201301 至当前月202503可选 HeadersContent-Type: application/json必需除非使用默认值Authorization: Bearer YOUR_API_KEY推荐匿名也可调但额度较低注意X-API-Key是旧版 Header 名称现文档推荐使用标准Authorization头。两种均可工作但建议统一使用 Bearer 方案。curl 最小可运行示例以下命令是上手最快的方式。将$APIZERO_API_KEY替换为你的实际密钥若匿名可去掉-H Authorization: Bearer ...即可查看北京 2025 年 3 月的空气质量curl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {city: 北京, month: 202503} \ https://v1.apizero.cn/api/air-history参数说明-s静默模式不显示进度条-S出错时仍显示错误信息。-X POST指定 HTTP 方法。-H添加请求头。-d请求体 JSON 字符串需用单引号包裹防止 shell 转义。若使用 Windows Command Prompt注意 JSON 内部的双引号需要转义curl -sS -X POST -H Authorization: Bearer YOUR_KEY -H Content-Type: application/json -d {\city\: \北京\, \month\: \202503\} https://v1.apizero.cn/api/air-history执行成功后你将得到一个完整的 JSON 响应。下面我们来拆解它的结构。返回值逐字段解读以北京 2024 年 12 月为例返回示例已精简{ code: 0, msg: 成功, request_id: abc123, data: { meta: { city: 北京, month: 202412, month_format: 2024年12月, total_days: 31 }, daily: [ { date: 2024-12-01, aqi: 53, level: 良, primary_pollutant: 细颗粒物(PM2.5), rank: 123, pollutants: { pm2_5: 26, pm10: 55, so2: 4, no2: 35, co: 0.5, o3: 52 } } ], summary: { aqi_avg: 58.3, aqi_avg_level: 良, best_day: { date: 2024-12-05, aqi: 28, level: 优 }, worst_day: { date: 2024-12-20, aqi: 168, level: 中度污染 }, days_distribution: { excellent: 8, good: 18, light: 3, medium: 2, heavy: 0, severe: 0 } } } }顶层字段字段类型说明codeint业务状态码0 表示成功msgstring状态描述request_idstring请求唯一标识可用于排查问题dataobject核心数据包含 meta、daily 和 summary 三个子对象data.meta – 月份元信息city请求的城市名原样返回month请求的月份原样month_format格式化后的中文月份如 “2024年12月”total_days该月总天数便于前端遍历data.daily – 逐日明细数组每个元素对应一天字段如下字段类型说明datestring日期YYYY-MM-DDaqiint当日 AQI 指数0–500levelstring空气质量等级优、良、轻度污染等primary_pollutantstring首要污染物如 “细颗粒物(PM2.5)”无首要时可为空字符串rankint当日该城市在全国的 AQI 排名数值越小越好注意排名变化较大pollutantsobject六项污染物浓度值污染物单位说明pm2_5、pm10、so2、no2、o3单位 μg/m³微克/立方米co单位 mg/m³毫克/立方米注意与 O₃ 等量级不同data.summary – 月度汇总提供该月的统计概览aqi_avg月均 AQIfloataqi_avg_level月均对应的等级根据均值区间划分best_day/worst_day最佳日AQI 最小和最差日AQI 最大各含 date、aqi、leveldays_distribution各等级天数分布字段含义excellent优AQI 0–50good良51–100light轻度污染101–150medium中度污染151–200heavy重度污染201–300severe严重污染300注意summary与daily数据是协调一致的你可以从daily自行验证best_day的计算逻辑。常见错误与排查1. 请求返回 400 Bad Request可能原因JSON 格式错误如缺少逗号、多出尾逗号、key 未加引号。month参数格式错误不是 YYYYMM 或超出范围。city为空或是不支持的城市名称请使用官方中文名如“北京”而非“北京市”。排查方法使用curl -v查看详细请求体和响应头。2. 返回 401 Unauthorized未传入Authorization头或 Key 无效。若匿名调用部分 Key-free 接口允许但生产环境建议始终传入有效 Key。检查 Key 是否含有空格或换行符。3. 返回 429 Too Many Requests超过了 QPS 5 次/秒的限制。实现客户端时应在每次请求间添加至少 200ms 间隔。建议使用请求队列并在 HTTP 返回 429 时等待Retry-After头若不提供则退避 1 秒。4. 返回{code: 1, msg: ...}业务层错误例如month对应的数据不存在早于 201301 或晚于当前月或城市名称不在支持列表内。工程化注意事项1. 环境变量管理 Key不要将 API Key 硬编码在源码中。在 Python 或 Node.js 中优先从环境变量读取export APIZERO_KEYyour-key-here然后在代码中引用。2. 请求重试与超时设置网络问题不可避免。建议配置超时如 10 秒和自动重试最多 3 次仅对 5xx 或网络错误重试。3. 缓存策略历史空气质量数据按天更新但同一月份在当月内也可能每天变化补充后几天数据。建议对已过去的月份做 1 天缓存当月数据缓存时间缩短至 1 小时。使用 ETag 或 If-Modified-Since 头该 API 可能未支持需查看文档。4. 分页与数据量当前接口按整月返回最多 31 天数据量约 1–3 KB无需分页。但如果将来支持跨月查询需注意接口变更。5. 时间戳与时区所有日期字段均为北京时间东八区不包含时区偏移。如果你的前端显示其他时区需自行转换。参考文档历史空气质量 API 文档原始接口定义raw.md以上文档中包含完整的错误码列表、QPS 详情及城市支持列表建议在实际集成前仔细阅读。