✓ Verified 💻 Development ✓ Enhanced Data

Stormglass

Fetch surf-relevant ocean conditions from Stormglass by spot name or coordinates, including current

Rating: 4.1 (37 reviews)
Downloads: 6,842 downloads
Version: 1.0.0

Overview

Fetch surf-relevant ocean conditions from Stormglass by spot name or coordinates, including current snapshot.

Complete Documentation

View Source →

Stormglass Surf Skill

Purpose

Produce machine-readable surf condition data for cron-driven agent pipelines.

This skill resolves a surf spot name with Google Geocoding (or uses direct coordinates), queries Stormglass, and returns a stable JSON payload for downstream interpretation/rendering.

Inputs

Provide exactly one location mode:

--location "Spot name" (optional country/region in string), or
--lat --lon

Optional controls:

--horizon now|24h|48h|72h (default 72h)
--output json|pretty (default json, recommended for automation)
--source
--mock (offline deterministic data; useful for tests)

Required Environment Variables

STORMGLASS_API_KEY for Stormglass requests
GOOGLE_GEOCODING_API_KEY optional for --location (if absent, script falls back to OpenStreetMap Nominatim)

In --mock mode, no API keys are required.

Credential Matrix

Mode	`STORMGLASS_API_KEY`	`GOOGLE_GEOCODING_API_KEY`
--mock	not required	not required
live --lat/--lon	required	not required
live --location with Google	required	optional (preferred when set)
live --location with OSM fallback	required	not required

Primary credential is STORMGLASS_API_KEY.

Execution Commands

JSON output for cron:

bash

python scripts/surf_report.py --location "Highcliffe Beach" --horizon 72h --output json

Direct coordinates:

bash

python scripts/surf_report.py --lat 50.735 --lon -1.705 --horizon 24h --output json

Offline test run:

bash

python scripts/surf_report.py --location "Highcliffe Beach" --horizon now --mock --output json

Output Contract (JSON-first)

Top-level keys are stable:

meta: request metadata, timestamps, input mode, optional warnings
location: resolved place details and coordinates
now: instantaneous surf-relevant metrics
forecast: horizon summaries and best windows
tides: tide extremes and inferred current tide trend

Expected metric coverage (null if unavailable):

waveHeightM
swellHeightM
swellPeriodS
swellDirectionDeg
windSpeedMps
windDirectionDeg
windGustMps
waterTemperatureC

Exit Codes

0: success
2: invalid CLI usage/arguments
3: missing API keys/configuration
4: external API failure (geocoding/Stormglass)
5: response parsing/normalization failure

Agent Handoff Rules

Prefer --output json for downstream agents.
Treat null metrics as "not provided by source", not zero.
Read field-level details in reference.md.
Use examples.md for prompt and command patterns.
Use scripts/test_surf_report.py before cron rollout.
Optional: use scripts/normalize_surf_data.py to enforce strict schema defaults before rendering.