環境省のWBGT予測値をDuckDBへ保存し、実況・予測を分ける時系列APIを作る(r0052) release 0.0.5α Step 2

はじめに

遂に酷暑日が現れましたね。35°は当たり前の時代になりました。

前回のr0051では、環境省のWBGT実況値を取得し、検証後にDuckDBへ保存するところまで作成しました。

r0052では予測値を追加します。目標は、単に予測値を保存するだけではなく、時系列グラフで次の境界を扱いやすいAPIにすることです。

主な追加内容は次のとおりです。

予測APIには、発表時刻と予測対象時刻があります。

reference_time : 予測を発表した時刻
forecast_time  : 予測の対象時刻

同じ15時の予測でも、10時発表版と11時発表版では値が変わる可能性があります。そのため、次の複合キーで保存します。

wbgt_no + reference_time + forecast_time

古い発表版を上書きせず、後から予測の変化を確認できるようにしています。

APIの forecast_val は10倍整数として扱います。

305 → 30.5
300 → 30.0

DuckDBには元の整数と変換後の値を両方保存します。

実況値：timestamp <= boundary_time
予測値：timestamp > boundary_time
予測版：reference_time <= boundary_time のうち最新

実況値は現在時刻と同じ時刻を含めます。予測値は現在時刻より後だけです。

同じ観測時刻に推定値と実測値がある場合は、実測値を優先します。

GET /api/timeseries/{wbgt_no}

呼出し例です。

http://localhost:8000/api/timeseries/14163?current_time=2026-07-12T11:30:00%2B09:00&past_hours=24&future_hours=24

レスポンスは実況値と予測値を分けています。

{
  "boundary_time": "2026-07-12T11:30:00+09:00",
  "forecast_reference_time": "2026-07-12T11:00:00+09:00",
  "observations": [],
  "forecasts": []
}

フロントエンドでは、boundary_timeに縦線を引き、observationsを実線、forecastsを破線で表示できます。

ZIPファイルをダウンロードして、解凍してください。
解凍後のフォルダーで作業を進めます。

start_server.bat
fetch_now_sample.bat
show_timeseries_sample.bat

サンプルでは、実況値4件、予測値8件を保存します。地点14163の時系列APIは、11時30分を境に実況2件、予測3件を返します。

run_tests.bat

予測値の単位変換、複合主キー、最新発表版の選択、境界条件を確認します。

r0052で、実況値と予測値を同じDuckDBで管理し、現在時刻を境に分けて返せるようになりました。

次の段階では、この時系列APIをOpenLayersの地点ポップアップとPlotlyのグラフへ接続します。