SpotCast API

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)

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)

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

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

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%."
        }
      ]
    }
  }
}

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 the forecast for an existing SpotCast with updated weather data.

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

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