Surf Forecast API Documentation

API Overview

The Surf Forecast API provides advanced surf forecasting capabilities using bathymetry data and wave physics modeling. Generate detailed surf reports with wave transformation analysis, breaking predictions, and swell interaction modeling.

Base URL: https://your-api-domain.com
Version: 1.0.0
Content-Type: application/json
Rate Limits: 100 requests per minute

Key Features

🌊 Advanced wave physics modeling with shoaling and refraction
📊 Real-time bathymetry data integration
🏄‍♂️ Surf-specific metrics and breaking predictions
🌀 Multi-swell interaction analysis
📈 Wave transformation visualizations
💡 AI-powered surf insights and recommendations

Authentication

Currently, the API does not require authentication. All endpoints are publicly accessible.

Note: Authentication will be required in future versions. Please monitor the changelog for updates.

Available Endpoints

GET /

Main UI interface for interactive surf forecasting

Returns the main web interface for generating surf forecasts interactively.

GET /health

API health check and system status

Returns detailed health information about the API and its dependencies.

Response Example

{
  "status": "operational",
  "version": "1.0.0",
  "endpoints": {
    "/": "Root endpoint",
    "/health": "Health check endpoint",
    "/forecast": "Forecast generation endpoint (POST)"
  },
  "dependencies": {
    "surf_forecast": "operational",
    "bathymetry_api": "operational"
  }
}

GET /api

Basic API status check

Simple endpoint to verify the API is running.

Response Example

{
  "message": "Surf Forecast API is running"
}

Forecast Generation API

POST /forecast

Generate detailed surf forecast with wave physics analysis

This is the main endpoint for generating surf forecasts. It analyzes wave conditions, applies bathymetry data, and returns comprehensive surf reports with breaking predictions, wave transformation analysis, and swell interactions.

Request Parameters

latitude float required

Target location latitude (-90 to 90)

longitude float required

Target location longitude (-180 to 180)

swells array required

Array of swell components. Each swell must have:

height (float): Wave height in meters (> 0)
period (float): Wave period in seconds (> 0)
direction (float): Wave direction in degrees (0-360)

radius_miles float optional

Bathymetry data radius in miles (default: 5.0, max: 50.0)

zoom_factor float optional

Zoom factor for analysis (default: 3.0)

interpolation_order integer optional

Bathymetry interpolation order (default: 3)

smoothing_sigma float optional

Smoothing parameter for bathymetry (default: 0.5)

Request Example

POST /forecast
Content-Type: application/json

{
  "latitude": 33.7701,
  "longitude": -118.1937,
  "swells": [
    {
      "height": 2.5,
      "period": 12.0,
      "direction": 270.0
    },
    {
      "height": 1.8,
      "period": 8.5,
      "direction": 285.0
    }
  ],
  "radius_miles": 8.0,
  "zoom_factor": 3.5
}

Response Structure

The response contains three main sections:

Field	Type	Description
`llm_report`	object	Raw forecast data with physics calculations and metrics
`surf_report`	object	Structured surf report in JSON format matching UI content
`plot_base64`	string	Base64-encoded PNG visualization of wave analysis

Response Examples

200 OK - Success

{
  "llm_report": {
    "nearshore_effects": {
      "wave_transformation": {
        "height_nearshore_m": 2.8,
        "height_gain_percent": 12.5,
        "dominant_direction_cardinal": "W",
        "direction_shift_deg": -15.2,
        "refraction_category": "moderate"
      },
      "deep_water_combination": {
        "combined_height_m": 2.5,
        "combined_period_s": 12.0,
        "combined_direction_cardinal": "W",
        "input_swells": [...]
      },
      "terrain_metrics": {
        "focus_quality": 0.75,
        "avg_slope": 0.8
      },
      "depth_m": 4.2,
      "notes": [...]
    }
  },
  "surf_report": {
    "surf_summary_header": {
      "emoji": "🏄‍♂️",
      "text": "Waves are 9.2ft (2.8m) with 12s period from W..."
    },
    "sections": [
      {
        "title": "🌊 Wave Conditions",
        "type": "wave_stats",
        "stats": [...]
      },
      ...
    ]
  },
  "plot_base64": "iVBORw0KGgoAAAANSUhEUgAAAlgAAAI4CAY..."
}

400 Bad Request - Invalid Input

{
  "error": "Missing required fields: latitude, longitude, or swells"
}

500 Internal Server Error

{
  "error": "Failed to generate forecast: Bathymetry data unavailable"
}

Usage Examples

Basic Single Swell Forecast

cURL

curl -X POST https://your-api-domain.com/forecast \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 21.3099,
    "longitude": -157.8581,
    "swells": [{
      "height": 3.0,
      "period": 14.0,
      "direction": 315.0
    }]
  }'

Python

import requests

url = "https://your-api-domain.com/forecast"
data = {
    "latitude": 21.3099,
    "longitude": -157.8581,
    "swells": [{
        "height": 3.0,
        "period": 14.0,
        "direction": 315.0
    }]
}

response = requests.post(url, json=data)
forecast = response.json()

Multi-Swell Analysis

JavaScript

const forecast = await fetch('/forecast', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    latitude: 33.7701,
    longitude: -118.1937,
    swells: [
      {
        height: 2.5,
        period: 12.0,
        direction: 270.0
      },
      {
        height: 1.8,
        period: 8.5,
        direction: 285.0
      }
    ],
    radius_miles: 10.0
  })
});

const data = await forecast.json();

Response Analysis

# Extract key metrics
height_ft = data['surf_report']['sections'][0]['stats'][0]['value']
breaking_status = "breaking" if data['llm_report']['nearshore_effects']['wave_transformation']['height_nearshore_m'] / data['llm_report']['nearshore_effects']['depth_m'] > 0.78 else "not breaking"

# Get wave interaction analysis
swell_section = next(s for s in data['surf_report']['sections'] if s['type'] == 'swell_analysis')
interactions = swell_section.get('wave_interaction_analysis', {})

Advanced Configuration

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "swells": [
    {
      "height": 1.8,
      "period": 10.0,
      "direction": 290.0
    }
  ],
  "radius_miles": 15.0,
  "zoom_factor": 4.0,
  "interpolation_order": 3,
  "smoothing_sigma": 0.3
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

Status Code	Error Type	Description
400	Bad Request	Invalid input data, missing required fields, or parameter validation errors
500	Internal Server Error	Server-side processing error, bathymetry data issues, or computation failures
503	Service Unavailable	External dependencies unavailable (bathymetry API, etc.)

Common Error Scenarios

Invalid Coordinates

{"error": "Latitude must be between -90 and 90"}

Invalid Swell Data

{"error": "Invalid swell data"}

Missing Required Fields

{"error": "Missing required fields: latitude, longitude, or swells"}

Bathymetry Data Issues

{"error": "Failed to generate forecast: Bathymetry data unavailable"}

SDKs & Integration Tools

While there are no official SDKs yet, the API is designed to work seamlessly with standard HTTP clients in any programming language.

Recommended Libraries

Python: requests, httpx
JavaScript: fetch, axios
Node.js: node-fetch, axios
PHP: curl, guzzle
Ruby: net/http, faraday
Go: net/http

🏄‍♂️ Try the Interactive Interface

Need Help? The API is designed to be self-documenting. Check the /health endpoint for system status and the main interface at / for interactive testing.