# SurfMap API

Surf spot database, hourly surf forecasts rated 1 to 5 for beginner, intermediate
and advanced surfers, and tide extremes. 5,877 named spots worldwide. JSON over
HTTPS. Metric units (meters, km/h, Celsius). All times UTC ISO 8601. Forecasts
refresh twice a day, 7-day hourly horizon.

Base URL: https://api.surf-map.com
OpenAPI spec: https://api.surf-map.com/openapi.json
MCP server (Streamable HTTP): https://api.surf-map.com/mcp
Developer console (create your key): https://surf-map.com/api/console/
  Early access is invite based. Write to contact@surf-map.com for an invite.
TypeScript SDK: npm install @surfmap/sdk
Product page: https://surf-map.com/api/
Contact: contact@surf-map.com

## Authentication

Send your API key on every /v1 and /mcp request, either way:

  X-API-Key: sm_live_...
  Authorization: Bearer sm_live_...

Early access keys allow 500 requests per day with a burst of 60 per minute.
Every /v1 response carries X-RateLimit-Limit, X-RateLimit-Remaining and
X-RateLimit-Reset (next UTC midnight).

## Endpoints (GET, versioned under /v1)

/v1/spots?q=<text>&limit=<1..50>
  Search by name, alias or country. q required, 2+ characters. Returns a JSON
  array of spots: {id, name, country, region, lat, lng}. Spot ids are stable
  slugs like anchor-point; raw 16-hex ids are also accepted everywhere.

/v1/spots/nearby?lat=&lng=&radius=<km, max 100>&limit=<1..50>
  Spots around a coordinate, closest first, each with distanceKm.

/v1/spots/{id}
  One spot by slug or 16-hex id.

/v1/spots/{id}/forecast?days=<1..7>
  Hourly forecast from the current UTC hour: waveHeight, swellHeight,
  wavePeriod, waveDirection (primary swell direction), windSpeed,
  windDirection, windGust, windDirectionType (offshore|onshore|cross),
  airTemperature, waterTemperature, weatherCode (WMO), tide {height, state}
  (null for tideless spots), rating {beginner, intermediate, advanced} as
  integers 1 to 5, 5 best. Plus daily sunrise/sunset/uvIndexMax.

/v1/spots/{id}/tides?days=<1..7>
  Tide extremes: {type: high|low, time, height in meters}. Tideless spots
  return 200 with an empty extremes array and tideless: true.

/v1/usage
  Your key's last 30 days: {plan, limit, today, days: [{date, total, byEndpoint}]}.

Errors use {"error": {"code", "message"}} with codes invalid_key, not_found,
no_forecast, rate_limited, invalid_request, internal.

## Examples

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

  curl -H "X-API-Key: $SURFMAP_API_KEY" \
    "https://api.surf-map.com/v1/spots/anchor-point/forecast?days=3"

  curl -H "X-API-Key: $SURFMAP_API_KEY" \
    "https://api.surf-map.com/v1/spots/nearby?lat=43.67&lng=-1.44&radius=25"

  curl -H "X-API-Key: $SURFMAP_API_KEY" \
    "https://api.surf-map.com/v1/spots/supertubos/tides"

## MCP

Point Claude Code, Cursor or any MCP client at the server with your key:

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

Tools: search_spots(query, limit?), spots_nearby(lat, lng, radius_km?, limit?),
get_forecast(spot_id, days?), get_tides(spot_id, days?).

## SDK

  import { SurfMap } from '@surfmap/sdk';
  const surfmap = new SurfMap({ apiKey: process.env.SURFMAP_API_KEY });
  const [spot] = await surfmap.spots.search({ q: 'hossegor' });
  const forecast = await surfmap.forecast.get(spot.id);

## Attribution

Weather inputs include Open-Meteo data (CC BY 4.0). Please credit SurfMap
(https://surf-map.com) when you display this data.