Quickstart Guide

Choose Your Integration Path

SeaLegs offers two ways to integrate marine forecasts into your application:

Step 1: Create an Account

First, you'll need a SeaLegs developer account. Sign up at developers.sealegs.ai.

1. Go to the signup page
2. Enter your email and create a password
3. Verify your email address

Step 2: Create an API Key

Once logged in, create your first API key:

1. Go to your Dashboard
2. Click on "API Keys" in the sidebar
3. Click "Create New Key"
4. Give your key a name (e.g., "My First App")
5. Copy your API key and store it securely

Your API key will look like this:

sk_live_c757c4c4a1b2c3d4e5f6g7h8i9j0...

Step 3: Make Your First Request

Now let's create your first SpotCast forecast. A SpotCast provides AI-powered weather forecasts for any marine location.

curl -X POST https://api.sealegs.ai/v3/spotcast \
  -H "Authorization: Bearer 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
  }'

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.sealegs.ai/v3"

# Create the SpotCast
response = requests.post(
    f"{BASE_URL}/spotcast",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "latitude": 25.7617,
        "longitude": -80.1918,
        "start_date": "2025-12-05T00:00:00Z",
        "num_days": 2
    }
)

data = response.json()
spotcast_id = data["id"]
print(f"Created SpotCast: {spotcast_id}")

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.sealegs.ai/v3';

// Create the SpotCast
const response = await fetch(`${BASE_URL}/spotcast`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    latitude: 25.7617,
    longitude: -80.1918,
    start_date: '2025-12-05T00:00:00Z',
    num_days: 2
  })
});

const data = await response.json();
console.log(`Created SpotCast: ${data.id}`);

You'll receive a response like this:

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

Step 4: Get the Results

SpotCasts are processed asynchronously (usually 30-60 seconds). You can poll for the results:

# Check the status
curl https://api.sealegs.ai/v3/spotcast/spc_abc123xyz/status \
  -H "Authorization: Bearer YOUR_API_KEY"

# Once completed, get the full results
curl https://api.sealegs.ai/v3/spotcast/spc_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

# Poll for completion
while True:
    status_response = requests.get(
        f"{BASE_URL}/spotcast/{spotcast_id}/status",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    status = status_response.json()

    if status["status"] == "completed":
        break
    elif status["status"] == "failed":
        raise Exception(f"SpotCast failed: {status.get('error')}")

    print(f"Processing... {status.get('progress', {}).get('percentage', 0)}%")
    time.sleep(5)

# Get the full results
result = requests.get(
    f"{BASE_URL}/spotcast/{spotcast_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()

print(f"Summary: {result['latest_forecast']['ai_analysis']['summary']}")

// Poll for completion
async function waitForCompletion(spotcastId) {
  while (true) {
    const statusResponse = await fetch(
      `${BASE_URL}/spotcast/${spotcastId}/status`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );
    const status = await statusResponse.json();

    if (status.status === 'completed') break;
    if (status.status === 'failed') {
      throw new Error(`SpotCast failed: ${status.error}`);
    }

    console.log(`Processing... ${status.progress?.percentage || 0}%`);
    await new Promise(r => setTimeout(r, 5000));
  }
}

await waitForCompletion(data.id);

// Get the full results
const result = await fetch(
  `${BASE_URL}/spotcast/${data.id}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
).then(r => r.json());

console.log(`Summary: ${result.latest_forecast.ai_analysis.summary}`);

The completed SpotCast includes the AI analysis:

{
  "id": "spc_abc123xyz",
  "status": "completed",
  "coordinates": {
    "latitude": 25.7617,
    "longitude": -80.1918
  },
  "latest_forecast": {
    "forecast_id": "fcst_xyz789",
    "status": "completed",
    "ai_analysis": {
      "summary": "Excellent conditions expected. Light winds 8-12kt from the NE with calm 1-2ft seas. Perfect day for boating.",
      "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%."
        }
      ]
    }
  }
}

Understanding the Response

Daily Classifications

Each day in the forecast receives a classification along with a summary of conditions:

AI Summary

The AI analysis includes a natural language summary of overall conditions and key weather insights.

Next Steps