open-meteo-air-quality-fetch

Open-Meteo Air Quality Fetch 是一个面向 Open-Meteo 空气质量 API 的数据抓取脚本，核心目标是在一次调用中为一个或多个坐标获取逐小时的空气质量背景数据。

用途 该工具用于抓取 Open-Meteo 的逐小时空气质量背景字段，支持包含起始和结束日期的日期窗口（start_date 与 end_date 均为闭区间），适合需要按坐标与时间窗获取空气质量原始数据的场景。

主要能力

• 单次调用支持一个或多个坐标（通过 --location 指定）。
• 支持闭区间的 start_date 和 end_date 窗口。
• 返回机器可读的 JSON，包含请求元数据、传输信息、校验摘要和规范化记录。
• 通过结构化日志保持运行可观测，可选输出日志文件。
• 内置稳健性机制：对瞬时 HTTP 和网络失败进行指数退避重试；在存在 Retry-After 时予以遵守，若超过配置上限则快速失败；以最小请求间隔进行限流；在远程调用前强制执行安全上限（最大位置数、最大天数范围、最大小时变量数）。
• 传输校验：HTTP 状态处理、JSON 内容类型、UTF-8 严格解码、JSON 解析。
• 结构校验：响应对象/列表形状、请求的 hourly 段是否存在、请求变量是否存在且数组长度对齐、时间轴可解析性与范围检查。

使用方式 需通过环境变量配置运行环境（参见 references/env.md），可从 assets/config.example.env 开始。加载环境变量的命令： set -a source assets/config.example.env set +a

工作流包括三步：

1. 校验有效配置： python3 scripts/open_meteo_air_quality_fetch.py check-config --pretty
2. 先对请求计划进行 dry-run： python3 scripts/open_meteo_air_quality_fetch.py fetch
   --location 52.52,13.41
   --start-date 2026-03-17
   --end-date 2026-03-18
   --hourly-var pm2_5
   --hourly-var pm10
   --timezone GMT
   --dry-run
   --pretty
3. 带校验与操作日志正式抓取： python3 scripts/open_meteo_air_quality_fetch.py fetch
   --location 52.52,13.41
   --location 48.85,2.35
   --start-date 2026-03-17
   --end-date 2026-03-18
   --hourly-var pm2_5
   --hourly-var pm10
   --hourly-var nitrogen_dioxide
   --hourly-var ozone
   --hourly-var us_aqi
   --domain auto
   --cell-selection nearest
   --timezone GMT
   --output ./data/open-meteo/open-meteo-air-quality-fetch.json
   --log-level INFO
   --log-file ./logs/open-meteo-air-quality-fetch.log
   --pretty

OpenClaw 兼容与调用 触发元数据保存在 name、description 和 agents/openai.yaml 中，使用 $open-meteo-air-quality-fetch 调用。调用应保持原子性，并通过 --location、--start-date、--end-date、--hourly-var、--domain、--cell-selection 进行参数化。循环任务应使用 OpenClaw 编排，而非此脚本。

OpenClaw 提示词模板 可在 OpenClaw 中直接使用以下模板，仅替换方括号占位符。 侦察（dry-run）： Use $open-meteo-air-quality-fetch. Run: python3 scripts/open_meteo_air_quality_fetch.py fetch
--location [LATITUDE,LONGITUDE]
--start-date [YYYY-MM-DD]
--end-date [YYYY-MM-DD]
--hourly-var [HOURLY_VARIABLE]
--timezone GMT
--dry-run
--pretty Return only the JSON result.

抓取（空气质量背景窗口）： Use $open-meteo-air-quality-fetch. Run: python3 scripts/open_meteo_air_quality_fetch.py fetch
--location [LATITUDE,LONGITUDE]
--start-date [YYYY-MM-DD]
--end-date [YYYY-MM-DD]
--hourly-var pm2_5
--hourly-var pm10
--hourly-var nitrogen_dioxide
--hourly-var ozone
--hourly-var us_aqi
--domain auto
--cell-selection nearest
--timezone GMT
--pretty Return only the JSON result.

校验（质量门）： Use $open-meteo-air-quality-fetch. Run: python3 scripts/open_meteo_air_quality_fetch.py fetch
--location [LATITUDE,LONGITUDE]
--start-date [YYYY-MM-DD]
--end-date [YYYY-MM-DD]
--hourly-var pm2_5
--hourly-var pm10
--hourly-var us_aqi
--timezone GMT
--pretty Check validation_summary.total_issue_count and validation_summary.ok. Return JSON plus one-line pass/fail verdict.

适用范围与限制 范围决策上，该工具仅保留一个针对 Open-Meteo 空气质量端点的原子抓取实现，不内嵌地理编码、站点合并、告警阈值或 AQI 解读逻辑；循环任务或多步融合（例如与 OpenAQ 融合）应使用 OpenClaw 编排，而非此脚本。

参考资料包括 references/env.md、references/open-meteo-air-quality-api-notes.md、references/open-meteo-air-quality-limitations.md、references/openclaw-chaining-templates.md，脚本位于 scripts/open_meteo_air_quality_fetch.py。

其他事实（如具体收费、价格、支持平台、性能效果等）在提供的资料中暂未提供。