The SpotCast API is the core of the SeaLegs platform. It takes a set of coordinates, a date range, and optional context about your vessel, and returns an AI-analyzed marine weather forecast with daily classifications and a natural language summary. No weather models to parse, no data to interpret — the API does the heavy lifting.
In this post, we'll walk through the full lifecycle of working with the SpotCast API: creating a forecast, handling the async response, reading the results, customizing for different vessels and trip durations, and building up a forecast history for a location.
The Basics: Creating a SpotCast
At its simplest, a SpotCast needs four things: latitude, longitude, a start date, and how many days to forecast (1–5). We'll use South Florida coordinates here, but this works for any location worldwide:
curl -X POST https://api.sealegs.ai/v3/spotcast \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"latitude": 25.954,
"longitude": -79.743,
"start_date": "2026-01-28",
"num_days": 3
}'This returns immediately with a SpotCast ID and a pending status:
{
"id": "spc_abc123...",
"status": "pending",
"coordinates": {
"latitude": 25.954,
"longitude": -79.743
},
"forecast_period": {
"start_date": "2026-01-28",
"end_date": "2026-01-30",
"num_days": 3
},
"created_at": "2026-01-28T14:30:00Z"
}The forecast doesn't come back inline because there's real work happening behind the scenes: fetching data from multiple weather models, running the analysis, and generating the AI summary. This typically takes a few seconds.
Handling Async Processing
You have two options for getting the completed forecast: polling or webhooks.
Option 1: Poll the Status Endpoint
The simplest approach. Hit the status endpoint until the forecast is ready:
GET /v3/spotcast/spc_abc123/status
# Response while processing:
{
"status": "processing",
"progress": {
"stage": "ai_analysis",
"percentage": 75
}
}
# Response when done:
{
"status": "completed",
"forecast_id": "fcst_xyz789..."
}The progress object tells you where things stand. The stages are: pending → fetching_weather → processing_data → ai_analysis → completed. In practice, the whole pipeline finishes in a few seconds, so a simple poll with a 1-second interval works well.
Option 2: Webhooks
For production systems, webhooks are cleaner. Include a webhook_url when you create the SpotCast, and we'll POST the result to your server when it's ready:
curl -X POST https://api.sealegs.ai/v3/spotcast \
-H "X-API-Key: your_api_key" \
-d '{
"latitude": 25.954,
"longitude": -79.743,
"start_date": "2026-01-28",
"num_days": 3,
"webhook_url": "https://yourapp.com/api/forecast-ready"
}'The webhook payload includes the SpotCast ID, forecast ID, summary, and any metadata you attached. See the webhook docs for the full payload format and security verification.
Reading the Forecast
Once the status is completed, fetch the full forecast:
GET /v3/spotcast/spc_abc123The response contains two key pieces:
The Summary
A natural language overview of the entire forecast period. This is what you'd show to an end user who just wants to know "should I go out this weekend?":
"summary": "The three-day period shows progressively favorable
conditions for recreational boating. Wednesday starts rough
but improves significantly by evening. Thursday and Friday
offer excellent all-day conditions with light winds (7-12kt)
and manageable seas (1.8-2.8ft). High forecast confidence
(95%) for Thursday and Friday ensures reliable planning."Daily Classifications
Each day gets a classification — GO, CAUTION, or AVOID — along with a detailed breakdown:
"daily_classifications": [
{
"date": "2026-01-28",
"classification": "CAUTION",
"summary": "Winds 15-20kt from the NE with gusts to 25kt
in the morning, easing to 10-15kt by afternoon. Seas
4-5ft with 6-second period. Conditions improve through
the day but morning departure not recommended."
},
{
"date": "2026-01-29",
"classification": "GO",
"summary": "Light winds 7-10kt from the E. Seas 1.5-2ft
with 5-second period. Excellent conditions all day.
Forecast confidence 95%."
},
{
"date": "2026-01-30",
"classification": "GO",
"summary": "Winds 8-12kt from the SE. Seas 2-2.8ft with
4-second period. Good conditions throughout. Slight
increase in afternoon chop."
}
]The classifications factor in wind speed, gusts, wave height, swell, visibility, and precipitation. They're designed to be directly usable in a UI — map them to green/yellow/red and you've got an instant conditions indicator.
Customizing for Vessel Type
The default classifications work for a typical recreational powerboat. But a 45-foot yacht handles 4-foot seas very differently than a jet ski does. The vessel_info parameter adjusts the AI analysis to match:
{
"latitude": 25.954,
"longitude": -79.743,
"start_date": "2026-01-28",
"num_days": 3,
"vessel_info": {
"type": "sailboat",
"length_ft": 38
}
}Supported vessel types:
powerBoat— standard recreational powerboatsailboat— wind is weighted more favorably, wave tolerance adjustedpwc— personal watercraft, tighter safety thresholdsyacht— larger vessel, more tolerant of rough conditionscatamaran— stability-focused analysis
The length_ft further refines the thresholds. A 20-foot center console and a 50-foot sportfisher will get different GO/CAUTION/AVOID classifications for the same weather conditions.
Trip Duration: Finding the Best Window
The trip_duration_hours parameter tells the AI how long your user plans to be on the water (1–48 hours). The API uses this to evaluate rolling windows within the forecast period and identify the best time slots:
{
"latitude": 25.954,
"longitude": -79.743,
"start_date": "2026-01-28",
"num_days": 2,
"trip_duration_hours": 6,
"vessel_info": {
"type": "powerBoat",
"length_ft": 24
}
}Instead of just saying "Wednesday is CAUTION," the analysis can tell your users that the best 6-hour window on Wednesday starts at 1 PM when winds drop to 10 knots. This is much more actionable than a full-day classification alone.
Attaching Metadata
The metadata field lets you store arbitrary key-value data with a SpotCast. It gets saved with the forecast and echoed back in API responses and webhooks:
{
"latitude": 26.101,
"longitude": -80.108,
"start_date": "2026-01-28",
"num_days": 3,
"metadata": {
"user_id": "usr_456",
"location_name": "Fort Lauderdale Inlet",
"trip_id": "trip_789"
}
}This is useful for routing webhook notifications to the right user, labeling forecasts in your database, or linking SpotCast results back to entities in your own system. You don't need to maintain a separate mapping — the context travels with the forecast.
Building Forecast History
Every time you create or refresh a SpotCast for the same location, a new forecast is added to the history. You can retrieve past forecasts for any SpotCast:
# List all forecasts for a SpotCast
GET /v3/spotcast/spc_abc123/forecasts
# Get a specific historical forecast
GET /v3/spotcast/spc_abc123/forecast/fcst_xyz789This is valuable for building features like:
- Trend analysis — how did the forecast evolve as the date approached?
- Accuracy tracking — compare forecasts against actual observed conditions
- User history — show users past forecasts for their favorite locations
To update an existing SpotCast with the latest weather data, use the refresh endpoint instead of creating a new one:
POST /v3/spotcast/spc_abc123/refreshThis costs the same as a new forecast (1 credit per day) but keeps the forecast linked to the same SpotCast ID and location history.
Multi-Language Summaries
The AI-generated summaries support six languages. Set the language preference and the summary and daily classification text come back localized:
{
"latitude": 43.296,
"longitude": 5.369,
"start_date": "2026-01-28",
"num_days": 3,
"preferences": {
"language": "fr",
"distance_units": "km",
"speed_units": "kts"
}
}Supported languages: English (en), Spanish (es), French (fr), Portuguese (pt), Italian (it), and Japanese (ja). This is especially useful for international regions like the Mediterranean. The units preferences (distance_units and speed_units) also affect the values used in the summary text.
Cost and Rate Limits
A few practical details:
- Cost: 1 credit per forecast-day. A 3-day SpotCast costs 3 credits. Retrieving forecasts and checking status are free.
- Rate limit: 60 requests per minute across all endpoints.
- Credits: Start at $10 for 200 forecast-days, or $20 for 500.
- Free operations: GET requests for existing forecasts, status checks, and listing SpotCasts don't cost credits.
Tip: Use the GET /v3/account/balance endpoint to check your remaining credits programmatically. Build this into your app to warn users or auto-purchase before credits run out.
Putting It All Together
Here's a complete example in Python that creates a SpotCast, polls for the result, and prints the forecast:
import requests
import time
API_KEY = "your_api_key"
BASE_URL = "https://api.sealegs.ai/v3"
headers = {"X-API-Key": API_KEY}
# 1. Create the SpotCast
response = requests.post(f"{BASE_URL}/spotcast", headers=headers, json={
"latitude": 25.954,
"longitude": -79.743,
"start_date": "2026-01-28",
"num_days": 3,
"trip_duration_hours": 6,
"vessel_info": {"type": "sailboat", "length_ft": 35}
})
spotcast = response.json()
spotcast_id = spotcast["id"]
print(f"Created SpotCast: {spotcast_id}")
# 2. Poll for completion
while True:
status = requests.get(
f"{BASE_URL}/spotcast/{spotcast_id}/status",
headers=headers
).json()
if status["status"] == "completed":
break
print(f"Processing... {status['progress']['stage']}")
time.sleep(1)
# 3. Fetch the full forecast
forecast = requests.get(
f"{BASE_URL}/spotcast/{spotcast_id}",
headers=headers
).json()
print(f"\n{forecast['summary']}\n")
for day in forecast["daily_classifications"]:
print(f"{day['date']}: {day['classification']}")
print(f" {day['summary']}\n")From here, you can map the classifications to your UI, pipe the summary into a notification, or store the result for historical analysis. The full SpotCast documentation covers every parameter and response field in detail.
Ready to get started? Create your free developer account and make your first SpotCast in minutes.