Surfline APIsurfline.com ↗
Access Surfline surf forecasts, wind, tide, current conditions, spot listings, and live camera feeds via a structured REST API. 6 endpoints, global coverage.
What is the Surfline API?
The Surfline API gives developers structured access to 6 endpoints covering wave forecasts, wind, tides, current conditions, regional spot listings, and live camera feeds. The get_surf_forecast endpoint returns per-timestamp swell data — height, period, direction, and power — for any spot identified by its Surfline spot ID. Real-time snapshots, multi-day forecasts, and camera stream URLs are all available in a single consistent JSON interface.
curl -X GET 'https://api.parse.bot/scraper/ee8dc746-3f62-4465-8b17-cc5d8c44a178/get_surf_forecast?days=1&spot_id=5842041f4e65fad6a7708ceb&interval=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace surfline-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.surfline_api import Surfline, Spot, SpotConditions, WaveForecast, WindForecast, TideForecast, Region, Camera
surfline = Surfline()
# Discover spots in Hawaii
hawaii = surfline.region(id="58f7ed87dadb30820bb3c537")
for spot in hawaii.spots():
print(spot.name, spot.lat, spot.lon)
# Get current conditions for a specific spot
pipeline = surfline.spot(id="5842041f4e65fad6a7708890")
conditions = pipeline.conditions()
print(conditions.name, conditions.rating.key, conditions.rating.value)
print(conditions.surf.min, conditions.surf.max, conditions.surf.human_relation)
print(conditions.wind.speed, conditions.wind.direction_type, conditions.wind.gust)
print(conditions.weather.temperature, conditions.weather.condition)
print(conditions.water_temp.min, conditions.water_temp.max)
# Get surf forecast
for wave in pipeline.surf_forecast(days=2, interval=3):
print(wave.timestamp, wave.surf.min, wave.surf.max, wave.power)
for swell in wave.swells:
print(swell.height, swell.period, swell.direction)
# Get wind forecast
for wind in pipeline.wind_forecast(days=1, interval=6):
print(wind.timestamp, wind.speed, wind.direction_type, wind.gust)
# Get tide forecast
for tide in pipeline.tide_forecast(days=1):
print(tide.timestamp, tide.type, tide.height)
# List cameras in a region
for cam in hawaii.cams():
print(cam.title, cam.spot_name, cam.stream_url)
Retrieve detailed surf forecast for a specific spot. Returns wave height (min/max), swell components (height, period, direction, power), and other wave data for multiple timestamps. Each data point includes surf min/max in feet, human-readable size relation, swell breakdown, and probability. The interval parameter controls spacing between data points.
| Param | Type | Description |
|---|---|---|
| days | integer | Number of forecast days |
| spot_idrequired | string | Surfline spot ID (e.g. 5842041f4e65fad6a7708ceb) |
| interval | integer | Interval in hours between data points |
{
"type": "object",
"fields": {
"wave": "array of wave forecast objects with timestamp, surf min/max, swells, power, probability"
},
"sample": {
"data": {
"wave": [
{
"surf": {
"max": 4,
"min": 3,
"raw": {
"max": 4.2,
"min": 3.1
},
"plus": false,
"optimalScore": 2,
"humanRelation": "Waist to chest"
},
"power": 239,
"swells": [
{
"power": 237.7,
"height": 5.24,
"impact": 0.81,
"period": 8,
"direction": 174.2,
"directionMin": 161.2,
"optimalScore": 0
}
],
"timestamp": 1781060400,
"utcOffset": -3,
"probability": 100
}
]
},
"status": "success"
}
}About the Surfline API
Forecasts: Waves, Wind, and Tides
get_surf_forecast accepts a spot_id, optional days count, and an optional interval (in hours) to control forecast resolution. Each object in the returned wave array includes surf.min, surf.max, a swells array with individual swell height, period, direction, and power, plus a probability field. get_wind_forecast returns matching timestamp-aligned objects with speed, direction, gust, a directionType field that distinguishes Offshore, Onshore, and Cross-shore conditions, and an optimalScore. get_tide_forecast returns height and a discrete type — HIGH, LOW, or NORMAL — for each prediction window.
Current Conditions and Spot Metadata
get_current_conditions returns a real-time snapshot for a single spot. The response includes the spot name, a rating object with both a human-readable key (e.g. POOR_TO_FAIR, GOOD) and a numeric value, current surf min/max, wind state, weather temperature and condition, waterTemp range, and a cameras array listing any live feeds attached to that spot.
Spot Discovery and Camera Listings
get_spots_by_region accepts a region_id from Surfline's taxonomy tree and returns an array of spot objects — each with id, name, lat, and lon — plus a total count. Example region IDs for Hawaii and Europe are documented. list_cams returns camera objects with streamUrl and stillUrl for each feed. Called without a region_id it returns popular US cameras; filtered by region it returns cameras for up to the first 100 spots in that region, and includes lat/lon coordinates. Some regions return no cameras.
Spot IDs and Data Alignment
All forecast and conditions endpoints require a Surfline spot_id string (e.g. 5842041f4e65fad6a7708ceb). These IDs are stable identifiers that appear in both get_spots_by_region results and list_cams responses, so you can chain discovery and forecast calls. Forecast timestamps are Unix epoch values and align across wave, wind, and tide responses for the same spot.
The Surfline API is a managed, monitored endpoint for surfline.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when surfline.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official surfline.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a surf session planner that displays swell height, period, and direction for a chosen spot over the next 5 days.
- Alert surfers when
directionTypeflips to Offshore andoptimalScoreexceeds a threshold at their saved spots. - Embed live camera stills using
stillUrlfromlist_camson a regional surf conditions dashboard. - Create a tide chart by pulling
heightandtype(HIGH/LOW/NORMAL) fromget_tide_forecastfor any spot. - Map all surf spots in a region using
lat/lonfromget_spots_by_regionto build a geo-filtered spot finder. - Display a spot's current
ratingkey and water temperature range alongside wind gust data for quick go/no-go decisions. - Aggregate historical rating patterns by logging
get_current_conditionsresponses at regular intervals across multiple spot IDs.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Surfline have an official developer API?+
What does `get_surf_forecast` return beyond wave height?+
wave array includes surf.min and surf.max (the human-scaled height range), a swells array where every swell entry carries height, period, direction, and power, a top-level power value for the composite swell, and a probability field. You can control how many timestamps appear by passing an interval parameter (in hours) and a days count.Does `list_cams` return cameras for all regions worldwide?+
region_id, the endpoint returns popular US cameras. When you pass a region_id, it covers cameras tied to up to the first 100 spots in that region. Some regions have no cameras at all. The API currently covers discovery and stream/still URLs; it does not return archived footage or historical camera snapshots. You can fork it on Parse and revise to add an endpoint targeting archived content if that becomes available.Is surf rating history or past forecast data accessible?+
get_current_conditions and forward-looking forecasts via the wave, wind, and tide endpoints. Historical forecast archives and past conditions records are not exposed. You can fork it on Parse and revise to add the missing endpoint if Surfline surfaces a historical data route.