历史空气质量

air-historyPOST

按城市 + 年月查询历史空气质量档案:逐日 AQI 与六项污染物(PM2.5/PM10/SO₂/NO₂/CO/O₃)浓度、空气质量等级、首要污染物、全国排名,并给出月度汇总(均值、最佳/最差日、优良天数分布)。 可查范围 2013 年 1 月至当前月,覆盖全国主要城市。首要污染物按国标 HJ 633-2012 IAQI 分指数计算。数据仅供参考。

POSThttps://v1.apizero.cn/api/air-history

平台约定

  • 网关 · https://v1.apizero.cn
  • 鉴权 · Authorization: Bearer <API Key>
  • 回包 · JSON {code, msg, data}。成功看 code === 0,不要只看 HTTP 200。
/aidocs/air-history/raw.md
打开 Markdown

鉴权

匿名可调用(每日 5 次);登录后每日 50 次免费,超出按 ¥0.01/次 从余额扣费,开通会员可免费不限量。

获取 API Key:/account/keys

请求头

Header类型必填说明
Authorizationstring推荐:Bearer <API Key>。兼容请求头 X-API-Key,以及 Query api_key / apikey / key(key 仅当值为 sk_live_/sk_test_/sk_stag_ 形态时生效)。匿名可不传,受每日免费额度限制。
Content-Typestring请求体格式

请求参数

POST · APPLICATION/JSON

参数类型必填说明示例
citystring城市中文名北京
monthstring年月,格式 YYYYMM,可查 2013-01 至当前月202503
{
  "city": "北京",
  "month": "202503"
}

响应字段

顶层固定为 code / msg / data。下表一般是 data 内字段。 code · msg · data · tips · request_id

字段类型说明
meta.citystring城市名称
meta.monthstring查询年月(YYYYMM)
meta.month_formatstring年月中文格式
meta.total_daysnumber当月有效监测天数
unitsobject各指标单位说明
summary.aqi_avgnumber月度平均 AQI
summary.aqi_avg_levelstring平均 AQI 对应等级
summary.pm2_5_avgnumberPM2.5 月均值(其余污染物同理)
summary.best_dayobject空气最佳日 {date, aqi, level}
summary.worst_dayobject空气最差日 {date, aqi, level}
summary.days_distributionobject优/良/轻度/中度/重度/严重 天数分布
summary.overall_textstring月度概览文字
dailyarray逐日明细列表
daily[].datestring日期
daily[].aqinumber当日 AQI
daily[].levelstring空气质量等级
daily[].primary_pollutantstring首要污染物(AQI≤50 为「无」)
daily[].ranknumber当日全国城市排名(无则 null)
daily[].pollutantsobject六项污染物浓度 {pm2_5,pm10,so2,no2,co,o3}
tipsstring品牌提示(所有接口统一返回):极数本源 · https://apizero.cn

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "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
      }
    },
    "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
        }
      }
    ]
  },
  "request_id": "abc123",
  "tips": "极数本源 · https://apizero.cn"
}

请求示例

将 YOUR_API_KEY 替换为真实 Key 后运行。

# 1. 密钥:登录 https://apizero.cn/account/keys 申请,写入环境变量 APIZERO_KEY
#    请求头 Authorization: Bearer <key>
import json
import os
import urllib.request

key = os.environ["APIZERO_KEY"]

# 2. 请求地址
url = "https://v1.apizero.cn/api/air-history"

# 3. 发请求
payload = {
    "city": "北京",
    "month": "202503",
}
req = urllib.request.Request(
    url,
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + key,
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=15) as resp:
    body = json.loads(resp.read().decode("utf-8"))

# 4. 打印整包。
#   第 5 步的字段按本接口 data 里实际键改。
print(json.dumps(body, ensure_ascii=False, indent=2))

# 5. code == 0 后再取字段
if body.get("code") == 0:
    data = body.get("data") or {}
    print(data)

在线调试

填写参数后运行,将真实调用接口;计入免费额度。

RequestPOST
POST https://v1.apizero.cn/api/air-history

认证方式

参数(2)

>_

待运行

填写参数后点击「运行调试」查看响应

错误码

先看业务 code。HTTP 也可能不是 200。

业务码HTTP说明
0200成功
4000400参数错误
4011401API Key 无效
4013403API Key 已暂停
4014403当前 IP 不在 Key 白名单
4015401此接口需要 API Key
4022402余额不足
4029429调用过快(QPS)
4030429今日免费额度已用完
4040503接口已下线
4041404接口不存在
5000500服务器内部错误
5020502上游暂时不可用
5021502上游返回格式异常
5030502暂无可用节点

额度与计费

计费模式完全免费
QPS 限制3 req/s
登录免费额度50 次(已认证)
匿名每日额度5 次(无 API Key)
黄金会员每日 50000 次 · QPS 10
企业会员每日 1000000 次 · QPS 120

购买套餐、看评价请走商城详情。 购买 / 调试

变更日志

  • v1.02026-07-02

    首次上线:逐日 AQI 与六项污染物、首要污染物(国标 IAQI)、全国排名、月度汇总。

免责声明

空气质量数据来源于公开监测历史数据整理,仅供参考,具体以官方发布为准。

历史空气质量 接入文档|极数本源