World Surf League APIworldsurfleague.com ↗
Access WSL event schedules, heat-by-heat scores, athlete profiles, and tour rankings via the worldsurfleague.com API. 6 endpoints covering all major tours.
What is the World Surf League API?
This API covers 6 endpoints pulling live and historical competition data from worldsurfleague.com, including event schedules, round-by-round results, and individual heat wave scores. The get_heat_details endpoint returns wave-by-wave scoring for every athlete in a heat alongside fantasy stats, while get_tour_rankings returns ranked standings with points totals across CT, QS, and longboard tours.
curl -X GET 'https://api.parse.bot/scraper/2381c8f6-f756-4b78-85c1-8e441fe15585/get_athletes?tour=mct&query=Medina' \ -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 worldsurfleague-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: World Surf League SDK — browse events, drill into heats, check rankings."""
from parse_apis.world_surf_league_api import WSL, RankingTour, EventTour, ResourceNotFound
client = WSL()
# Get men's championship tour rankings
for ranking in client.rankings.list(tour=RankingTour.MCT, year="2024", limit=5):
print(ranking.name, ranking.country, ranking.total_points)
# List championship tour events and drill into the first one's results
event = client.events.list(tour_code=EventTour.CT, year="2024", limit=1).first()
if event:
result = event.results()
for rnd in result.rounds[:1]:
print(rnd.round_name)
for heat in rnd.heats[:2]:
for athlete in heat.athletes:
print(athlete.name, athlete.score, athlete.is_winner)
# Get wave-by-wave details for the first heat
first_heat_id = result.rounds[0].heats[0].id
detail = event.heats.get(heat_id=first_heat_id)
for wave_score in detail.wave_data:
print(wave_score.athlete_name, wave_score.waves)
# Search athletes and view a profile
athlete_summary = client.athletesummaries.search(query="Medina", limit=1).first()
if athlete_summary:
try:
profile = athlete_summary.profile()
print(profile.name, profile.details.hometown, profile.details.stance)
for cr in profile.event_results[:3]:
print(cr.event, cr.place, cr.points)
except ResourceNotFound as exc:
print(f"Athlete not found: {exc}")
print("exercised: rankings.list / events.list / event.results / event.heats.get / athletesummaries.search / profile")Search for athletes by name or filter by tour. Returns a list of matching athletes with their IDs, slugs, names, and profile URLs. Without parameters, returns athletes visible on the default athletes page.
| Param | Type | Description |
|---|---|---|
| tour | string | Tour code to filter athletes (e.g. mct, wct, mcs, wcs) |
| query | string | Athlete name to search for |
{
"type": "object",
"fields": {
"athletes": "array of athlete objects with id, slug, name, and url"
},
"sample": {
"data": {
"athletes": [
{
"id": "1085",
"url": "https://www.worldsurfleague.com/athletes/1085/gabriel-medina",
"name": "Gabriel Medina",
"slug": "gabriel-medina"
}
]
},
"status": "success"
}
}About the World Surf League API
Schedules and Event Data
The get_event_schedule endpoint accepts a year and optional tour_code (e.g. ct, qs, lt, bwt) and returns an array of event objects with fields including id, slug, name, date, location, and status. These identifiers — particularly slug, event_id, and tour — are required inputs for the results and heat endpoints, so the schedule is typically the starting point for any data pipeline.
Results and Heat Scoring
get_event_results returns a nested structure of rounds, each containing a heats array with per-athlete scores. Passing a heat_id from those results into get_heat_details returns wave_data, an array of objects pairing athlete_name with a waves array of score strings — giving full wave-by-wave breakdowns. A fantasy_stats object is included when available for that heat, and returns an empty object otherwise.
Athlete Profiles and Rankings
get_athletes supports both name search via query and tour filtering via tour (e.g. mct, wct, mcs, wcs), returning athlete id, slug, name, and url. Passing those identifiers to get_athlete_profile returns details (hometown, stance, age, height where available) and an event_results array listing event, place, points, and defeated_by across the athlete's career. get_tour_rankings returns a ranked list with rank, name, country, and total_points for any supported tour and year combination.
ID Chaining
Most endpoints require IDs sourced from earlier calls. The recommended flow is: get_event_schedule → get_event_results → get_heat_details. Similarly, get_athletes supplies the athlete_id and slug needed for get_athlete_profile. There is no standalone lookup by athlete ID without first going through the athlete search endpoint.
The World Surf League API is a managed, monitored endpoint for worldsurfleague.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when worldsurfleague.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 worldsurfleague.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 competition tracker showing live round-by-round results for CT events using
get_event_results. - Display wave-by-wave score breakdowns for individual heats using
get_heat_detailswave_data fields. - Generate season standings dashboards by pulling
total_pointsandrankfromget_tour_rankingsfor multiple tours. - Power an athlete comparison tool using career
event_resultsincludingplace,points, anddefeated_byfromget_athlete_profile. - Sync WSL event calendars by fetching
date,location, andstatusfields fromget_event_schedulefor a given year. - Integrate WSL fantasy scoring data into a custom fantasy surf application using
fantasy_statsfromget_heat_details. - Filter and list active QS or BWT athletes by tour using the
tourparameter inget_athletes.
| 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 the World Surf League have an official developer API?+
What tour codes are supported across the endpoints?+
get_event_schedule accepts ct, qs, lt, and bwt. get_athletes and get_tour_rankings use a different set: mct, wct, mcs, wcs, mqs, and wqs, representing men's and women's Championship Tour, Challenger Series, and Qualifying Series respectively. Mixing tour codes between endpoints that expect different formats will produce no results.Are surf forecasts, swell data, or heat draw brackets included?+
How complete is the `details` object returned by `get_athlete_profile`?+
details object includes hometown, stance, age, and height, but these fields are optional and may be absent for some athletes depending on what WSL has published for that profile. event_results is always returned as an array but may be empty for athletes with no recorded results.Is historical heat data available, or only current season results?+
year parameter on get_event_schedule and get_tour_rankings allows querying past seasons. Since get_event_results and get_heat_details require event identifiers from get_event_schedule, you can retrieve historical heat data for any year where WSL published event records — though completeness of older seasons depends on what the source has retained.