﻿================================================================
  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .
================================================================  

-------------------------------------------------------------
|                                                                      |
|        Marine Weather Data Downloader                    |
|        Optimal Loads API  |  GRIB2 File Fetcher            |
|                                                                      | 
-------------------------------------------------------------



A script that automatically downloads marine weather data (GRIB2)
from the API in parallel.


================================================================
  Requirements
================================================================

  * Python 3.10 or higher
  * pip install requests

  All other libraries are Python standard library.


================================================================
  Quick Start
================================================================

  # Download all variables
  python download_latest.py

  # Select specific variables only
  python download_latest.py --vars HTSGW WDIR

  Note: Presigned URLs expire approximately 1 hour after generation.
        Re-downloads via --from-json are only possible within that window.


================================================================
  Output Structure
================================================================

  weather_data/
  |
  +-- WDIR/
  |     original_WDIR_20260615_00Z_step000.grib2
  |     original_WDIR_20260615_00Z_step003.grib2
  |     ...
  |
  +-- HTSGW/
  |     original_HTSGW_20260615_00Z_step000.grib2
  |     ...
  |
  +-- tidal_elevation/
  |     ...
  |
  +-- download_20260615_120000.txt    <-- download log (includes variable descriptions)


================================================================
  Variable List
================================================================

  VAR               Name                       Unit   Source
  ----------------  -------------------------  -----  ----------
  WDIR              Wind Direction             deg    noaa/gfs
  WIND              Wind Speed                 m/s    noaa/gfs
  HTSGW             Significant Wave Height    m      noaa/gfs
  DIRPW             Peak Wave Direction        deg    noaa/gfs
  PERPW             Peak Wave Period           s      noaa/gfs
  UGRD              Eastward Current           m/s    noaa/gfs
  VGRD              Northward Current          m/s    noaa/gfs
  tidal_elevation   Astronomical Tide Height   m      eot20/tide


================================================================
  Variable Descriptions
================================================================

[WDIR]
  Name      : Wind Direction
  Unit      : degree
  Direction : from
  Source    : noaa/gfs
  Desc      : Direction the wind blows from, in degrees clockwise
              from north (0=N, 90=E, 180=S, 270=W).
              Ex) 225 means wind coming from the southwest
              (a southwesterly wind).

[WIND]
  Name      : Wind Speed
  Unit      : m/s
  Direction : -
  Source    : noaa/gfs
  Desc      : Wind strength only; magnitude with no direction
              information.

[HTSGW]
  Name      : Significant Wave Height
  Unit      : m
  Direction : -
  Source    : noaa/gfs
  Desc      : Average height of the highest one-third of waves.
              Wave height is measured from the trough (lowest
              point) to the crest (highest point).

[DIRPW]
  Name      : Peak Wave Direction
  Unit      : degree
  Direction : from
  Source    : noaa/gfs
  Desc      : When many waves overlap, the direction from which
              the wave carrying the most energy comes - i.e. the
              direction of the dominant swell at that moment.
              Same angle convention as wind direction.

[PERPW]
  Name      : Peak Wave Period
  Unit      : s
  Direction : -
  Source    : noaa/gfs
  Desc      : Period of the wave carrying the most energy.
              A long period (roughly 12-20 s) indicates a swell
              that traveled from far away; a short period
              (roughly 4-6 s) indicates a wind-driven wave formed
              nearby. Shorter period = narrower spacing between
              waves.

[UGRD]
  Name      : Eastward Current
  Unit      : m/s
  Direction : from
  Source    : noaa/gfs
  Desc      : East-west component of the current. Positive =
              eastward, negative = westward. Combine with VGRD
              to get the actual current direction and speed.

[VGRD]
  Name      : Northward Current
  Unit      : m/s
  Direction : from
  Source    : noaa/gfs
  Desc      : North-south component of the current. Positive =
              northward, negative = southward.

[tidal_elevation]
  Name      : Astronomical Tide Height
  Unit      : m
  Direction : -
  Source    : eot20/tide
  Desc      : Sea-surface height driven only by the gravitational
              pull of celestial bodies such as the Moon and Sun,
              which makes the water rise and fall on a regular
              cycle. Weather effects such as wind, pressure, and
              storms are not included.
              Excludes: storm surge, weather-driven sea-level
              changes, wave height, wind setup, river discharge,
              observed sea level, and real-time data assimilation.
              Spatial grid : 0.25 x 0.25 deg lat/lon.
              Time structure: tides have no forecast run concept,
              so run_time_utc = valid_time_utc and step_hours = 0;
              generated at 3-hour intervals (00Z/03Z/.../21Z).


================================================================
  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .  '  .
================================================================

================================================================
  © 2026 BLUEMAP. All rights reserved.
  Contact : Kim  |  hjk@bluemap.dev
================================================================