极数本源历史空气质量API实战：从申请到数据可视化

为什么需要历史空气质量API

在环境监测、健康预警、智慧城市等场景中，历史空气质量数据是分析污染趋势、评估政策效果的重要基础。手动采集分散的监测站数据效率极低，而专业API能以标准化接口提供分钟级、日级甚至更细粒度的数据。极数本源（ApiZero）聚合平台提供了覆盖全球主要城市的历史空气质量API，支持按时间范围、污染物类型查询，本文将以该API为例，讲解完整的调用与处理流程。

前置准备：注册与密钥申请

使用极数本源API前需要完成以下步骤：

访问极数本源官网，注册账号。
登录后进入控制台，在"API密钥"页面生成一枚新密钥（AppKey）。
找到"历史空气质量"接口详情页，查看文档中要求的请求格式、频率限制（通常免费额度为1000次/日）。

密钥是每次请求的身份凭证，建议将其存储在环境变量或配置文件中，避免硬编码到代码仓库。

接口文档解析

根据平台提供的文档（示例性提取），历史空气质量API的主要参数如下：

参数	类型	必填	说明
`city`	string	是	城市名称（中文或拼音，如"北京""beijing"）
`start`	string	是	起始日期，格式 `YYYY-MM-DD`
`end`	string	是	结束日期，格式 `YYYY-MM-DD`
`type`	string	否	污染物类型，默认返回AQI综合指标，可选 `pm25`、`pm10`、`o3` 等
`appkey`	string	是	你的API Key

请求方式为 GET，基础URL示例：

复制代码

https://api.apizero.cn/air/history?city=beijing&start=2024-01-01&end=2024-01-31&appkey=YOUR_KEY

响应采用JSON格式，典型结构如下：

json 复制代码

{
  "code": 200,
  "message": "success",
  "data": {
    "city": "北京",
    "records": [
      {
        "date": "2024-01-01",
        "aqi": 85,
        "pm25": 45,
        "pm10": 80,
        "o3": 30,
        "no2": 20
      },
      {
        "date": "2024-01-02",
        "aqi": 110,
        "pm25": 78,
        "pm10": 120,
        "o3": 25,
        "no2": 30
      }
    ]
  }
}

Python代码实现：从请求到解析

下面用Python的requests库完成一次完整调用。首先安装依赖：

bash 复制代码

pip install requests

1. 发起请求

python 复制代码

import requests
import json
from datetime import date

# 配置参数
API_BASE = "https://api.apizero.cn/air/history"
API_KEY = "your_appkey_here"  # 请替换为真实密钥

city = "shanghai"
start_date = "2024-06-01"
end_date = "2024-06-07"

params = {
    "city": city,
    "start": start_date,
    "end": end_date,
    "appkey": API_KEY
}

try:
    response = requests.get(API_BASE, params=params, timeout=10)
    response.raise_for_status()  # 非200状态码抛出异常
except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")
    exit(1)

2. 解析响应数据

python 复制代码

data = response.json()
if data.get("code") != 200:
    print(f"业务错误: {data.get('message')}")
    exit(1)

records = data["data"]["records"]
print(f"共获取 {len(records)} 条记录")

3. 转换为DataFrame便于分析

python 复制代码

import pandas as pd

df = pd.DataFrame(records)
df['date'] = pd.to_datetime(df['date'])
df.set_index('date', inplace=True)
print(df.head())

输出示例：

复制代码

            aqi  pm25  pm10   o3  no2
date                                   
2024-06-01   55   12    30    40   15
2024-06-02   70   35    60    38   22
...

4. 错误处理最佳实践

网络超时 ：设置合理的timeout，重试3次（使用requests.adapters.HTTPAdapter）。
HTTP 4xx/5xx：检查API密钥是否失效、额度是否用完，不同状态码对应不同修复策略。
数据完整性 ：响应中可能出现缺失的污染物字段，建议用dict.get()或设置默认值NaN。

数据可视化：用Matplotlib绘制趋势

获取数据后，最直观的用法是绘制PM2.5日变化曲线。

python 复制代码

import matplotlib.pyplot as plt

plt.figure(figsize=(12, 5))
plt.plot(df.index, df['pm25'], marker='o', linestyle='-', label='PM2.5')
plt.plot(df.index, df['pm10'], marker='s', linestyle='--', label='PM10')
plt.title('上海空气质量趋势 (2024.06.01 - 2024.06.07)')
plt.xlabel('日期')
plt.ylabel('浓度 (μg/m³)')
plt.legend()
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

借助这类图表，可以快速识别污染峰值日期，或结合风玫瑰图分析污染源方向。

进阶应用场景

定时任务采集：部署到服务器，每天自动拉取前一天数据存入数据库（如InfluxDB），用于长期趋势分析。
联动Webhook：当某天PM2.5超过阈值时，发送钉钉/企业微信通知。
移动端展示：封装为轻量Flask API，供小程序或App调用。

总结

通过极数本源历史空气质量API，开发者只需几行代码就能获得结构化的历史污染数据。本文演示了从申请密钥、参数构造、Python请求到可视化的完整链路。实际应用中还需要关注数据缓存、请求频率限制和异常重试。建议先在平台的"在线调试"工具中验证参数效果（该页面提供交互式测试面板），然后再集成到生产系统。

空气质量数据的开放化让更多人能够参与环保监测，而高质量的API降低了门槛。如果你正在开发气象或健康类应用，不妨试试这个接口。