SpotCast API

Create AI-powered marine forecasts for any spot in the world

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)
trip_duration_hours integer Optional Expected trip duration in hours. Used to tailor the AI analysis to your planned time on the water.

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.

Insufficient Credits

Returns 402 with error code insufficient_balance if your account does not have enough credits.

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",
  "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"
  }
}

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
  },
  "trip_duration_hours": 8,
  "forecast_count": 1,
  "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%."
        }
      ]
    }
  }
}

Response (200 OK - Processing)

When the SpotCast is still being processed, the latest_forecast includes a progress object instead of ai_analysis:

{
  "id": "spc_abc123xyz",
  "status": "processing",
  "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": 8,
  "forecast_count": 1,
  "latest_forecast": {
    "forecast_id": "fcst_xyz789",
    "status": "processing",
    "created_at": "2025-12-01T10:30:00Z",
    "progress": {
      "stage": "ai_analysis",
      "percentage": 75
    }
  }
}

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. Returns 402 with error code insufficient_balance if your account does not have enough 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 Forecasts

GET /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. Use this endpoint to retrieve the history of forecasts.

Path Parameters

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

Query Parameters

Parameter Type Description
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 sk_live_your_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
}

Errors

Status Code Description
404 spotcast_not_found SpotCast does not exist or does not belong to your account

Get Forecast

GET /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.

Path Parameters

Parameter Type Description
id required string The SpotCast ID (e.g. spc_abc123xyz)
forecast_id required string The forecast ID (e.g. fcst_xyz789)

Example Request

curl "https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/forecast/fcst_xyz789" \
 -H "Authorization: Bearer sk_live_your_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)

When the forecast is still being processed, a progress object is returned instead of ai_analysis:

{
  "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)

If the forecast failed to process, an error field is returned:

{
  "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"
}

Errors

Status Code Description
404 forecast_not_found Forecast does not exist, does not belong to your account, or does not belong to the specified SpotCast

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

For a practical walkthrough, see Building with the SpotCast API.