BLUEMAP Marine Weather Data Inventory Manual

1. Data Characteristics

Forecast data is defined by a model run time and a forecast step. The valid time is calculated as run time plus step hours.

Example: run_time_utc=2026-02-02T06:00:00Z and step_hours=24 means valid time is 2026-02-03 06:00 UTC.

2. Data Sources

ECMWF IFS

Atmosphere and wave forecast data. Query mapping: source=ecmwf, model=ifs.

NOAA GFS

Atmosphere and wave forecast data. Query mapping: source=noaa, model=gfs.

Source	Model	Description
ecmwf	ifs	ECMWF IFS Atmosphere + Wave
noaa	gfs	NOAA GFS Atmosphere + Wave

3. Data Availability

Both sources use four daily run cycles: 00Z, 06Z, 12Z, and 18Z.

Source	Step interval	Maximum range
ECMWF IFS	3-hour intervals to 144h, then 6-hour intervals for extended runs	Up to 360h
NOAA GFS	3-hour intervals to 384h	Up to 384h

4. Directory Structure

{source}/{model}/yyyy/yyyy-mm/yyyy-mm-dd/hhZ/{dataset_code}/{variable}/dataset file

Example paths:

ecmwf/ifs/2025/2025-07/2025-07-01/00Z/original/swh/
noaa/gfs/2026/02/02/06Z/original/HTSGW/

5. Provided Variables

Group	ECMWF	NOAA	Computed
Atmosphere	10u, 10v	UGRD, VGRD, WIND, WDIR	wind_speed_10m, wind_dir_10m
Wave	swh, mwp, mwd	HTSGW, PERPW, DIRPW	-

6. API Usage

Endpoint	Description
`GET /api/griddata`	Retrieve gridded variable data.
`GET /api/gridfile`	Return a presigned URL for one original GRIB2 file.
`GET /api/sources`	List available data sources.
`GET /api/variables`	List variables by source.

Grid data example

GET /api/griddata
  ?source=noaa
  &dataset_code=original
  &model=gfs
  &variable=HTSGW
  &run_time_utc=2026-02-02T06:00:00Z
  &step_hours=24
  &lat=35.0&lon=129.0&buffer_km=200

7. How to Read the Result Array

Values are stored row-major, bottom-up. Index 0 is the southwest grid cell.

index = y * nx + x
x: west to east
y: south to north

8. Wind Speed and Direction

wind_speed = np.hypot(u, v)
wind_dir_from = (270.0 - np.degrees(np.arctan2(v, u))) % 360.0

Wind direction uses the meteorological FROM-direction convention: 0° is North and direction increases clockwise.

9. Quick Start

Call GET /api/latest — no parameters required — to receive a single JSON manifest covering all current NOAA GFS Wave variables (7 variables × up to 89 steps) and EOT20 tidal elevation (89 steps), each with a presigned S3 download URL.

One-time snapshot: All presigned URLs in the manifest expire at issued.expires_at (1 hour from the request time). Re-call /api/latest to get a fresh manifest.

Endpoint

GET http://weather-api.bmap.kr/api/latest

Download script usage

# Download everything (calls /api/latest automatically)
python download_latest.py

# Save manifest first, then download
python download_latest.py --save-json latest.json

# Re-download from a saved manifest (no API call, valid within 1 h)
python download_latest.py --from-json latest.json

# Specific variables only
python download_latest.py --vars HTSGW WIND tidal_elevation

# Adjust parallel workers and output directory
python download_latest.py --workers 16 --out-dir ./data

↓ Downloader Script (ZIP)

Weather Service