SpotCast API - SeaLegs Developer API

Overview

A SpotCast is a marine weather forecast for a specific location. It includes:

N-day forecasts (1-5 days)
Summary of conditions across all forecast days
Summary of conditions for each day
Key weather insights (wind, waves, precipitation, visibility)

Credit Usage

SpotCasts are billed at 1 credit per forecast day. A 3-day forecast costs 3 credits, a 5-day forecast costs 5 credits.

Async Processing

SpotCasts are processed asynchronously. After creating a SpotCast, poll the status endpoint or use webhooks to know when it's complete.

Create SpotCast

POST /v3/spotcast

Creates a new SpotCast forecast for the specified location and date range.

Request Body

Parameter	Type	Required	Description
latitude	number	Required	Latitude (-90 to 90)
longitude	number	Required	Longitude (-180 to 180)
start_date	string	Required	Start date (ISO 8601)
num_days	integer	Required	Number of days for the forecast (1-5)
webhook_url	string	Optional	URL to receive completion webhook (HTTPS only)
metadata	object	Optional	Custom metadata to store with the SpotCast
preferences	object	Optional	Localization preferences (see below)
vessel_info	object	Optional	Vessel information for customized analysis (see below)

Preferences Object

Parameter	Type	Default	Description
language	string	`en`	Language for AI analysis: `en`, `es`, `fr`, `pt`, `it`, `ja`
distance_units	string	`nm`	Distance units: `nm` (nautical miles), `mi` (miles), `km` (kilometers)
speed_units	string	`kts`	Speed units: `kts` (knots), `mph`, `ms` (meters/second)

Vessel Info Object

When provided, the AI analysis will be customized for your specific vessel type and size, adjusting safety thresholds and recommendations accordingly.

Parameter	Type	Required	Description
type	string	Required	Vessel type: `powerBoat`, `sailboat`, `pwc`, `yacht`, `catamaran`
length_ft	number	Required	Vessel length in feet (1-500)

Vessel-Specific Analysis

When vessel info is provided, the AI adjusts its analysis based on vessel characteristics. For example, sailboats get wind-optimized recommendations, while PWCs receive stricter wave height thresholds. Larger vessels generally have more lenient limits than smaller ones.

Example Request

curl -X POST https://api.sealegs.ai/v3/spotcast \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 25.7617,
    "longitude": -80.1918,
    "start_date": "2025-12-05T00:00:00Z",
    "num_days": 2,
    "webhook_url": "https://your-server.com/webhook",
    "metadata": {
      "trip_name": "Weekend Fishing Trip"
    },
    "preferences": {
      "language": "en",
      "distance_units": "nm",
      "speed_units": "kts"
    },
    "vessel_info": {
      "type": "sailboat",
      "length_ft": 35
    }
  }'

Response (202 Accepted)

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

Get SpotCast

GET /v3/spotcast/{id}

Retrieves a SpotCast with its latest forecast and AI analysis.

Path Parameters

Parameter	Type	Description
id	string	SpotCast ID (e.g., spc_abc123xyz)

Example Request

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

Response (200 OK - Completed)

{
  "id": "spc_abc123xyz",
  "status": "completed",
  "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
  },
  "metadata": {
    "trip_name": "Weekend Fishing Trip"
  },
  "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": "Excellent conditions throughout most of the day with best windows from midnight to 4:00 PM. Light 7-9kt west-southwest winds and well-organized 2.4-2.6ft seas at comfortable 7-second periods from the southeast (period/height ratio ~2.9 = excellent) dominate the first 16 hours. Conditions deteriorate in late afternoon/evening after 5:00 PM with increasing 12-14kt west-northwest winds and building 2.6-3.5ft seas at shorter 4-6 second periods from the south-southwest (ratio drops to ~1.1-1.7 = fair to rough). Plan activities before 4:00 PM for optimal comfort. Moderate forecast confidence at 82% with some wave period disagreement between models."
        },
        {
          "date": "2025-12-06",
          "classification": "CAUTION",
          "summary": "Improving conditions throughout the day with best windows in the afternoon and evening. Morning starts rough with 12-14kt northwest winds and choppy 3.5-4.1ft seas at short 4-second periods from the northeast (period/height ratio ~1.0 = rough). Conditions improve significantly after 1:00 PM with 8-11kt northwest winds and more organized 3.5-4.0ft seas at comfortable 6-7 second periods from the east-southeast (ratio ~1.7-2.0 = fair to good). Evening hours 7:00 PM-11:00 PM are excellent with light 4-7kt west-northwest winds and well-organized 2.6-3.0ft seas at 7-second periods from the southeast (ratio ~2.3-2.7 = good). High forecast confidence at 91%."
        }
      ]
    }
  }
}

Get SpotCast Status

GET /v3/spotcast/{id}/status

Gets the current processing status of a SpotCast. Use this for polling.

Example Request

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

Response

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

Status Values

Status	Description
`pending`	Request received, waiting to process
`processing`	Currently being processed
`completed`	Successfully completed
`failed`	Processing failed

Progress Stages

Stage	Percentage
`pending`	0%
`fetching_weather`	25%
`processing_data`	50%
`ai_analysis`	75%
`completed`	100%

Refresh SpotCast

POST /v3/spotcast/{id}/refresh

Refresh the forecast for an existing SpotCast with updated weather data.

Credit Cost

Each refresh costs 1 credit per forecast day. A 3-day SpotCast refresh costs 3 credits.

Request Body (Optional)

Parameter	Type	Description
webhook_url	string	Override webhook URL for this refresh

Example Request

curl -X POST https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/refresh \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json"

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 SpotCasts

GET /v3/spotcasts

Lists all SpotCasts for your account, sorted by creation date (newest first).

Query Parameters

Parameter	Type	Description
limit	integer	Number of results (default: 20, max: 100)
after	string	Cursor for pagination

Example Request

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

Response

{
  "data": [
    {
      "id": "spc_abc123xyz",
      "status": "completed",
      "created_at": "2025-12-01T10:30:00Z",
      "coordinates": {
        "latitude": 25.7617,
        "longitude": -80.1918
      },
      "latest_forecast": {
        "forecast_id": "fcst_xyz789",
        "status": "completed"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "spc_def456"
}

Understanding AI Analysis

Daily Classifications

Each day in the forecast period receives its own classification and summary, helping you identify the best days for your trip.

Weather Variables

The analysis considers:

Wind: Speed, gusts, direction
Waves: Height, period, direction, swell
Visibility: Fog, precipitation impacts
Precipitation: Rain probability and intensity
Temperature: Air and water temperature

SpotCast Widgets API

Widgets are embeddable SpotCast forecasts that can be added to any website. Widgets automatically refresh based on your configured update frequency.

Credit Usage

Widgets are billed at 1 credit per forecast day on each refresh. A 3-day widget refreshing daily costs 3 credits per day.

Create Widget

POST /v3/spotcast/widgets

Creates a new embeddable SpotCast widget for a specific location.

Request Body

Parameter	Type	Required	Description
name	string	Required	Display name for the widget (max 100 characters)
latitude	number	Required	Latitude (-90 to 90)
longitude	number	Required	Longitude (-180 to 180)
num_days	integer	Optional	Number of forecast days (1-5, default: 3)
update_frequency	string	Optional	Auto-refresh frequency: `never`, `daily`, `twice_daily`, `three_daily`, `four_daily` (default: `daily`)
theme	string	Optional	Widget theme: `light` or `dark` (default: `light`)
vessel_info	object	Optional	Vessel information for customized analysis (see below)

Vessel Info Object

When provided, the AI analysis will be customized for your specific vessel type and size.

Parameter	Type	Required	Description
type	string	Required	Vessel type: `powerBoat`, `sailboat`, `pwc`, `yacht`, `catamaran`
length_ft	number	Required	Vessel length in feet (1-500)

Example Request

curl -X POST https://api.sealegs.ai/v3/spotcast/widgets \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Miami Marina Forecast",
    "latitude": 25.7617,
    "longitude": -80.1918,
    "num_days": 3,
    "update_frequency": "daily",
    "theme": "light",
    "vessel_info": {
      "type": "sailboat",
      "length_ft": 35
    }
  }'

Response (201 Created)

{
  "widget_id": "wgt_abc123xyz",
  "name": "Miami Marina Forecast",
  "status": "active",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "num_days": 3,
  "update_frequency": "daily",
  "theme": "light",
  "vessel_info": {
    "type": "sailboat",
    "length_ft": 35
  },
  "created_at": "2025-12-01T10:30:00Z",
  "embed_code": "<div id=\"sealegs-widget-wgt_abc123xyz\"></div>\n<script src=\"https://cdn.sealegs.ai/spotcast_widget.js\" data-widget-id=\"wgt_abc123xyz\" async></script>"
}

Update Widget

PUT /v3/spotcast/widgets/{id}

Updates an existing widget's configuration. Only include fields you want to change.

Path Parameters

Parameter	Type	Description
id	string	Widget ID (e.g., wgt_abc123xyz)

Request Body

Parameter	Type	Description
name	string	Display name for the widget
latitude	number	Latitude (-90 to 90)
longitude	number	Longitude (-180 to 180)
num_days	integer	Number of forecast days (1-5)
update_frequency	string	Auto-refresh frequency
theme	string	Widget theme: `light` or `dark`
vessel_info	object	Vessel information (type and length_ft)

Example Request

curl -X PUT https://api.sealegs.ai/v3/spotcast/widgets/wgt_abc123xyz \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Marina Name",
    "vessel_info": {
      "type": "yacht",
      "length_ft": 55
    }
  }'

Response (200 OK)

{
  "widget_id": "wgt_abc123xyz",
  "name": "Updated Marina Name",
  "status": "active",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "num_days": 3,
  "update_frequency": "daily",
  "theme": "light",
  "vessel_info": {
    "type": "yacht",
    "length_ft": 55
  },
  "updated_at": "2025-12-01T12:00:00Z"
}

Get Widget

GET /v3/spotcast/widgets/{id}

Retrieves a widget's configuration and current status.

Example Request

curl https://api.sealegs.ai/v3/spotcast/widgets/wgt_abc123xyz \
  -H "Authorization: Bearer sk_live_your_api_key"

Response (200 OK)

{
  "widget_id": "wgt_abc123xyz",
  "name": "Miami Marina Forecast",
  "status": "active",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "num_days": 3,
  "update_frequency": "daily",
  "theme": "light",
  "vessel_info": {
    "type": "sailboat",
    "length_ft": 35
  },
  "current_spotcast_id": "spc_xyz789",
  "last_refresh_at": "2025-12-01T06:00:00Z",
  "next_refresh_at": "2025-12-02T06:00:00Z",
  "total_refreshes": 15,
  "created_at": "2025-11-15T10:30:00Z",
  "embed_code": "<div id=\"sealegs-widget-wgt_abc123xyz\"></div>\n<script src=\"https://cdn.sealegs.ai/spotcast_widget.js\" data-widget-id=\"wgt_abc123xyz\" async></script>"
}

List Widgets

GET /v3/spotcast/widgets

Lists all widgets for your account.

Example Request

curl https://api.sealegs.ai/v3/spotcast/widgets \
  -H "Authorization: Bearer sk_live_your_api_key"

Response (200 OK)

{
  "widgets": [
    {
      "widget_id": "wgt_abc123xyz",
      "name": "Miami Marina Forecast",
      "status": "active",
      "coordinates": {
        "latitude": 25.7617,
        "longitude": -80.1918
      },
      "num_days": 3,
      "update_frequency": "daily",
      "vessel_info": {
        "type": "sailboat",
        "length_ft": 35
      },
      "last_refresh_at": "2025-12-01T06:00:00Z"
    }
  ],
  "total_count": 1
}

Delete Widget

DELETE /v3/spotcast/widgets/{id}

Deletes a widget. This stops all scheduled refreshes and removes the widget.

Example Request

curl -X DELETE https://api.sealegs.ai/v3/spotcast/widgets/wgt_abc123xyz \
  -H "Authorization: Bearer sk_live_your_api_key"

Response (200 OK)

{
  "message": "Widget deleted successfully",
  "widget_id": "wgt_abc123xyz"
}

Refresh Widget

POST /v3/spotcast/widgets/{id}/refresh

Manually triggers a forecast refresh for a widget outside of its scheduled update frequency.

Credit Cost

Each refresh costs 1 credit per forecast day.

Example Request

curl -X POST https://api.sealegs.ai/v3/spotcast/widgets/wgt_abc123xyz/refresh \
  -H "Authorization: Bearer sk_live_your_api_key"

Response (202 Accepted)

{
  "widget_id": "wgt_abc123xyz",
  "spotcast_id": "spc_newxyz789",
  "status": "processing",
  "message": "Widget refresh initiated"
}

Embedding SpotCast Widgets

SpotCast widgets can be embedded on any website using a simple script tag. The embed code is available in your dashboard.

Basic Embed Code

<!-- SeaLegs SpotCast Widget -->
<div id="sealegs-widget-YOUR_WIDGET_ID"></div>
<script src="https://cdn.sealegs.ai/spotcast_widget.js"
        data-widget-id="YOUR_WIDGET_ID"
        data-type="mini"
        async></script>

Content Security Policy (CSP)

Most websites don't use CSP and the widget will work without any configuration. However, if your site has a Content Security Policy, you'll need to add the following directives:

Required CSP Directives

Add these to your existing Content-Security-Policy header or meta tag:

Directive	Required Value	Purpose
`script-src`	`https://cdn.sealegs.ai`	Load the widget script
`connect-src`	`https://cdn.sealegs.ai`	Fetch forecast data
`media-src`	`https://cdn.sealegs.ai`	Play audio narration (if enabled)
`style-src`	`'unsafe-inline'`	Widget styling
`img-src`	`https://www.sealegs.ai`	SeaLegs logo

Example CSP Meta Tag

<meta http-equiv="Content-Security-Policy" content="
  default-src 'self';
  script-src 'self' https://cdn.sealegs.ai;
  connect-src 'self' https://cdn.sealegs.ai;
  media-src 'self' https://cdn.sealegs.ai;
  style-src 'self' 'unsafe-inline';
  img-src 'self' https://www.sealegs.ai;
">

How to Check if Your Site Uses CSP

Open your browser's Developer Tools (F12)
Go to the Network tab and reload the page
Click on your HTML document in the list
Look in Response Headers for Content-Security-Policy
Or check your HTML source for <meta http-equiv="Content-Security-Policy">

Troubleshooting

If the widget shows "Blocked by Security Policy", check your browser console for specific CSP violation messages. They will indicate which directive needs to be updated.