IQAir 空气质量数据源

通过 curl tool 调用 IQAir AirVisual API 获取全球城市实时空气质量数据。

鉴权

请求 api.airvisual.com 时，在 URL query 参数中携带 API Key：

https://api.airvisual.com/v2/...?key={{secrets.IQAIR_API_KEY}}

占位符由后端在 curl 运行期替换为真实 key，你无需也无法看到明文。

获取 API Key 步骤：

1. 访问 https://dashboard.iqair.com/ 登录或注册 IQAir 账号
2. 登录后，在左侧菜单栏点击 "Air quality API" 标签
3. 点击右上角 "+ Create an API key" 按钮创建 API Key
4. 获取 API Key 后在「设置 → 凭证配置」页面添加 IQAIR_API_KEY

通用约定

• Base URL：https://api.airvisual.com/v2（必须使用 HTTPS）
• 请求方法：GET
• 响应格式：JSON
• 分页：不分页（返回完整列表）
• 速率限制：免费版约 10 次/分钟、10000 次/月
• 层级关系：Country → State → City → Station
  • 获取城市数据前，需要先确定国家（Country）和州/省（State）
  • 部分国家州/省层级可能为空，可尝试使用 "n/a" 或省略

⚠️ 速率限制策略（必须遵守）

IQAir 免费版限额严格，必须遵守以下规则：

1. 串行请求：同一时间只发 1 个 curl 请求，等返回后再发下一个。严禁并行发送多个请求
2. 请求间隔：每两个请求之间至少间隔 3 秒
3. 批量查询：需要查多个城市时，一次最多查 3 个城市，如需更多则分批
4. 429 重试：收到 429 错误后等待 60 秒再重试
5. 数据复用：已获取的城市列表结果应缓存使用，不要重复请求

常用接口

1. 获取支持的国家列表

GET https://api.airvisual.com/v2/countries?key={{secrets.IQAIR_API_KEY}}

参数：

关键返回字段：

2. 获取指定国家的州/省列表

GET https://api.airvisual.com/v2/states?country={country}&key={{secrets.IQAIR_API_KEY}}

参数：

关键返回字段：

3. 获取指定州/省的城市列表

GET https://api.airvisual.com/v2/cities?state={state}&country={country}&key={{secrets.IQAIR_API_KEY}}

参数：

关键返回字段：

4. 获取指定城市的空气质量数据

GET https://api.airvisual.com/v2/city?city={city}&state={state}&country={country}&key={{secrets.IQAIR_API_KEY}}

参数：

关键返回字段：

5. 获取最近的监测站空气质量数据（IP 定位）

GET https://api.airvisual.com/v2/nearest_city?key={{secrets.IQAIR_API_KEY}}

返回字段与接口 4 相同，基于请求 IP 定位最近监测站。

6. 获取指定 GPS 坐标最近的监测站数据

GET https://api.airvisual.com/v2/nearest_city?lat={latitude}&lon={longitude}&key={{secrets.IQAIR_API_KEY}}

参数：

返回字段与接口 4 相同。

调用示例

场景：查询北京当前的空气质量

注意：请严格串行调用，不要并行发送多个请求。

1. 调用接口：

curl(url = "https://api.airvisual.com/v2/city?city=Beijing&state=Beijing&country=China&key={{secrets.IQAIR_API_KEY}}", X = "GET")

2. 从返回中提取关键信息：

   • data.current.pollution.aqius → AQI（美国标准）
   • data.current.pollution.aqicn → AQI（中国标准）
   • data.current.weather.tp → 当前温度

3. 向用户汇报，附上 AQI 等级和健康建议。

场景：对比多个城市的空气质量

必须串行请求，每次只查 1 个城市：

# 第 1 个城市curl(url = "https://api.airvisual.com/v2/city?city=Beijing&state=Beijing&country=China&key={{secrets.IQAIR_API_KEY}}", X = "GET")
# 等待上一个返回后，再发第 2 个curl(url = "https://api.airvisual.com/v2/city?city=Shanghai&state=Shanghai&country=China&key={{secrets.IQAIR_API_KEY}}", X = "GET")
# 等待上一个返回后，再发第 3 个curl(url = "https://api.airvisual.com/v2/city?city=Guangzhou&state=Guangdong&country=China&key={{secrets.IQAIR_API_KEY}}", X = "GET")

错误处理

AQI 等级参考

根据返回的 aqius（美国 EPA 标准）：

注意事项

1. 必须 HTTPS：所有请求必须使用 https://，HTTP 会被系统拒绝
2. 英文名称：所有国家、州/省、城市名称必须使用英文
3. 串行请求：严禁并行发送多个 curl 请求，必须等上一个返回后再发下一个
4. 层级关系：查询城市数据前，需先确认正确的国家和州/省
5. 数据时效：数据通常有 1-3 小时延迟，以 ts 字段为准
6. 历史数据：城市接口返回 history 字段，包含过去 48 小时的逐小时污染物和气象数据。如需更长时间跨度的趋势，应结合网络搜索获取公开年报数据