历史空气质量API接口能力边界与适用场景深度解析

发布时间：2026/7/26 7:20:43

适用场景：哪些业务需要历史空气质量数据？

历史空气质量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³（以实际返回值为准）。

性能与鉴权限制

QPS：5次/秒。适合低频批量处理，高频场景需自行控制请求间隔。
鉴权方式：可选Authorization头（Bearer Token）或X-API-Key头。匿名调用可能受额度限制，建议准备后获取API Key以提升稳定性。素材未说明具体额度，以官方文档为准。

请求参数与鉴权

请求方法

POST
固定地址：https://v1.apizero.cn/api/air-history

Header参数

参数名	必需	类型	说明
Content-Type	否	string	设为`application/json`即可
Authorization	否	string	格式：`Bearer <你的API Key>`
X-API-Key	否	string	直接传入API Key（与Authorization二选一）

请求体

JSON对象，两个必填字段：

字段	类型	必需	说明	示例
city	string	是	城市中文名，如“北京”	“北京”
month	string	是	年月，格式YYYYMM，可查2013-01至当前月	“202503”

{ "city": "北京", "month": "202503" }

curl示例与代码接入

最简curl请求（使用X-API-Key）

curl -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 Token

curl -sS -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{"city":"北京","month":"202503"}' \ "https://v1.apizero.cn/api/air-history"

Python接入示例

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, headers=headers, json=payload, timeout=10) 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（每日数据数组）

每个元素包含：

字段	类型	说明
date	string	日期，YYYY-MM-DD格式
aqi	integer	AQI指数
level	string	空气质量等级，如“良”、“轻度污染”等
pollutants	object	六项污染物浓度：pm2_5, pm10, so2, no2, co, o3
primary_pollutant	string	首要污染物名称，如“细颗粒物(PM2.5)”
rank	integer	全国城市排名（示例123，具体排名范围以文档为准）

data.meta

"meta": { "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至当前月之间
401	API Key无效或未传递	确认Header名称和值，测试直接使用Bearer Token或X-API-Key
403	权限不足或IP被限制	检查配额是否耗尽，联系服务方
429	请求过于频繁（超过QPS）	降低请求频率，加入退避策略
5xx	服务端内部错误	稍后重试，若持续可检查官方状态页