适用场景哪些业务需要历史空气质量数据历史空气质量API提供按城市年月查询逐日AQI和六项污染物PM2.5、PM10、SO2、NO2、CO、O3浓度以及月度汇总信息。以下场景可充分利用该接口环境科学研究分析多年空气质量趋势评估区域排放政策效果。例如对比2013年与2023年北京PM2.5年均值变化。健康与流行病学追溯特定时间段个体的暴露水平关联呼吸系统疾病发病率。数据可视化与报告制作历史空气污染热力图、年度空气质量报告或城市排名变化图表。保险精算与风险评估将空气污染作为风险因子纳入气候相关保险产品模型。旅游与出行规划查询目的地历史空气状况辅助选择出行时机。接口能力边界可查范围时间范围2013年1月至当前月。注意当前月份可能未完结数据仅供参考。空间覆盖全国主要城市。素材仅说明“覆盖全国主要城市”具体支持的城市列表需查阅官方文档接口未直接提供城市枚举。查询粒度按城市年月返回该月每日数据。不支持自定义日期范围可通过连续多次调用实现多个月份查询。数据来源与精度数据源自官方监测站但接口声明数据仅供参考不可用于法律或医疗决策。每日AQI计算依据国家环保标准HJ 633-2012首要污染物通过IAQI分指数确定。污染物浓度单位PM2.5、PM10、SO2、NO2、O3为μg/m³CO为mg/m³以实际返回值为准。性能与鉴权限制QPS5次/秒。适合低频批量处理高频场景需自行控制请求间隔。鉴权方式可选Authorization头Bearer Token或X-API-Key头。匿名调用可能受额度限制建议准备后获取API Key以提升稳定性。素材未说明具体额度以官方文档为准。请求参数与鉴权请求方法POST固定地址https://v1.apizero.cn/api/air-historyHeader参数参数名必需类型说明Content-Type否string设为application/json即可Authorization否string格式Bearer 你的API KeyX-API-Key否string直接传入API Key与Authorization二选一请求体JSON对象两个必填字段字段类型必需说明示例citystring是城市中文名如“北京”“北京”monthstring是年月格式YYYYMM可查2013-01至当前月“202503”{ city: 北京, month: 202503 }curl示例与代码接入最简curl请求使用X-API-Keycurl -sS -X POST \ -H Content-Type: application/json \ -H X-API-Key: YOUR_API_KEY \ -d {city:北京,month:202503} \ https://v1.apizero.cn/api/air-history使用Authorization Bearer Tokencurl -sS -X POST \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_TOKEN \ -d {city:北京,month:202503} \ https://v1.apizero.cn/api/air-historyPython接入示例import requests import json url https://v1.apizero.cn/api/air-history headers { Content-Type: application/json, X-API-Key: YOUR_API_KEY } payload {city: 北京, month: 202503} try: resp requests.post(url, headersheaders, jsonpayload, timeout10) data resp.json() if data.get(code) 0: summary data[data][summary] print(f月度平均AQI: {summary[aqi_avg]}, 等级: {summary[aqi_avg_level]}) print(f优良天数: {summary[days_distribution][excellent]}天优, {summary[days_distribution][good]}天良) else: print(f请求失败: {data.get(msg)}, request_id: {data.get(request_id)}) except requests.exceptions.RequestException as e: print(f网络异常: {e})注意实际部署时应将API Key存储在环境变量中避免硬编码。返回字段解读外层结构{ code: 0, msg: 成功, request_id: abc123, data: { ... } }code: 0表示成功非0为错误。request_id: 唯一标识可用于日志排查。data.daily每日数据数组每个元素包含字段类型说明datestring日期YYYY-MM-DD格式aqiintegerAQI指数levelstring空气质量等级如“良”、“轻度污染”等pollutantsobject六项污染物浓度pm2_5, pm10, so2, no2, co, o3primary_pollutantstring首要污染物名称如“细颗粒物(PM2.5)”rankinteger全国城市排名示例123具体排名范围以文档为准data.metameta: { city: 北京, month: 202503, month_format: 2025年3月, total_days: 31 }total_days: 当月实际天数。data.summary月度汇总summary: { aqi_avg: 58.3, aqi_avg_level: 良, best_day: { date: 2025-03-05, aqi: 28, level: 优 }, worst_day: { date: 2025-03-20, aqi: 168, level: 中度污染 }, days_distribution: { excellent: 8, good: 18, light: 3, medium: 2, heavy: 0, severe: 0 } }aqi_avg: 月平均AQI浮点数。days_distribution: 各级别天数分布excellent优(0-50)good良(51-100)light轻度(101-150)medium中度(151-200)heavy重度(201-300)severe严重(300)。常见错误与排查HTTP状态码可能原因排查方法400请求体字段缺失/格式错误month超出范围检查city是否为中文、month格式是否为YYYYMM、是否在201301至当前月之间401API Key无效或未传递确认Header名称和值测试直接使用Bearer Token或X-API-Key403权限不足或IP被限制检查配额是否耗尽联系服务方429请求过于频繁超过QPS降低请求频率加入退避策略5xx服务端内部错误稍后重试若持续可检查官方状态页错误响应体中msg字段提供错误描述。记录request_id有助于向服务方反馈。工程化注意事项批处理策略按城市和月份逐条请求建议使用异步队列控制并发每个请求间隔至少200ms。本地缓存历史数据不变可将已查询结果缓存到SQLite或Redis减少重复调用与API消耗。错误重试对网络异常和5xx实现指数退避如首次1s二次2s四次后终止4xx错误不重试。密钥管理使用环境变量或密钥管理服务如Vault禁止硬编码。数据校验响应的total_days应与实际月份天数一致daily数组长度应与total_days匹配缺失值可能是当日无数据。多城市并行查询例如一次性查询多个城市同月数据需控制总QPS不超过5建议串行或限流。参考文档API文档页https://apizero.cn/aidocs/air-history原始Markdown文档https://apizero.cn/aidocs/air-history/raw.md
