SeaLegs AI Marine Forecast API

Get AI-powered marine weather forecasts for any location worldwide. Includes wind, waves, visibility, precipitation analysis with GO/CAUTION/NO-GO safety classifications.

Features

• SpotCast Forecasts: Get marine weather forecasts for any coordinates worldwide
• AI Safety Analysis: GO / CAUTION / NO-GO classifications for each day
• Vessel-Specific: Tailored recommendations based on boat type and size
• Multi-Language: Supports English, Spanish, French, Portuguese, Italian, Japanese

Setup

1. Get an API Key

1. Sign up at https://developer.sealegs.ai — you'll get 10 free credits to get started
2. Generate an API key from your dashboard
3. Need more? Add credits anytime ($10 = 200 forecast-days)

2. Configure OpenClaw

Add to your OpenClaw configuration:

{
  skills: {
    entries: {
      "sealegs-marine-forecast": {
        enabled: true,
        apiKey: "sk_live_your_key_here"
      }
    }
  }
}

Or set the environment variable:

export SEALEGS_API_KEY=sk_live_your_key_here

3. Install the Skill

clawhub install sealegs-marine-forecast

Usage Example

// Miami, FL
POST /v3/spotcast
{
  "latitude": 25.7617,
  "longitude": -80.1918,
  "start_date": "2026-02-10T00:00:00Z",
  "num_days": 2,
  "vessel_info": {"type": "sailboat", "length_ft": 35}  // optional
}

Sample response:

{
  "id": "spc_FrZdSAs6T3cxbXiPtNZvxu",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "forecast_period": {
    "start_date": "2026-02-10T00:00:00-05:00",
    "end_date": "2026-02-11T23:59:59-05:00",
    "num_days": "2"
  },
  "trip_duration_hours": "12",
  "metadata": {
    "location_name": "Miami Marina"
  },
  "latest_forecast": {
    "status": "completed",
    "ai_analysis": {
      "summary": "Ideal conditions both days with light winds",
      "daily_classifications": [
        {
          "date": "2026-02-10",
          "classification": "GO",
          "short_summary": "Outstanding conditions all day with light winds under 7kt and calm 1.1-1.6ft seas. Best window is morning 5:00 AM-12:00 PM with nearly calm 1-4kt northwest winds and comfortable 1.4ft seas at 11-second periods.",
          "summary": "Outstanding sailing conditions throughout Monday with exceptionally light winds and calm seas. Morning hours offer the best window with nearly calm 1-4kt northwest winds and comfortable 1.4ft seas at 11-second periods from the northeast."
        },
        {
          "date": "2026-02-11",
          "classification": "GO",
          "short_summary": "Exceptional conditions with very light winds 1-6kt and minimal 1.2-1.3ft seas all day. Best window 9:00 AM-1:00 PM offers glassy conditions with 1-3kt winds and 1.2ft seas at 11-second periods.",
          "summary": "Exceptional boating conditions on Tuesday with very light winds and minimal seas throughout the day. Morning through midday provides ideal glassy conditions with 1-3kt east-southeast winds and 1.2ft seas at 10-11 second periods from the northeast."
        }
      ]
    }
  }
}

API Endpoints

Weather Factors Used

• Wind speed, gusts, and direction
• Wave height, period, and direction
• Visibility and fog probability
• Precipitation probability and intensity
• Air and water temperature

Authentication

All requests require:

Authorization: Bearer $SEALEGS_API_KEY
Content-Type: application/json

Rate Limits

• Standard tier: 60 requests per minute
• Rate limit headers included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Billing

• 1 credit per forecast-day (3-day forecast = 3 credits)
• GET operations are free
• Refreshes cost 1 credit per forecast-day

---

SpotCast Forecasts

SpotCast generates AI-powered marine weather forecasts for specific coordinates.

Create SpotCast

POST https://api.sealegs.ai/v3/spotcast

Creates a new forecast request. Processing is asynchronous (typically 30-60 seconds).

Required parameters:

• latitude (number): -90 to 90
• longitude (number): -180 to 180
• start_date (string): ISO 8601 format (e.g., "2025-12-05T00:00:00Z")
• num_days (integer): 1-5

Optional parameters:

• webhook_url (string): HTTPS endpoint for completion notification
• metadata (object): Custom key-value pairs for your reference
• trip_duration_hours (integer): Trip duration in hours
• preferences.language: en, es, fr, pt, it, ja (default: en)
• preferences.distance_units: nm, mi, km (default: nm)
• preferences.speed_units: kts, mph, ms (default: kts)
• vessel_info.type: powerBoat, sailboat, pwc, yacht, catamaran
• vessel_info.length_ft: 1-500

Example request:

curl -X POST https://api.sealegs.ai/v3/spotcast \
  -H "Authorization: Bearer $SEALEGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 25.7617,
    "longitude": -80.1918,
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2,
    "vessel_info": {"type": "sailboat", "length_ft": 35}
  }'

Response (202 Accepted):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "processing",
  "created_at": "2025-12-01T10:30:00Z",
  "estimated_completion_seconds": 45,
  "credits_charged": 2,
  "credits_remaining": 98,
  "links": {
    "self": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz",
    "forecast": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/forecast/fcst_xyz789",
    "status": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/status"
  }
}

Check SpotCast Status

GET https://api.sealegs.ai/v3/spotcast/{id}/status

Poll this endpoint until status is "completed" or "failed". Recommended poll interval: 10-15 seconds.

Status values:

• pending: Queued for processing (no progress field)
• processing: Currently generating forecast (includes progress)
• completed: Ready to retrieve (includes progress at 100%)
• failed: Error occurred

Progress stages (only present when status is processing or completed):

• fetching_weather
• processing_data
• ai_analysis
• completing
• completed (100%)

Example request:

curl https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/status \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

Response (pending):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "pending",
  "created_at": "2025-12-01T10:30:00Z"
}

Response (processing):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "processing",
  "created_at": "2025-12-01T10:30:00Z",
  "progress": {
    "stage": "ai_analysis",
    "percentage": 75
  }
}

Response (completed):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_xyz789",
  "status": "completed",
  "created_at": "2025-12-01T10:30:00Z",
  "completed_at": "2025-12-01T10:30:45Z",
  "progress": {
    "stage": "completed",
    "percentage": 100
  }
}

Get SpotCast

GET https://api.sealegs.ai/v3/spotcast/{id}

Retrieves the completed forecast with AI analysis.

Example request:

curl https://api.sealegs.ai/v3/spotcast/spc_abc123xyz \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

Response (200 OK):

{
  "id": "spc_abc123xyz",
  "created_at": "2025-12-01T10:30:00Z",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "end_date": "2025-12-06T00:00:00Z",
    "num_days": 2
  },
  "trip_duration_hours": 12,
  "forecast_count": 1,
  "metadata": {
    "location_name": "Miami Marina"
  },
  "latest_forecast": {
    "forecast_id": "fcst_xyz789",
    "status": "completed",
    "created_at": "2025-12-01T10:30:00Z",
    "completed_at": "2025-12-01T10:30:45Z",
    "ai_analysis": {
      "summary": "Excellent conditions expected. Light winds 8-12kt from the NE with calm 1-2ft seas.",
      "daily_classifications": [
        {
          "date": "2025-12-05",
          "classification": "GO",
          "summary": "Light winds 8-12kt from NE. Seas 1-2ft. Visibility excellent at 10+ nm. No precipitation expected."
        },
        {
          "date": "2025-12-06",
          "classification": "CAUTION",
          "summary": "Winds increasing to 15-20kt. Seas building to 3-4ft by afternoon. Morning departure recommended."
        }
      ]
    }
  }
}

Refresh SpotCast

POST https://api.sealegs.ai/v3/spotcast/{id}/refresh

Updates an existing forecast with the latest weather data. Costs 1 credit per forecast-day.

Optional body:

• webhook_url (string): Override webhook for this refresh

Example request:

curl -X POST https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/refresh \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

Response (202 Accepted):

{
  "id": "spc_abc123xyz",
  "forecast_id": "fcst_newxyz789",
  "status": "processing",
  "created_at": "2025-12-02T08:00:00Z",
  "links": {
    "self": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz",
    "status": "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/status"
  }
}

List Forecasts

GET https://api.sealegs.ai/v3/spotcast/{id}/forecasts

Lists all forecasts for a SpotCast, sorted by creation date (newest first). Each time you create or refresh a SpotCast, a new forecast is generated.

Query parameters:

• limit (integer): Number of results to return (default: 10)

Example request:

curl "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/forecasts?limit=5" \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

Response (200 OK):

{
  "spotcast_id": "spc_abc123xyz",
  "data": [
    {
      "forecast_id": "fcst_newxyz789",
      "status": "completed",
      "created_at": "2025-12-02T08:00:00Z",
      "completed_at": "2025-12-02T08:00:42Z"
    },
    {
      "forecast_id": "fcst_xyz789",
      "status": "completed",
      "created_at": "2025-12-01T10:30:00Z",
      "completed_at": "2025-12-01T10:30:45Z"
    }
  ],
  "has_more": false
}

Get Forecast

GET https://api.sealegs.ai/v3/spotcast/{id}/forecast/{forecast_id}

Retrieves a specific forecast with full details including AI analysis. Use this to access any forecast in a SpotCast's history, not just the latest one.

Example request:

curl "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/forecast/fcst_xyz789" \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

Response (200 OK - Completed):

{
  "forecast_id": "fcst_xyz789",
  "spotcast_id": "spc_abc123xyz",
  "status": "completed",
  "created_at": "2025-12-01T10:30:00Z",
  "completed_at": "2025-12-01T10:30:45Z",
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2
  },
  "ai_analysis": {
    "summary": "Excellent conditions expected. Light winds 8-12kt from the NE with calm 1-2ft seas.",
    "daily_classifications": [
      {
        "date": "2025-12-05",
        "classification": "GO",
        "summary": "Light winds and calm seas throughout the day."
      },
      {
        "date": "2025-12-06",
        "classification": "CAUTION",
        "summary": "Improving conditions with best windows in the afternoon."
      }
    ]
  }
}

Response (200 OK - Processing):

{
  "forecast_id": "fcst_xyz789",
  "spotcast_id": "spc_abc123xyz",
  "status": "processing",
  "created_at": "2025-12-01T10:30:00Z",
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2
  },
  "progress": {
    "stage": "analyzing",
    "percentage": 65
  }
}

Response (200 OK - Failed):

{
  "forecast_id": "fcst_xyz789",
  "spotcast_id": "spc_abc123xyz",
  "status": "failed",
  "created_at": "2025-12-01T10:30:00Z",
  "forecast_period": {
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2
  },
  "error": "Processing failed"
}

List SpotCasts

GET https://api.sealegs.ai/v3/spotcasts

Retrieves all SpotCasts for your account.

Query parameters:

• limit (integer): 1-100 results (default: 20)
• after (string): Cursor for pagination

Example request:

curl "https://api.sealegs.ai/v3/spotcasts?limit=10" \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

Response (200 OK):

{
  "data": [
    {
      "id": "spc_abc123xyz",
      "created_at": "2025-12-01T10:30:00Z",
      "coordinates": {
        "latitude": 25.7617,
        "longitude": -80.1918
      },
      "start_date": "2025-12-05T00:00:00-05:00",
      "end_date": "2025-12-06T23:59:59-05:00",
      "num_days": 2,
      "latest_forecast": {
        "forecast_id": "fcst_xyz789",
        "status": "completed"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "spc_def456"
}

---

Account

Get Balance

GET https://api.sealegs.ai/v3/account/balance

Returns your current credit balance and usage.

Example request:

curl https://api.sealegs.ai/v3/account/balance \
  -H "Authorization: Bearer $SEALEGS_API_KEY"

Response (200 OK):

{
  "credit_balance": 100,
  "total_credits_purchased": 200,
  "total_credits_used": 100,
  "purchase_url": "https://developers.sealegs.ai/dashboard/billing"
}

---

Webhooks

When you provide a webhook_url during SpotCast creation or refresh, SeaLegs sends a POST request to that URL when processing completes or fails.

Webhook Headers

Content-Type: application/json
X-SeaLegs-Event: spotcast.forecast.completed
X-SeaLegs-Signature: sha256=abc123...
X-SeaLegs-Delivery-ID: whk_abc123xyz
X-SeaLegs-Timestamp: 1733045400
User-Agent: SeaLegs-Webhooks/1.0

Verifying Signatures

Every webhook includes an HMAC-SHA256 signature in the X-SeaLegs-Signature header. Your webhook secret is available in the Developer Dashboard. Always verify the signature before processing the payload.

Python:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

JavaScript:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

Completed Event

{
  "event": "spotcast.forecast.completed",
  "created_at": "2025-12-01T10:30:45Z",
  "data": {
    "spotcast_id": "spc_abc123xyz",
    "forecast_id": "fcst_xyz789",
    "status": "completed",
    "summary": "Excellent conditions expected. Light winds 8-12kt from the NE with calm 1-2ft seas.",
    "metadata": {
      "trip_name": "Weekend Fishing Trip"
    }
  }
}

The summary field is included when AI analysis completes successfully. The metadata object is included when you provided metadata in the original POST /v3/spotcast request, echoed back exactly as sent.

Failed Event

{
  "event": "spotcast.forecast.failed",
  "created_at": "2025-12-01T10:31:00Z",
  "data": {
    "spotcast_id": "spc_abc123xyz",
    "forecast_id": "fcst_xyz789",
    "status": "failed",
    "error": {
      "code": "processing_failed",
      "message": "Unable to fetch weather data for the specified location"
    },
    "metadata": {
      "trip_name": "Weekend Fishing Trip"
    }
  }
}

Retry Policy

Failed deliveries are retried up to 4 times: after 5 minutes, 30 minutes, 2 hours, and 24 hours.

---

Understanding Results

Daily Classifications

Each forecast day receives a safety classification:

Classifications are adjusted based on vessel type and size when vessel_info is provided.

Weather Variables Analyzed

• Wind: Speed (kts), gusts, direction (degrees)
• Waves: Height (ft), period (seconds), direction, swell
• Visibility: Distance (nm), fog probability
• Precipitation: Probability (%), intensity
• Temperature: Air and water (F/C)

Vessel-Specific Adjustments

When vessel_info is provided:

• PWC/Jet Ski: Stricter wave height limits
• Sailboats: Wind optimization recommendations
• Large Yachts: Higher tolerance for wave conditions
• Small Powerboats: Balanced wind/wave thresholds

---

Error Handling

Error Response Format

{
  "error": {
    "code": "invalid_coordinates",
    "message": "Latitude must be between -90 and 90",
    "param": "latitude"
  }
}

HTTP Status Codes

Error Codes

Authentication (401)

Authorization (403)

Payment (402)

Validation (400)

Not Found (404)

Rate Limit (429)

Server (500)

---

Common Workflows

Get a Marine Forecast

1. Create a SpotCast with coordinates and dates
2. Poll the status endpoint until "completed"
3. Retrieve the full forecast with AI analysis
4. Present GO/CAUTION/NO-GO classification to user

Check Conditions Before a Trip

1. Create SpotCast with trip coordinates and date
2. Include vessel_info for tailored recommendations
3. Check daily_classifications for each day
4. Review AI summary for specific concerns

---

Links

• Developer Portal
• API Documentation
• SeaLegs App

License

MIT