magicseaweed.com APImagicseaweed.com ↗
Access surf forecasts, wave heights, wind, tides, and weather for any surf spot worldwide via the Magicseaweed API. Search spots and get up to 16-day forecasts.
curl -X GET 'https://api.parse.bot/scraper/bdd16c83-771c-411b-b9e9-b7de50f4ec1a/search_spots?query=Malibu' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for surf spots by name to find their unique IDs. Returns matching spots, geonames, and travel destinations.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | The name of the beach or surf spot to search for (e.g. 'Malibu', 'Pipeline'). |
{
"type": "object",
"fields": {
"query": "string — the search query echoed back",
"spots": "array of objects containing id, name, breadCrumbs, location (lat/lon), and type (spot, geoname, editorial, travel)"
},
"sample": {
"data": {
"query": "Malibu",
"spots": [
{
"id": "5842041f4e65fad6a7708e1b",
"name": "Baja Malibu",
"type": "spot",
"location": {
"lat": 32.417,
"lon": -117.096
},
"breadCrumbs": [
"Mexico",
"Estado de Baja California",
"Tijuana"
]
},
{
"id": "584204214e65fad6a7709b9f",
"name": "Malibu First Point",
"type": "spot",
"location": {
"lat": 34.03577735818882,
"lon": -118.67668
},
"breadCrumbs": [
"United States",
"California",
"Los Angeles County"
]
}
]
},
"status": "success"
}
}About the magicseaweed.com API
The Magicseaweed API covers 3 endpoints that expose surf spot discovery, detailed multi-day forecasts, and popular spot conditions. The get_spot_forecast endpoint returns hourly wave, wind, tide, and weather data for up to 16 days at any spot ID, while search_spots resolves location names — from "Malibu" to "Pipeline" — into the numeric IDs those forecasts require. A third endpoint surfaces a curated list of popular breaks with current conditions and camera details.
Spot Search and Discovery
The search_spots endpoint accepts a query string and returns an array of matching results, each carrying an id, name, breadCrumbs for context, a location object with latitude and longitude, and a type field that distinguishes between surf spots, geonames, editorial features, and travel destinations. This makes it the correct starting point when you have a place name but need the spot_id required by the forecast endpoint.
The get_popular_spots endpoint requires no parameters and returns a data object containing a spots array with current conditions, surf, wind, swells, tide, and cameras fields for each featured break. An associated object carries unit configuration, and a permissions object surfaces any access restrictions. This endpoint is suited for overview dashboards that need a snapshot of well-known breaks without prior knowledge of individual spot IDs.
Forecast Data
The get_spot_forecast endpoint takes a required spot_id and an optional days integer (1–16) and returns four parallel arrays: wave (timestamp, surf min/max, swell breakdown, power), wind (timestamp, speed, direction, directionType, gust), tides (timestamp, type, height), and weather (timestamp, temperature, condition, pressure). Each array uses consistent timestamps so records at the same index can be aligned across forecast types. An associated object provides units, UTC offset, location metadata, and forecast metadata to frame the raw numbers correctly.
Coverage Notes
Magicseaweed indexes thousands of named surf spots globally. The breadCrumbs field in search results helps disambiguate spots that share names across regions. Forecast depth extends to 16 days, though confidence naturally decreases at the outer range. Tide data uses type and height fields rather than a continuous water-level series, which suits session planning but not precision marine modeling.
- Build a surf session planner that resolves a beach name via
search_spotsand displays a 7-day wave height and wind chart fromget_spot_forecast. - Create a travel itinerary tool that cross-references
get_popular_spotsconditions with flight and accommodation availability. - Power a surf alert system that monitors swell
min/maxand gust values and notifies users when thresholds are met at a saved spot. - Render a tide table widget using the
tidesarray (type and height fields) for any spot ID. - Display a regional conditions map by resolving spot
locationlat/lon fromsearch_spotsand layering current conditions fromget_popular_spots. - Aggregate historical forecast accuracy by storing timestamped
waveandweatherresponses and comparing them against later actuals. - Enrich a surf camp booking platform with live break conditions and camera availability from the
get_popular_spotscameras field.
| 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 | 250 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 Magicseaweed have an official developer API?+
What does `get_spot_forecast` return and how do I control the time range?+
wave, wind, tides, and weather — each containing objects with a timestamp field for alignment. You control the horizon using the days parameter, which accepts integers from 1 to 16. Omitting days returns the default forecast window. The associated object in the response provides the UTC offset and units needed to interpret raw timestamps and measurement values correctly.Does the API return surf spot user reviews or crowd ratings?+
Can I retrieve historical forecast or observed wave data?+
How do I find the correct spot_id for a location like 'Jeffreys Bay' or 'Uluwatu'?+
query parameter to search_spots. The response returns an array of matching objects, each with an id, name, breadCrumbs (which shows the region and country hierarchy), and a type field. Use type: spot results and match on breadCrumbs to resolve ambiguity when multiple spots share a name. The id from that object is the spot_id value for get_spot_forecast.