Dive Conditions Forecasting

Instructions

Build dive condition forecasting systems that aggregate marine weather, ocean, and biological data from multiple APIs to produce actionable dive condition assessments with risk-level ratings for recreational divers.

1. Data Sources and API Integration

Integrate these data sources for comprehensive forecasts:

Open-Meteo Marine API (free, no key required)

• Endpoint: https://marine-api.open-meteo.com/v1/marine
• Provides: Wave height, wave period, wave direction, swell height, ocean current velocity
• Resolution: Hourly forecasts up to 7 days
• Parameters: latitude, longitude, hourly=wave_height,wave_period,wave_direction,swell_wave_height,ocean_current_velocity

Stormglass API (freemium, key required)

• Endpoint: https://api.stormglass.io/v2/weather/point
• Provides: Water temperature, visibility estimate, current speed/direction, air temperature, wind, pressure
• Resolution: Hourly, up to 10 days
• Auth: API key in Authorization header

NOAA APIs (free, no key required)

• Tides: https://api.tidesandcurrents.noaa.gov/api/prod/datagetter — tide predictions and observations
• Buoy data: https://www.ndbc.noaa.gov/data/realtime2/{station}.txt — real-time buoy observations
• Regional: US waters only, but high accuracy for covered stations

WorldTides API (freemium, key required)

• Endpoint: https://www.worldtides.info/api/v3
• Provides: Global tide predictions, tide heights, tidal extremes
• Coverage: Worldwide (useful for international dive destinations)

2. Condition Parameters

Track and score these parameters for every forecast:

Parameter	Source	Impact on Diving
Wave height (m)	Open-Meteo, Stormglass	Entry/exit difficulty, surface conditions
Swell period (s)	Open-Meteo	Longer periods = more manageable surge
Wind speed (knots)	Stormglass	Surface chop, boat comfort
Wind direction	Stormglass	Onshore wind degrades conditions at exposed sites
Water temperature (°C)	Stormglass	Exposure suit selection, comfort
Current speed (knots)	Stormglass, NOAA	Drift intensity, safety concern
Visibility estimate (m)	Stormglass, derived	Primary quality factor for divers
Tide state	NOAA, WorldTides	Affects current, visibility, site accessibility
Air temperature (°C)	Stormglass	Surface interval comfort
Barometric pressure (hPa)	Stormglass	Weather system indicator

3. Risk Level Assessment

Score dive conditions using a 5-level system:

Level	Label	Score Range	Description
1	Excellent	85-100	Calm seas, great visibility, mild current, warm water
2	Good	70-84	Minor chop or current, good visibility, comfortable conditions
3	Moderate	50-69	Noticeable swell or current, reduced visibility, experienced divers
4	Challenging	30-49	Significant waves/current, poor visibility, advanced divers only
5	Not Recommended	0-29	Dangerous conditions, dive should be postponed

Scoring Algorithm

base_score = 100

# Wave penalty (biggest impact on entry/exit and comfort)
if wave_height > 2.0m: score -= 40
elif wave_height > 1.5m: score -= 25
elif wave_height > 1.0m: score -= 15
elif wave_height > 0.5m: score -= 5

# Current penalty
if current_speed > 2.0kt: score -= 30
elif current_speed > 1.5kt: score -= 20
elif current_speed > 1.0kt: score -= 10
elif current_speed > 0.5kt: score -= 5

# Wind penalty
if wind_speed > 25kt: score -= 25
elif wind_speed > 20kt: score -= 15
elif wind_speed > 15kt: score -= 10

# Visibility bonus/penalty
if visibility > 20m: score += 10
elif visibility < 5m: score -= 20
elif visibility < 10m: score -= 10

# Temperature comfort (no safety impact, but affects experience)
if water_temp < 15°C: score -= 5
if water_temp < 10°C: score -= 10

4. Tide Integration

Tides affect dive conditions significantly:

• Incoming tide (flood): Often brings clearer water from open ocean
• Outgoing tide (ebb): Can reduce visibility with sediment; stronger outflow currents
• Slack tide: Best window for drift-sensitive sites — minimum current
• Spring tides (full/new moon): Strongest tidal currents — important for planning
• Neap tides (quarter moon): Weakest currents — better for novice divers

Calculate optimal dive windows by finding slack tide periods within daylight hours.

5. Seasonal and Biological Overlays

Layer biological data onto condition forecasts:

• Whale shark season: Specific months by region (Maldives: May-Nov, Mexico: Jun-Sep)
• Manta ray season: Linked to plankton blooms and current patterns
• Coral spawning: Typically 3-5 days after full moon in late spring/summer
• Jellyfish blooms: Seasonal risk by region, affects exposed-skin diving
• Plankton blooms: Reduce visibility but attract megafauna

6. Forecast Output Format

Structure forecast output as:

{
  "location": { "name": "Blue Corner, Palau", "lat": 7.05, "lon": 134.37 },
  "forecast_time": "2026-04-15T08:00:00Z",
  "conditions": {
    "wave_height_m": 0.8,
    "swell_period_s": 12,
    "current_speed_kt": 1.2,
    "wind_speed_kt": 10,
    "wind_direction": "NE",
    "water_temp_c": 29,
    "visibility_est_m": 25,
    "tide_state": "incoming",
    "next_slack": "2026-04-15T10:30:00Z"
  },
  "risk_level": 2,
  "risk_label": "Good",
  "score": 78,
  "recommendations": [
    "Good conditions for drift dive",
    "Moderate current — suit intermediate+ divers",
    "Best window: 10:00-11:30 around slack tide"
  ],
  "biological_notes": ["Manta ray season active — check cleaning stations"],
  "certification_minimum": "Advanced Open Water"
}

7. Caching and Update Strategy

• Cache API responses for 1 hour (conditions change gradually)
• Refresh on user request or when forecast window shifts
• Store historical conditions per site for trend analysis and seasonal averages
• Use WordPress transients for short-lived caches; custom table for historical data

Inputs Required

• Dive site location (name and/or lat/lon coordinates)
• Planned dive date and time
• Diver certification level (for risk-appropriate recommendations)
• Specific interests (marine life sightings, photography conditions)
• API keys for Stormglass and WorldTides (if using premium sources)

Output Format

• Structured condition forecast (JSON)
• Risk level assessment with score
• Optimal dive window recommendation
• Tide and current timeline
• Biological/seasonal overlay notes
• Certification-appropriate recommendations

Anti-Patterns

• Single API dependency: No single marine data API is reliable 100% of the time. Always integrate at least two sources with fallback logic.
• Ignoring tide state: Forecasting dive conditions without tide data misses the biggest variable affecting current and visibility at most sites.
• Universal scoring: A 1-meter swell means different things at a sheltered lagoon vs. an exposed wall dive. Score relative to site characteristics.
• Stale data without indicators: Always show when data was last fetched. Divers need to know forecast freshness.
• No certification gating: Conditions rated “moderate” for an experienced diver may be dangerous for a newly certified Open Water diver. Always contextualize risk to diver level.
• Over-precision: Displaying visibility to decimal places implies accuracy the data doesn’t support. Round to meaningful increments.