Offshore passage planning is one of those problems where “good enough” weather data genuinely isn’t good enough. A delivery skipper taking a 48-foot monohull from Newport to Bermuda needs more than a daily high/low summary — they need to know when pressure is falling fast, when swell period is short enough to make headway miserable, and whether the wind direction is going to clock around mid-passage. Most of this is derivable from standard forecast API output if you think about the right fields and the right thresholds.
Here’s how I’d build a basic passage risk scorer on top of WeatherAPI’s forecast endpoint, using nothing exotic.
What the Forecast Endpoint Actually Gives You
The /v1/forecast.json endpoint returns hourly forecast blocks for up to 14 days. Each block includes surface wind speed and direction, precipitation, visibility, cloud cover, and — critically — pressure. The pressure_mb field per hour is what makes rapid pressure change detection possible without pulling in separate GRIB2 model output.
What you don’t get natively: swell period, wave height, current data. For bluewater routing you’ll need to supplement with a dedicated marine model — NOAA’s WAVEWATCH III is freely available in GRIB2, or CMEMS if you’re working European waters. Within 200nm of the coast, though, the wind and pressure fields from a solid NWP-backed API will carry you surprisingly far.
Pressure Tendency: The Signal Most Apps Ignore
The single most useful derived metric for marine go/no-go decisions is pressure tendency — how fast the barometer is moving over a 3-hour window. Beaufort’s original storm warning criteria were largely barometer-based for good reason. A fall of more than 6 hPa in 3 hours is a rapid deepening event; anything above 3 hPa/3hr deserves attention.
Computing this from hourly API data is straightforward:
def pressure_tendency(hourly_data, hour_index, window_hours=3):
if hour_index < window_hours:
return None
p_now = hourly_data[hour_index]['pressure_mb']
p_prev = hourly_data[hour_index - window_hours]['pressure_mb']
return round(p_now - p_prev, 2) # negative = falling
A tendency of -4.0 or lower over 3 hours should immediately flag that forecast window as high risk, regardless of what the wind speed looks like at that specific hour. Pressure leads wind by several hours — that's the whole point.
Building a Per-Window Risk Score
Structure this as a function that ingests a sequence of hourly forecast blocks and returns a risk score (0–100) plus a list of triggered flags:
- Wind speed ≥ 25 kts sustained: +25 points
- Wind speed ≥ 35 kts sustained: +40 points (not additive with above — take the higher)
- Pressure tendency ≤ -3 hPa/3hr: +20 points
- Pressure tendency ≤ -6 hPa/3hr: +35 points
- Wind direction change ≥ 60° over 6 hours: +15 points (veering or backing rapidly signals frontal passage)
- Visibility < 1 km: +15 points
- Precip > 5 mm/hr: +10 points
Score 0–30: proceed. 30–60: monitor closely, consider departure timing. Above 60: delay or reroute.
These thresholds are starting points. A vessel with professional crew and storm sails will tolerate 35 knots differently than a short-handed delivery in unfamiliar waters. Expose the threshold configuration so users or operators can tune it per vessel class.
Wind Direction Shift Detection
The direction-change check needs a bit of care because wind direction wraps at 360°. A naive subtraction produces absurd numbers when direction crosses north — 350° to 10° is a 10° shift, not 340°.
def angular_diff(a, b):
diff = abs(a - b) % 360
return diff if diff <= 180 else 360 - diff
def direction_shift(hourly_data, hour_index, window_hours=6):
if hour_index < window_hours:
return None
d_now = hourly_data[hour_index]['wind_degree']
d_prev = hourly_data[hour_index - window_hours]['wind_degree']
return angular_diff(d_now, d_prev)
A shift of 60° or more over 6 hours is significant. On a passage already underway, that's the difference between a comfortable reach and being hard on the wind in a seaway that hasn't had time to settle.
Structuring the Departure Window Query
For actual passage planning, evaluate multiple potential departure times — every 6 hours over the next 5 days — and find the window where the maximum per-hour risk score across the expected passage duration is lowest.
- Estimate passage duration in hours based on distance and expected VMG. Add 20–30% — boats are slow and weather is inconvenient.
- Pull 14-day hourly forecast for both the departure point and a midpoint waypoint on long passages. Two API calls, two sets of hourly data.
- For each candidate departure time, slice the hourly array for the departure location for the first N hours and the midpoint location for hours N/2 through N.
- Score each hour, take the peak score across the window, return the ranked list of departure times.
This matters more than it might sound. A departure time that looks clean based on the first 24-hour window can carry a score of 75 at hour 36 — right when you're 200nm offshore with nowhere to duck in.
Where This Breaks Down
Fourteen-day forecasts degrade fast beyond day 5 or 6. GFS ensemble spread widens significantly past that range, and a deterministic hourly forecast at day 10 is basically a climatological guess dressed up as precision. For departure planning beyond 5 days out, weight risk scores lower and require a recheck within 48 hours of departure.
This approach also works on a per-point basis only. It doesn't model how a weather system moves relative to a moving vessel — the routing problem that commercial systems like PredictWind and Expedition solve with polars and full NWP model sweeps. For a departure-window tool aimed at coastal cruisers or marina operators, per-point is defensible. For a bluewater routing product, you'll eventually need to march the vessel position through the forecast grid as the passage progresses.
One edge case worth handling explicitly: rapid cyclogenesis in the western Atlantic during hurricane season, June through November. NWP models sometimes miss intensification events in the 24–48 hour window that NOAA's National Hurricane Center catches with their Tropical Weather Outlook. Building anything aimed at Caribbean or Gulf passages during that period means scraping the TWO and injecting an override flag when tropical development probability exceeds 40% within the routing corridor.