Ariasurf APIariasurf.com ↗
Search thousands of surf spots worldwide and retrieve 48-hour hourly forecasts with swell, wind, tide, and water temperature data via the Ariasurf API.
What is the Ariasurf API?
The Ariasurf API covers 4 endpoints that expose surf spot search and detailed hourly surf forecasts for locations worldwide. The get_spot_forecast endpoint returns up to 48 hours of per-hour data including swell wave height, period, and direction, wind speed and gusts, tide height, and water temperature — all keyed to a spot UUID retrieved from search_spots. A blog content layer is also available via list_posts and get_post.
curl -X GET 'https://api.parse.bot/scraper/06f2b051-ae63-4d35-b233-125f43f29e49/search_spots?query=Bali' \ -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 ariasurf-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.
"""Walkthrough: Aria Surf SDK — bounded, re-runnable; every call capped."""
from parse_apis.Aria_Surf_API import AriaSurf, SpotNotFound
client = AriaSurf()
# List blog posts from the listing page
for post_summary in client.post_summaries.list(limit=3):
print(post_summary.title, post_summary.published_date, post_summary.excerpt[:60])
# Drill-down: get full details of the first post
summary = client.post_summaries.list(limit=1).first()
if summary:
full_post = summary.details()
print(full_post.title, full_post.author, full_post.tags)
for related in full_post.related_posts[:2]:
print(related.title, related.url)
# Search for surf spots
for spot in client.spots.search(query="Bali", limit=3):
print(spot.name, spot.country, spot.latitude, spot.longitude)
# Get a forecast for the first spot found
spot = client.spots.search(query="Pipeline", limit=1).first()
if spot:
try:
forecast = spot.forecast()
print(forecast.name, forecast.address.country)
for hour in forecast.forecast_hours[:3]:
print(hour.time, hour.swell_wave_height, hour.wind_speed)
except SpotNotFound as e:
print("spot gone:", e.identifier)
print("exercised: post_summaries.list, PostSummary.details, spots.search, spot.forecast")
Full-text search over surf spots by name. Returns matching spots with location, surface type, and address metadata. Results are auto-iterated as a single page.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search term matched against spot names (e.g. a beach name, region, or famous break). |
{
"type": "object",
"fields": {
"spots": "array of surf spot objects with identifier, name, coordinates, surface, address",
"total": "integer count of matching spots"
},
"sample": {
"spots": [
{
"name": "Balian",
"town": null,
"state": "Bali",
"country": "Indonesia",
"surface": "sand",
"latitude": -8.5026987,
"longitude": 114.9643489,
"identifier": "bbe3a28a-44a7-4cac-9e20-5292f6bb34a3",
"description": null,
"country_code": "id",
"orientation_degrees": 208,
"coast_distance_meters": 19
}
],
"total": 9
}
}About the Ariasurf API
Spot Search and Forecast
Use search_spots with a query string — a beach name, region, or well-known break — to get back an array of matching surf spot objects. Each result includes a UUID identifier, display name, decimal coordinates, surface type, and structured address metadata. Pass that identifier to get_spot_forecast to pull the full forecast.
Hourly Forecast Data
get_spot_forecast returns a forecast_hours array covering up to 48 consecutive hours. Each entry carries swellWaveHeight, swellWavePeriod, and swellWaveDirection alongside windSpeed, windGusts, and windDirect. Tide height, water temperature, and wave height are also present per hour, and each record includes sunrise and sunset timestamps for that location. The response also echoes the spot's name, address (locality, country, postal code), latitude, and longitude.
Blog Content Endpoints
list_posts returns all published Ariasurf blog posts in a single page — each summary includes slug, title, author, published_date, thumbnail_url, tags, and a short excerpt. The site serves all posts on page 1; requesting page values above 1 returns an empty list. get_post accepts a slug and returns the full article body as HTML (full_content), canonical url, tags, author, thumbnail_url, published_date, and a related_posts array with slugs, titles, and URLs of linked articles.
The Ariasurf API is a managed, monitored endpoint for ariasurf.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ariasurf.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 ariasurf.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 shows 48-hour swell and wind forecasts for a searched beach.
- Display tide height and water temperature trends alongside wave height for dive and surf trip planning.
- Create a spot-comparison tool that queries multiple surf breaks by name and overlays their hourly forecasts.
- Send daily wind and swell alerts to users who have saved specific spot UUIDs.
- Power a surf travel app that resolves a region name to matching spots and surfaces their coordinates on a map.
- Aggregate Ariasurf blog posts into a content feed filtered by topic tag.
- Archive surf forecasting articles by fetching full HTML content and related post links from
get_post.
| 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 Ariasurf have an official developer API?+
What does get_spot_forecast return beyond wave height?+
get_spot_forecast returns a full forecast_hours array where each hour includes swellWaveHeight, swellWavePeriod, swellWaveDirection, windSpeed, windGusts, windDirect, tide height, water temperature, wave height, and sunrise/sunset times for the spot's location. The spot's name, coordinates, and structured address are also included at the top level of the response.Does the API cover historical forecast data or only the next 48 hours?+
Can I retrieve a list of all surf spots without searching by name?+
search_spots requires a query string and returns matches against that term — there is no browse-all or category-filter mode currently. You can fork this API on Parse and revise it to add a listing or browse endpoint if that surface exists on the source site.How does pagination work for list_posts?+
list_posts endpoint accepts an optional page integer, but only page=1 returns data; any higher value returns an empty list and a total of zero.