<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 历史空气质量

> 按城市 + 年月查询历史空气质量档案：逐日 AQI 与六项污染物（PM2.5/PM10/SO₂/NO₂/CO/O₃）浓度、空气质量等级、首要污染物、全国排名，并给出月度汇总（均值、最佳/最差日、优良天数分布）。

可查范围 2013 年 1 月至当前月，覆盖全国主要城市。首要污染物按国标 HJ 633-2012 IAQI 分指数计算。数据仅供参考。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `air-history` |
| 接口名称 | 历史空气质量 |
| 接口地址 | `https://v1.apizero.cn/api/air-history` |
| 请求方法 | `POST` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 50 次（已认证用户） |
| 匿名每日额度 | 5 次（无 API Key） |
| VIP 免费 | 是 |
| 调用总次数 | undefined |

## 2. 认证

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

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `city` | `string` | 是 | 城市中文名 | `北京` |
| `month` | `string` | 是 | 年月，格式 YYYYMM，可查 2013-01 至当前月 | `202503` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | Bearer <你的 API Key>（登录调用可提升额度/享会员免费；匿名可不传） | — |
| `Content-Type` | `string` | 否 | 请求体格式 | — |

## 5. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

```bash
curl -X POST "https://v1.apizero.cn/api/air-history" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "北京",
  "month": "202503"
}'
```

### Python

```python
import requests

resp = requests.request(
    "POST",
    "https://v1.apizero.cn/api/air-history",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
    "city": "北京",
    "month": "202503",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const res = await fetch("https://v1.apizero.cn/api/air-history", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "city": "北京",
    "month": "202503"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"city":"北京","month":"202503"}`)
	req, _ := http.NewRequest("POST", "https://v1.apizero.cn/api/air-history", bytes.NewBuffer(body))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}
```

### PHP

```php
<?php
$payload = json_encode([
    "city" => "北京",
    "month" => "202503",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://v1.apizero.cn/api/air-history");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        "X-Api-Key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `meta.city` | `string` | 城市名称 | — |
| `meta.month` | `string` | 查询年月（YYYYMM） | — |
| `meta.month_format` | `string` | 年月中文格式 | — |
| `meta.total_days` | `number` | 当月有效监测天数 | — |
| `units` | `object` | 各指标单位说明 | — |
| `summary.aqi_avg` | `number` | 月度平均 AQI | — |
| `summary.aqi_avg_level` | `string` | 平均 AQI 对应等级 | — |
| `summary.pm2_5_avg` | `number` | PM2.5 月均值（其余污染物同理） | — |
| `summary.best_day` | `object` | 空气最佳日 {date, aqi, level} | — |
| `summary.worst_day` | `object` | 空气最差日 {date, aqi, level} | — |
| `summary.days_distribution` | `object` | 优/良/轻度/中度/重度/严重 天数分布 | — |
| `summary.overall_text` | `string` | 月度概览文字 | — |
| `daily` | `array` | 逐日明细列表 | — |
| `daily[].date` | `string` | 日期 | — |
| `daily[].aqi` | `number` | 当日 AQI | — |
| `daily[].level` | `string` | 空气质量等级 | — |
| `daily[].primary_pollutant` | `string` | 首要污染物（AQI≤50 为「无」） | — |
| `daily[].rank` | `number` | 当日全国城市排名（无则 null） | — |
| `daily[].pollutants` | `object` | 六项污染物浓度 {pm2_5,pm10,so2,no2,co,o3} | — |

## 7. 响应示例

```json
{
  "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"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `VALIDATION_ERROR` | 参数缺失/格式错误，或该城市·月份无数据 |
| `4022` | `INSUFFICIENT_BALANCE` | 余额不足（登录用户超免费额度后） |
| `5020` | `UPSTREAM_ERROR` | 空气质量数据服务暂不可用 |
| `5021` | `UPSTREAM_INVALID` | 空气质量数据解析失败 |

## 9. 变更日志

- **v1.0** (2026-07-02)
  - 首次上线：逐日 AQI 与六项污染物、首要污染物（国标 IAQI）、全国排名、月度汇总。

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/air-history`

Source: `https://apizero.cn/aidocs/air-history/raw.md`
Last updated: 2026-07-02T11:30:12+08:00