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. 時間軸を設計します（タイムゾーン、timeformat、範囲）

   • 結果を現地時間の午前 0 時に合わせる必要がある場合は、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 を使って、直ちに処理を失敗させてください。
• デフォルトで大量の変数をリクエストしないでください。ペイロードを減らし、意図しない過剰利用を避けるため、クエリは最小限にしてください。

完了の定義

• 地名をジオコーディングし、座標とタイムゾーンを取得できます。
• 少なくとも1つのhourly変数、1つのタイムゾーン付きdaily変数、1つのcurrent変数について、Forecastデータを取得できます。
• 少なくとも1つの汚染物質と1つのAQI指標について、Air Qualityデータを取得できます。
• クライアントコードは、HTTPレベルの失敗とJSONレベルのerror: trueの両方に対応し、明確なメッセージを表示します。
• Air Quality（CAMS）とGeocoding（GeoNames）に関するドキュメントのクレジット表記要件を把握しています。

リンク

• ドキュメント
• リリース
• GitHub