SurfMap API console

Loading your console.

Invite only for now

The console works once your email is on the invite list. Not on it yet? Email us with a line about what you are building, and we will set you up.

contact@surf-map.com

See the plans

Limits follow your plan: Developer is 1 key, 50 requests a day and a 3-day forecast and tides for 60 days; Starter is 2 keys and 500 a day with the full 7 days; Growth and Pro go up from there.

Checking your access…

Confirm your email

Open the link we emailed to , then come back here. Nothing in your inbox? We can send it again.

Access is by invite

Your account is ready, but it is not on the list yet. Email us from this address with a line about what you are building: we read every message and we will set you up.

contact@surf-map.com

See the plans

Dashboard

Signed in as

Plan

…

Requests today

…

Active keys

…

Forecast horizon

…

Quick start

Four ways in. Swap in your key and go.

curl

curl -H "X-API-Key: sm_live_your_key" \
  "https://api.surf-map.com/v1/spots?q=hossegor"

terminal

npm install @surfmap/sdk

quickstart.ts

import { SurfMap } from '@surfmap/sdk';
const surfmap = new SurfMap({ apiKey: process.env.SURFMAP_API_KEY });
const forecast = await surfmap.forecast.get('la-graviere');

.mcp.json

{
  "mcpServers": {
    "surfmap": {
      "type": "http",
      "url": "https://api.surf-map.com/mcp",
      "headers": { "X-API-Key": "sm_live_your_key" }
    }
  }
}

API reference OpenAPI spec llms.txt @surfmap/sdk on npm

Keys

Name each key after the thing it powers.

Create a key

Your new key · shown once

Save it now. You will not see the full key again, only its prefix.

Your keys

Loading your keys…

API reference

Surf spot database, 7-day hourly forecasts rated 1 to 5 for beginner, intermediate and advanced surfers, and tide extremes for 5,877 named surf spots. JSON over HTTPS, metric units, UTC times. Weather inputs include Open-Meteo data (CC BY 4.0).

Basics

Base URL: https://api.surf-map.com
Auth: X-API-Key: sm_live_… or Authorization: Bearer sm_live_… on every /v1 and /mcp request.
Rate limits: X-RateLimit-Limit, X-RateLimit-Remaining (daily), X-RateLimit-Reset (next UTC midnight, ISO 8601). Sent on every authenticated /v1 and /mcp response. Per-minute burst by plan: Developer 10, Starter 60, Growth 120, Pro 300. Over it you get a 429 with Retry-After.
Horizon: Horizon in days, 1 to 7 (default 7); anything else is a 400 invalid_request. Above your plan's horizon (3 on Developer) the value is clamped to the horizon, not rejected.
Freshness: Forecasts refresh about twice a day. Every forecast and tides response carries aCache-Control max-age and an updatedAt: honor them, cache on your own server for at most 24 hours, and never store or redistribute the data beyond that.
Units: Metric everywhere: meters, seconds, km/h, Celsius. Times are ISO 8601 in UTC.
Errors: Every error body is { "error": { "code", "message" } }. Codes: invalid_key, account_disabled, not_found, no_forecast, rate_limited, invalid_request, internal.
MCP: POST https://api.surf-map.com/mcp with the same key in X-API-Key. Tools: search_spots(query, limit?), spots_nearby(lat, lng, radius_km?, limit?), get_forecast(spot_id, days?), get_tides(spot_id, days?). Tool calls count toward the same quota.

GET/v1/spots

Search spots by name, alias, or country

Case- and diacritic-insensitive search. q is required (at least 2 characters); there is no unfiltered listing. Returns a bare JSON array.

Parameters

Name	In	Type	Notes
`q`required	query	string, at least 2 chars	Example: `hossegor`
`limit`	query	integer, 1..50, default 10

Response

200 Matching spots, best match first. Body: Array of Spot.

Field	Type	Notes
`id`	string	Stable slug id, e.g. anchor-point.
`name`	string	The local name of the spot.
`aka`	string	International nickname when name is the local endonym (Punta Elena, aka Rocky Point). Only present when the catalog has one; search matches it too.
`country`	string	First segment of the spot's country string.
`region`	string \| null	Remaining segments, or null.
`lat`	number
`lng`	number

Errors

400 Invalid parameters.
401 Missing, unknown, or revoked API key (code invalid_key), or a key whose account is disabled or whose 60-day Developer access has ended (code account_disabled, the message gives the end date).
429 Daily quota or per-minute burst exceeded. Retry-After header is set.

curl

curl -H "X-API-Key: sm_live_your_key" \
  "https://api.surf-map.com/v1/spots?q=hossegor"

Back to the top of the reference

GET/v1/spots/nearby

Find spots near a coordinate

Spots within radius km of (lat, lng), sorted by distance. Returns a bare JSON array; each result includes distanceKm.

Parameters

Name	In	Type	Notes
`lat`required	query	number, -90..90
`lng`required	query	number, -180..180
`radius`	query	number, 0..100, default 50	Radius in km.
`limit`	query	integer, 1..50, default 10

Response

200 Nearby spots, closest first. Body: Array of SpotWithDistance.

Field	Type	Notes
`id`	string	Stable slug id, e.g. anchor-point.
`name`	string	The local name of the spot.
`aka`	string	International nickname when name is the local endonym (Punta Elena, aka Rocky Point). Only present when the catalog has one; search matches it too.
`country`	string	First segment of the spot's country string.
`region`	string \| null	Remaining segments, or null.
`lat`	number
`lng`	number
`distanceKm`	number

Errors

400 Invalid parameters.
401 Missing, unknown, or revoked API key (code invalid_key), or a key whose account is disabled or whose 60-day Developer access has ended (code account_disabled, the message gives the end date).
429 Daily quota or per-minute burst exceeded. Retry-After header is set.

curl

curl -H "X-API-Key: sm_live_your_key" \
  "https://api.surf-map.com/v1/spots/nearby?lat=43.66&lng=-1.44&radius=30"

Back to the top of the reference

GET/v1/spots/{id}

Get one spot

Parameters

Name	In	Type	Notes
`id`required	path	string	Spot slug (e.g. anchor-point) or raw 16-hex id. Example: `anchor-point`

Response

200 The spot. Body: Spot.

Field	Type	Notes
`id`	string	Stable slug id, e.g. anchor-point.
`name`	string	The local name of the spot.
`aka`	string	International nickname when name is the local endonym (Punta Elena, aka Rocky Point). Only present when the catalog has one; search matches it too.
`country`	string	First segment of the spot's country string.
`region`	string \| null	Remaining segments, or null.
`lat`	number
`lng`	number

Errors

401 Missing, unknown, or revoked API key (code invalid_key), or a key whose account is disabled or whose 60-day Developer access has ended (code account_disabled, the message gives the end date).
404 Unknown spot (code not_found).
429 Daily quota or per-minute burst exceeded. Retry-After header is set.

curl

curl -H "X-API-Key: sm_live_your_key" \
  "https://api.surf-map.com/v1/spots/la-graviere"

Back to the top of the reference

GET/v1/spots/{id}/forecast

Hourly forecast with 3-level ratings

Hourly conditions from the current UTC hour forward, refreshed twice a day. waveDirection is the primary swell direction (true wave direction is not persisted). tide is null for tideless spots. Responds 404 with code no_forecast when the spot exists but has no forecast document yet.

Parameters

Name	In	Type	Notes
`id`required	path	string	Spot slug (e.g. anchor-point) or raw 16-hex id. Example: `anchor-point`
`days`	query	integer, 1..7, default 7	Horizon in days, 1 to 7 (default 7); anything else is a 400 invalid_request. Above your plan's horizon (3 on Developer) the value is clamped to the horizon, not rejected.

Response

200 Forecast envelope. Body: ForecastResponse.

Field	Type	Notes
`spot`	object { id, name, country }
`units`	"metric"
`updatedAt`	string (date-time)	When this forecast was last refreshed (about twice a day). Honor the Cache-Control header; cache at most 24 hours, never redistribute.
`attribution`	"Weather inputs include Open-Meteo data (CC BY 4.0)"	SurfMap's own credit for its weather inputs, carried on every response. You are not required to display it.
`hours`	array of ForecastHour
`daily`	array of DailyWeather

Errors

400 Invalid parameters.
401 Missing, unknown, or revoked API key (code invalid_key), or a key whose account is disabled or whose 60-day Developer access has ended (code account_disabled, the message gives the end date).
404 Unknown spot (code not_found), or no forecast yet for a known spot (code no_forecast).
429 Daily quota or per-minute burst exceeded. Retry-After header is set.

curl

curl -H "X-API-Key: sm_live_your_key" \
  "https://api.surf-map.com/v1/spots/la-graviere/forecast?days=3"

Back to the top of the reference

GET/v1/spots/{id}/tides

Tide extremes

Stored tide extremes from now forward. Tideless spots return 200 with an empty extremes array and tideless true.

Parameters

Name	In	Type	Notes
`id`required	path	string	Spot slug (e.g. anchor-point) or raw 16-hex id. Example: `anchor-point`
`days`	query	integer, 1..7, default 7	Horizon in days, 1 to 7 (default 7); anything else is a 400 invalid_request. Above your plan's horizon (3 on Developer) the value is clamped to the horizon, not rejected.

Response

200 Tide extremes envelope. Body: TidesResponse.

Field	Type	Notes
`spot`	object { id, name }
`units`	"metric"
`extremes`	array of TideExtreme
`tideless`	boolean

Errors

400 Invalid parameters.
401 Missing, unknown, or revoked API key (code invalid_key), or a key whose account is disabled or whose 60-day Developer access has ended (code account_disabled, the message gives the end date).
404 Unknown spot (code not_found), or no forecast yet for a known spot (code no_forecast).
429 Daily quota or per-minute burst exceeded. Retry-After header is set.

curl

curl -H "X-API-Key: sm_live_your_key" \
  "https://api.surf-map.com/v1/spots/la-graviere/tides?days=3"

Back to the top of the reference

GET/v1/usage

Usage for the presented key

Daily totals for the last 30 UTC days. Does not count toward the daily quota.

Response

200 Usage series. Body: UsageResponse.

Field	Type	Notes
`plan`	string
`limit`	integer	Daily request limit.
`forecastDays`	integer	Forecast and tide horizon served to this key: 3 on Developer, 7 on paid plans.
`expiresAt`	string (date-time) \| null	When a Developer key stops working: 60 days after the account's first key. null on paid plans, which do not expire.
`today`	integer
`days`	array of UsageDay

Errors

401 Missing, unknown, or revoked API key (code invalid_key), or a key whose account is disabled or whose 60-day Developer access has ended (code account_disabled, the message gives the end date).
429 Daily quota or per-minute burst exceeded. Retry-After header is set.

curl

curl -H "X-API-Key: sm_live_your_key" \
  "https://api.surf-map.com/v1/usage"

Back to the top of the reference

Objects

Every field the API returns, in the shape the SDK types them.

Spot

Field	Type	Notes
`id`required	string	Stable slug id, e.g. anchor-point.
`name`required	string	The local name of the spot.
`aka`	string	International nickname when name is the local endonym (Punta Elena, aka Rocky Point). Only present when the catalog has one; search matches it too.
`country`required	string	First segment of the spot's country string.
`region`required	string \| null	Remaining segments, or null.
`lat`required	number
`lng`required	number

SpotWithDistance

Field	Type	Notes
`id`required	string	Stable slug id, e.g. anchor-point.
`name`required	string	The local name of the spot.
`aka`	string	International nickname when name is the local endonym (Punta Elena, aka Rocky Point). Only present when the catalog has one; search matches it too.
`country`required	string	First segment of the spot's country string.
`region`required	string \| null	Remaining segments, or null.
`lat`required	number
`lng`required	number
`distanceKm`required	number

Rating

1-5 for each level, 5 best.

Field	Type	Notes
`beginner`required	integer, 1..5
`intermediate`required	integer, 1..5
`advanced`required	integer, 1..5

Tide

Field	Type	Notes
`height`required	number	Meters.
`state`required	"rising" \| "falling"

ForecastHour

Field	Type	Notes
`time`required	string (date-time)	UTC, e.g. 2026-08-09T08:00:00Z.
`waveHeight`required	number	Combined significant wave height, meters.
`swellHeight`required	number	Meters.
`wavePeriod`required	number	Seconds.
`waveDirection`required	integer	Primary swell direction, degrees.
`windSpeed`required	number	km/h.
`windDirection`required	integer	Degrees.
`windGust`required	number	km/h.
`windDirectionType`required	"offshore" \| "onshore" \| "cross" \| null
`airTemperature`required	number	Celsius.
`waterTemperature`required	number	Celsius.
`weatherCode`required	integer	WMO weather code.
`tide`required	Tide \| null
`rating`required	Rating	1-5 for each level, 5 best.

DailyWeather

Field	Type	Notes
`date`required	string (date)
`sunrise`required	string (date-time) \| null
`sunset`required	string (date-time) \| null
`uvIndexMax`required	number

ForecastResponse

Field	Type	Notes
`spot`required	object { id, name, country }
`units`required	"metric"
`updatedAt`required	string (date-time)	When this forecast was last refreshed (about twice a day). Honor the Cache-Control header; cache at most 24 hours, never redistribute.
`attribution`required	"Weather inputs include Open-Meteo data (CC BY 4.0)"	SurfMap's own credit for its weather inputs, carried on every response. You are not required to display it.
`hours`required	array of ForecastHour
`daily`required	array of DailyWeather

TideExtreme

Field	Type	Notes
`type`required	"high" \| "low"
`time`required	string (date-time)
`height`required	number	Meters.

TidesResponse

Field	Type	Notes
`spot`required	object { id, name }
`units`required	"metric"
`extremes`required	array of TideExtreme
`tideless`required	boolean

UsageDay

Field	Type	Notes
`date`required	string (date)
`total`required	integer
`byEndpoint`required	object of integer	Request counts keyed by spots.search, spots.nearby, spots.get, forecast, tides, mcp.<tool>.

UsageResponse

Field	Type	Notes
`plan`required	string
`limit`required	integer	Daily request limit.
`forecastDays`required	integer	Forecast and tide horizon served to this key: 3 on Developer, 7 on paid plans.
`expiresAt`	string (date-time) \| null	When a Developer key stops working: 60 days after the account's first key. null on paid plans, which do not expire.
`today`required	integer
`days`required	array of UsageDay

Error

Field	Type	Notes
`error`required	object { code, message }	code is one of "invalid_key", "account_disabled", "not_found", "no_forecast", "rate_limited", "invalid_request", "internal".

Your SurfMap API console

Confirm your email

Access is by invite

Dashboard

Your Developer access has ended

Create your first key

Quick start

Keys

Create a key

Your keys

Usage

Last 30 days

By endpoint

API reference

Basics

Search spots by name, alias, or country

Parameters

Response

Errors

Find spots near a coordinate

Parameters

Response

Errors

Get one spot

Parameters

Response

Errors

Hourly forecast with 3-level ratings

Parameters

Response

Errors

Tide extremes

Parameters

Response

Errors

Usage for the presented key

Response

Errors

Objects

Spot

SpotWithDistance

Rating

Tide

ForecastHour

DailyWeather

ForecastResponse

TideExtreme

TidesResponse

UsageDay

UsageResponse

Error

Account

Your account

Change plan

Security