SeaLegs AI Marine Forecast API

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

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

| Operation | Endpoint | Cost | |-----------|----------|------| | Create forecast | POST /v3/spotcast | 1 credit/day | | Get forecast | GET /v3/spotcast/{id} | Free | | Check status | GET /v3/spotcast/{id}/status | Free | | Refresh forecast | POST /v3/spotcast/{id}/refresh | 1 credit/day | | List forecasts for SpotCast | GET /v3/spotcast/{id}/forecasts | Free | | Get specific forecast | GET /v3/spotcast/{id}/forecast/{forecast_id} | Free | | List SpotCasts | GET /v3/spotcasts | Free | | Get balance | GET /v3/account/balance | Free |

Weather Factors Used

Authentication

All requests require:

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

Rate Limits

Billing

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:

Optional parameters:

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:

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

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:

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:

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:

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:

| Classification | Meaning | |----------------|---------| | GO | Safe conditions for the vessel type | | CAUTION | Proceed with awareness; conditions may be challenging | | NO-GO | Conditions not recommended for the vessel type |

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

Weather Variables Analyzed

Vessel-Specific Adjustments

When vessel_info is provided:

Error Handling

Error Response Format

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

HTTP Status Codes

| Code | Meaning | Action | |------|---------|--------| | 200 | Success | Request completed | | 201 | Created | Resource created | | 202 | Accepted | Async processing started | | 400 | Bad Request | Check parameter values | | 401 | Unauthorized | Verify API key is correct | | 402 | Payment Required | Add credits at developer.sealegs.ai | | 403 | Forbidden | Account not verified or suspended | | 404 | Not Found | Check resource ID | | 429 | Rate Limited | Wait and retry (60 req/min limit) | | 500 | Server Error | Retry after brief delay |

Error Codes

Authentication (401)

| Code | Description | |------|-------------| | missing_api_key | No API key provided in request | | invalid_api_key | API key is not recognized | | key_revoked | API key has been revoked |

Authorization (403)

| Code | Description | |------|-------------| | account_not_verified | Developer account has not been verified | | account_suspended | Developer account has been suspended |

Payment (402)

| Code | Description | |------|-------------| | insufficient_balance | Not enough credits (response includes current_balance, required_credits, purchase_url) |

Validation (400)

| Code | Description | |------|-------------| | invalid_coordinates | Coordinates out of valid range | | invalid_date_format | Not ISO 8601 format | | invalid_webhook_url | Not a valid HTTPS URL | | invalid_preferences | Preferences format is invalid | | invalid_language | Language not supported (use: en, es, fr, pt, it, ja) | | invalid_distance_units | Distance units not supported (use: nm, mi, km) | | invalid_speed_units | Speed units not supported (use: kts, mph, ms) | | invalid_json | Request body is not valid JSON |

Not Found (404)

| Code | Description | |------|-------------| | spotcast_not_found | The specified SpotCast does not exist | | forecast_not_found | The specified forecast does not exist |

Rate Limit (429)

| Code | Description | |------|-------------| | rate_limit_exceeded | Too many requests (response includes retry_after seconds) |

Server (500)

| Code | Description | |------|-------------| | internal_error | An unexpected error occurred | | creation_failed | Failed to create SpotCast | | retrieval_failed | Failed to retrieve resource |

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

License

MIT

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