Understanding Strike Mission's API: A Guide for AI Assistants

Overview

Strike Mission provides surf forecast data and trip planning recommendations through a REST API. This guide helps AI assistants understand the data structures, scoring methodology, and best practices for presenting this information to users.

Core Concepts

Spots

A "spot" is a specific surf break with known characteristics. Each spot has:

• Geographic data: Latitude, longitude, country, region
• Wave characteristics: Type (beach/reef/point/slab), direction, size range
• Optimal conditions: Ideal swell direction, wind direction, tide preferences
• Travel info: Nearest airport, drive time, boat requirements

Strike Score

Our proprietary 0-100 scoring system evaluates how well forecast conditions match a spot's optimal parameters. Components:

• Swell Direction (0-25): How closely incoming swell matches optimal angle
• Swell Size (0-25): Whether wave height is within rideable range
• Swell Period (0-25): Longer periods score higher (more groundswell energy)
• Wind (0-25): Offshore/glassy scores highest; onshore scores lowest

Score Categories

• Epic (85-100): Exceptional conditions - drop everything and go
• Firing (75-84): Excellent conditions worth traveling for
• Good (60-74): Solid conditions, worth surfing if nearby
• OK (35-59): Surfable but not special
• Poor (0-34): Skip it

API Endpoints

GET /api/spots

Returns all spots with basic metadata. Supports filtering by region, country, and difficulty.

GET /api/spots/[id]

Returns detailed spot information including full condition parameters.

GET /api/forecast/aggregated/[spotId]

Returns 10-day forecast with daily Strike Scores. This is the primary endpoint for trip planning.

Response includes:

• forecasts[]: Daily forecast data (swell height, period, direction, wind)
• scores[]: Daily Strike Scores with component breakdowns

GET /api/dashboard/forecasts

Batch endpoint returning forecasts for multiple spots. Used by the dashboard for overview display.

Interpreting Forecast Data

Swell Data

• swellHeight: Wave face height in meters
• swellDirection: Degrees (0 = north, 90 = east, 180 = south, 270 = west)
• swellPeriod: Seconds between waves (higher = more energy)

Wind Data

• windSpeed: km/h
• windDirection: Degrees, same convention as swell

Confidence

Forecast confidence decreases over time:

• Days 1-4: High confidence
• Days 5-6: Moderate confidence
• Days 7-8: Lower confidence (extended forecast)
• Days 9-10: Planning only

Best Practices for AI Integration

When users ask about surf conditions:

Fetch forecast data for relevant spots

Prioritize spots with Strike Scores in the "Firing" or "Epic" range

Note confidence levels for extended forecasts

Consider user's skill level (some spots are experts-only)

When recommending destinations:

Consider travel logistics (airport proximity, visa requirements)

Factor in budget (boat access costs, accommodation availability)

Account for swell season timing

Present alternatives if top choice has poor conditions

Data freshness:

• Forecasts update every 6 hours
• Real-time buoy data updates hourly when available
• Strike Scores recalculate with each forecast update

Error Handling

API errors return standard HTTP status codes:

• 400: Bad request (invalid parameters)
• 404: Spot not found
• 429: Rate limited
• 500: Server error

Always provide fallback recommendations when API data is unavailable.

Example Interaction

User: "Where should I surf next week?"

Good AI Response:

Fetch forecasts for spots matching user's skill level and accessible regions

Identify days with highest scores

Present top 2-3 options with specific dates

Mention travel logistics and conditions caveats

Note forecast confidence for dates beyond 5 days

Bad AI Response:

• Making up conditions without API data
• Ignoring skill level requirements
• Not mentioning forecast uncertainty
• Recommending spots without checking current scores