open-meteo

Open Meteo

目标

提供一种可靠且适合生产环境的方式来调用 Open-Meteo API（Forecast、Air Quality、Geocoding），选择变量，控制时间、单位和时区，并以一致的方式解析响应。

步骤

1. 选择正确的 API 和基础 URL

   • Forecast：https://api.open-meteo.com/v1/forecast
   • Air Quality：https://air-quality-api.open-meteo.com/v1/air-quality
   • Geocoding：https://geocoding-api.open-meteo.com/v1/search

2. 解析坐标（如果只有地名）

   • 使用 name 和可选的 language、countryCode、count 调用 Geocoding。
   • 在后续调用中使用返回的 latitude、longitude 和 timezone。

3. 设计时间轴（时区、时间格式和范围）

   • 当结果必须与当地午夜对齐时，优先使用 timezone=auto。
   • 如果请求 daily=...，请设置 timezone（文档：daily 需要 timezone）。
   • 选择 timeformat=iso8601，便于阅读；或选择 timeformat=unixtime，以获得更紧凑的格式。
     • 如果使用 unixtime，请记住时间戳为 GMT+0，必须应用 utc_offset_seconds 才能获得正确的当地日期。
   • 选择范围控制方式：
     • forecast_days 和可选的 past_days，或
     • 明确指定 start_date/end_date（YYYY-MM-DD）；对于日内数据，还可指定 start_hour/end_hour。

4. 尽量精简地选择变量（避免“下载所有内容”）

   • Forecast：通过 hourly=...、daily=...、current=... 仅请求所需变量。
   • Air Quality：通过 hourly=...、current=... 仅请求所需变量。
   • 变量名必须准确；拼写错误会返回包含 error: true 的 JSON 错误。

5. 审慎选择单位和模型

   • Forecast 单位：
     • temperature_unit（celsius / fahrenheit）
     • wind_speed_unit（kmh / ms / mph / kn）
     • precipitation_unit（mm / inch）
   • Forecast 模型选择：
     • 默认的 models=auto / “Best match” 会组合最佳模型。
     • 也可以通过 models=... 明确请求模型。
     • 也提供特定提供方的 forecast 端点（提供方由路径决定）。示例和文档链接见 references/models.md（“Endpoints vs models=”一节）。
     • 有关特定提供方／模型的选择权衡，请参阅 references/models.md。
   • Air Quality 域选择：
     • domains=auto（默认）或 cams_europe / cams_global。

6. 实现稳健的请求／响应处理

   • 分别处理 HTTP 错误和 JSON 层级的错误。
   • JSON 错误格式为：
     • {"error": true, "reason": "..."}
   • 请求多个位置（以逗号分隔的坐标）时，JSON 输出结构会变为结构列表。
   • 如需导出数据，也可以使用 format=csv 或 format=xlsx。

7. 使用“已知城市”检查验证正确性

   • 对 “Berlin” 进行地理编码 → 请求 Forecast hourly=temperature_2m，时间范围为 1–2 天 → 验证时区和数组长度。
   • 请求 Air Quality hourly=pm10,pm2_5,european_aqi → 验证单位以及是否包含 hourly_units。

严格禁止事项

• 不要在此技能的实现指南中加入范围外的 API：Historical Weather、Ensemble Models、Seasonal Forecast、Climate Change、Marine、Satellite Radiation、Elevation、Flood。
• 请求 daily 变量时，不要省略 timezone（根据文档要求）。
• 不要假设 unixtime 时间戳为当地时间；它们采用 GMT+0，需要通过 utc_offset_seconds 进行调整。
• 不要忽略 {"error": true} 响应；应立即失败并提供返回的 reason。
• 默认不要请求大量变量；应尽量精简查询，以减少负载并避免意外的过度使用。

完成标准

• 可以对地点名称进行地理编码，并获取坐标和时区。
• 可以获取预报数据，其中至少包含一个 hourly 变量、一个 daily 变量（带时区）和一个 current 变量。
• 可以获取空气质量数据，其中至少包含一种污染物和一项 AQI 指标。
• 客户端代码能够处理 HTTP 层面的失败和 JSON 层面的 error: true，并提供清晰的错误消息。
• 已记录文档中对空气质量（CAMS）和地理编码（GeoNames）的署名要求。

链接

• 文档
• 发行版本
• GitHub