历史空气质量 API 常见错误与排错指南

适用场景历史空气质量 API 能够按城市和年月查询逐日 AQI 及六项污染物PM2.5、PM10、SO₂、NO₂、CO、O₃浓度、空气质量等级、首要污染物、全国排名同时返回月度汇总统计均值、最佳/最差日、优良天数分布。该接口适用于以下典型场景环境数据分析研究特定区域长时间序列的空气质量变化趋势。健康出行决策回顾历史污染时段为个人出行或防护提供参考。行业报告制作整合多个城市的月度数据生成环保或气象主题的可视化图表。业务系统集成将空气质量数据嵌入到健康管理、旅游规划或房地产评估应用中。接口能力边界在开始调用前必须明确接口的限制条件项目说明查询范围2013 年 1 月至当前月按自然月计算覆盖城市中国主要城市以接口返回为准数据粒度逐日 月度汇总返回字段AQI、六项污染物浓度、等级、首要污染物、全国排名、优良天数分布等数据来源仅供学习参考不保证实时性和绝对准确性QPS 限制5 次/秒超过可能触发限流开发者务必注意数据来源并非官方发布的最终结果项目中需声明数据仅供参考。另外month参数必须严格使用YYYYMM格式例如202503代表 2025 年 3 月月份不可大于当前月或早于 2013102013年1月可用。请求参数与鉴权接口采用POST方法请求地址为https://v1.apizero.cn/api/air-historyHeader 参数参数名必填类型说明Authorization否stringBearer 匿名可不传但可能会影响调用额度Content-Type否string建议设为application/json注意实际鉴权方式请以官方文档为准。下方 curl 示例使用X-API-Key头部来自官方示例你也可以选择使用Authorization: Bearer方式。推荐在正式代码中统一使用Authorization头部。请求体JSON{ city: 北京, month: 202503 }字段必填类型说明city是string城市中文名如“北京”、“上海”month是string年月格式 YYYYMM例如 202503curl 示例以下是最简洁的调用方式假设 API Key 已设置到环境变量APIZERO_API_KEYcurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {city: 北京, month: 202503} \ https://v1.apizero.cn/api/air-history若使用Authorization头部可将-H X-API-Key: ...替换为-H Authorization: Bearer 你的API Key。Python 版本import requests import json API_URL https://v1.apizero.cn/api/air-history API_KEY YOUR_API_KEY # 建议从环境变量读取 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { city: 北京, month: 202503 } try: resp requests.post(API_URL, headersheaders, jsonpayload, timeout10) resp.raise_for_status() data resp.json() print(json.dumps(data, indent2, ensure_asciiFalse)) except requests.exceptions.RequestException as e: print(f请求失败: {e})返回值解读成功响应示例HTTP 200{ code: 0, msg: 成功, request_id: abc123, data: { daily: [ { date: 2024-12-01, aqi: 53, level: 良, primary_pollutant: 细颗粒物(PM2.5), rank: 123, pollutants: { co: 0.5, no2: 35, o3: 52, pm10: 55, pm2_5: 26, so2: 4 } } ], meta: { city: 北京, month: 202412, month_format: 2024年12月, total_days: 31 }, 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 } } } }字段说明code: 0 表示业务成功非 0 为错误码。msg: 业务提示信息。request_id: 本次请求的唯一标识用于排查问题。data.daily: 按日期排序的数组每天一条记录。level包含“优”、“良”、“轻度污染”、“中度污染”、“重度污染”、“严重污染”。pollutants中各字段的单位CO 为 mg/m³其余为 μg/m³。data.summary: 月汇总。aqi_avg为当月平均 AQI。days_distribution统计各级别天数。data.meta: 查询元信息包括城市、月份及总天数。常见错误与排查在实际集成中开发者最容易遇到以下几类错误。下面按错误表型分类并给出定位建议。1. 认证鉴权失败现象返回 HTTP 401 Unauthorized 或 403 Forbiddencode 非 0msg 类似“未授权”或“无效的API Key”。原因未携带 API Key。使用了错误的 Key 或已过期。Header 名称使用错误例如将X-API-Key写成了Api-Key。排查步骤检查请求中是否包含Authorization: Bearer Key或X-API-Key头以官方文档为准。确认 API Key 字符串完整且未包含额外空格。登录后台查看 API Key 是否有效额度是否耗尽。2. 参数格式错误现象返回 code 1002示例实际以文档为准msg 提示“参数错误”。常见子场景city为空或包含非中文、非标准名称如“北京市”而非“北京”。month格式不对例如2025-03、2025年3月、20250301。month数值超出范围比如201299早于 2013年1月或202613超过当前月。排查步骤打印实际发送的请求体 JSON 字符串确认无多余字符。验证city是否为接口支持的城市名可先请求一个已知城市测试。检查month是否满足YYYYMM正则^(20[1-9]\d)(0[1-9]|1[0-2])$并且月份 当前月。3. 请求频率超限现象返回 HTTP 429 Too Many Requests响应 body 中提示限流。原因单 IP 或单 API Key 的 QPS 超过 5 次/秒。排查步骤降低请求并发数增加间隔。检查是否有循环调用的 bug例如在 for 循环中未添加time.sleep。考虑加入本地缓存避免重复请求相同数据。4. 数据不存在或城市不支持现象正常返回 HTTP 200但data.daily为空数组或data为 null或code非 0。原因该城市在该月份没有历史记录例如某些县城不支持。月份超越了接口可查范围。城市名称错误如“首尔”而非国内城市。排查步骤换用已知大城市如“北京”、“上海”测试同一月份确认接口功能正常。检查month是否在合理区间。查看返回的msg字段例如“城市不存在”。5. 网络超时或连接错误现象请求抛出超时异常例如requests.exceptions.Timeout或返回 HTTP 502/503。原因本地网络不稳定。接口服务临时不可用。DNS 解析失败。排查步骤设置合理超时建议 10 秒。使用curl测试基础连通性。配合重试逻辑指数退避。工程化注意事项API Key 管理不要硬编码在代码仓库中。使用环境变量或密钥管理服务如.env文件。错误重试策略对 HTTP 429 及 5xx 错误采用指数退避重试例如首次等待 1s第二次 2s第三次 4s最大三次。数据缓存对于历史数据过去月份结果不会变化建议加一层本地缓存如 Redis 或内存字典减少重复请求。月份校验在上游接口调用前校验month格式避免无效请求浪费资源。跨月查询如果要查连续多个月建议循环请求并添加间隔≥200ms防止被限流。记录日志将request_id、参数和返回错误码记录到日志中便于后期排查。参考文档官方文档页原始文档Markdown注意上述文档可能包含更详细的错误码说明和最新调用方式请在开发前仔细阅读。