airnow-hourly-obs-fetch

用途

AirNow Hourly Obs Fetch 的核心目标是抓取 AirNow 逐小时空气质量观测（Hourly AQ Obs）数据文件。它针对一个 UTC 时间窗口获取 AirNow 官方文件端点上的逐小时观测文件产品，按任务边界框（bbox）和请求的污染物参数过滤数据行，并为每个“站点-小时-参数”返回一条规范化 JSON 记录，供下游处理使用。

该技能通过重试、限流和本地安全上限来保持执行的确定性。

主要能力

从 AirNow 官方文件端点获取逐小时 AQ 观测文件产品。
按 UTC 时间窗口、任务边界框和请求的污染物参数过滤数据。
为每个站点-小时-参数输出一条规范化 JSON 记录。
输出记录包含字段：aqsid、site_name、status、epa_region、latitude、longitude、country_code、state_name、observed_at_utc、data_source、reporting_areas、parameter_name、aqi_value、aqi_kind、raw_concentration、unit、measured、source_file_url。
完整原始载荷还保留请求元数据、传输统计、验证输出以及文件级失败详情，供下游审计。

使用方式

环境配置

通过环境变量配置运行时（参见 references/env.md），从 assets/config.example.env 开始。运行命令前加载环境变量：

set -a
source assets/config.example.env
set +a

工作流

验证有效配置：

python3 scripts/airnow_hourly_obs_fetch.py check-config --pretty

试运行（dry-run）以检查目标小时文件和过滤器：

python3 scripts/airnow_hourly_obs_fetch.py fetch \
  --bbox=-123.5,37.0,-121.5,38.8 \
  --start-datetime 2026-03-22T00:00:00Z \
  --end-datetime 2026-03-22T02:00:00Z \
  --parameter PM25 \
  --parameter OZONE \
  --dry-run \
  --pretty

执行抓取并写出输出载荷：

python3 scripts/airnow_hourly_obs_fetch.py fetch \
  --bbox=-123.5,37.0,-121.5,38.8 \
  --start-datetime 2026-03-22T00:00:00Z \
  --end-datetime 2026-03-22T02:00:00Z \
  --parameter PM25 \
  --parameter OZONE \
  --parameter NO2 \
  --output ./data/airnow-hourly-obs.json \
  --pretty

仓库策略

这是本仓库中规范的 AirNow 站点观测技能。
当 eco-council 或 OpenClaw 分配原始产物路径时，使用 --output 将此技能的完整 JSON 载荷写入该确切路径。
不要将 dry-run 输出视为已收集的证据。

适用场景

适用于需要按 UTC 时间窗口、地理边界框和指定污染物参数获取 AirNow 逐小时空气质量观测数据，并将其规范化为结构化 JSON 记录以供下游分析处理的场景。

限制

该技能仅消费 AirNow 逐小时文件产品。
该技能不进行地名地理编码。
该技能不做 AQI 健康解读或政策判断。
该技能将文件数据视为初步数据，仅用于分析支持，不用于监管决策。
该技能是本仓库中规范的 AirNow 抓取接口。

参考

references/env.md
references/airnow-hourly-obs-api-notes.md
references/airnow-hourly-obs-limitations.md
references/openclaw-chaining-templates.md

脚本

scripts/airnow_hourly_obs_fetch.py