Buckets:
| Name | Size | Uploaded | Xet hash |
|---|---|---|---|
| .gitattributes | 2.55 kB xet | 2eeb7293 | |
| README.md | 15.3 kB xet | 0ca2094c | |
| wsl-v4.sqlite | 19.4 MB xet | 0c331265 |
WSL Championship Tour Heat-Level Dataset (2014–2025)
A complete, structured, hash-chained dataset of every World Surf League Men's and Women's Championship Tour heat from 2014 through 2025 — 230 events, 7,494 heats, 17,710 surfer-heat rows, 103,489 individual waves — joined to break geometry and ERA5 oceanic/atmospheric reanalysis.
Built for fantasy-league optimization, surf analytics, and educational machine-learning work. Every row is identified by a deterministic SHA-256 hash chain, every value is sourced from the public WSL website with documented provenance, and every known source-data limitation is recorded explicitly rather than papered over.
Quick start
import sqlite3
import pandas as pd
conn = sqlite3.connect("wsl-v4.sqlite")
# All heats from a recent event with conditions
heats = pd.read_sql("""
SELECT e.name, h.heat_date, h.wave_range, h.wind_condition,
era5.wave_height_m, era5.wind_speed_kmh
FROM Event e
JOIN Heat h ON h.event_id = e.event_id
LEFT JOIN ERA5Conditions era5
ON era5.break_id = h.break_id
AND DATE(era5.observation_hour) = h.heat_date
AND CAST(substr(era5.observation_hour, 12, 2) AS INTEGER) = 12 -- noon
WHERE e.year = 2025 AND e.tour = 'MCT'
""", conn)
For a working schema dump, run sqlite3 wsl-v4.sqlite '.schema' after download.
Dataset summary
- Coverage: 2014–2025, both Men's CT (MCT) and Women's CT (WCT), all events including wave-pool stops (Surf Ranch, Freshwater Pro, Surf Abu Dhabi, Jeep Surf Ranch).
- Granularity: Wave-level. Every wave a surfer caught in every heat is a row, with score, counted/uncounted flag, interference flag, and direction (for wave-pool events).
- Format: Single SQLite file (~18 MB, 9 tables, 7 indexes). The compact size is deliberate — see "ERA5 design choice" below.
- Identity: Every primary key is a deterministic SHA-256 hash truncated to 16 hex characters. The hash chain encodes ancestry:
wave_id = SHA256(heat_id|athlete_id|wave_index),heat_id = SHA256(round_id|heat_number), etc. Two independent observers computing IDs from the same source HTML produce the same IDs — the dataset is reproducible by construction. - Conditions: ERA5 reanalysis from Open-Meteo (Marine + Archive APIs) joined by
(break_id, observation_hour). 98.5% of heats join to a full 24-hour ERA5 day at their break. - Audit: Verdict HEALTHY, 0 Critical, 0 Major findings. 365 / 365 stratified-sample heats verified clean against the live WSL site at publication time.
Tables
| Table | Rows | Purpose |
|---|---|---|
Event |
230 | One row per (year, tour, name, location, anomaly_class). MCT and WCT are always separate rows. |
Round |
1,496 | Three columns: round_id, event_id, round_number. No display name (app-layer concern). |
Heat |
7,494 | The principal competitive unit. Date, duration, conditions, break, wsl_heat_id for source traceability. |
HeatSurfer |
17,710 | (heat × surfer) pairing with total_score and outcome_type. |
Wave |
103,489 | One row per wave. Score, is_counted (top-2-counted indicator), is_zeroed_by_interference, direction (wave-pool only). |
Surfer |
474 | Surfer profile: nationality, stance, DOB, height/weight (where WSL publishes them). |
Break |
40 | Geographic + competitive metadata — lat/lon, break type/handedness, swell window, orientation. |
BreakAlias |
196 | Year-aware mapping of WSL-rendered location strings → canonical break_id. |
ERA5Conditions |
15,264 | Hourly ERA5 reanalysis: wave height/period/direction, wind speed/direction, surface pressure. |
Hash chain (governing identity rule)
event_id = SHA256(name | year | tour | location | x)[:16]
round_id = SHA256(event_id | round_number)[:16]
heat_id = SHA256(round_id | heat_number)[:16]
heatentry_id = SHA256(heat_id | athlete_id)[:16]
wave_id = SHA256(heat_id | athlete_id | wave_index)[:16]
break_id = SHA256(name | lat:.6f | lon:.6f)[:16]
condition_id = SHA256(break_id | observation_hour)[:16]
athlete_id = SHA256(name | date_of_birth | nationality)[:16]
x = 1 for multi-break events (heats span breaks with different competitive character — e.g. 2018 Margaret River split across North Point, Margaret River, Uluwatu after a shark incident; 2020 Maui Pro split between Honolua Bay and Pipeline). Heat-level break_id is authoritative for which specific break each heat ran at.
NULL sentinel: any field that is NULL in the source uses the literal string "NULL" in hash inputs. Exception: heat_number falls back to 1-based positional ordering within its round when the source HTML doesn't provide a number, to avoid hash collisions.
Coverage by year and tour
| Year | MCT events | WCT events | Notes |
|---|---|---|---|
| 2014–2019 | 11 | 10 | Standard tour |
| 2020 | 1 | 1 | COVID-disrupted year. Only the December 2020 Pipe Masters and Maui Pro made it. |
| 2021 | 7 | 7 | Truncated COVID-recovery season |
| 2022–2024 | 10–11 | 10–11 | Standard tour |
| 2025 | 12 | 12 | Current full season (latest) |
Pre-2014 data is not included in this release. Earlier development generations of this dataset once contained partial MCT 2008–2013 and WCT 2010–2013 data scraped from WSL's archive, but per-wave detail is incomplete for that era and those generations were superseded before v4. The current production database and the available pre-v4 backup both cover 2014 onward only. v4 is therefore not a 2008-onward archive with the early years stripped — it is a uniform 2014–2025 dataset by design, where every event has full wave-level fidelity.
Data sources and provenance
Competition data is scraped from public WSL results pages (worldsurfleague.com/events/...) using the heat-popup endpoint and round-listing pages. Every heat record is traceable back to a specific WSL URL via Heat.wsl_heat_id. Recent re-crawls (April 2026) used direct popup-by-popup parsing with grid-attribution validation; earlier crawl batches were verified end-to-end against the same source.
ERA5 conditions come from Open-Meteo's Marine API (models=era5_ocean) and Archive API (models=era5). Hourly resolution, 0.25–0.5° spatial. Stored as raw values — no aggregation at the storage layer.
ERA5 design choice — why the dataset is ~18 MB. A naïve enrichment fetches ERA5 for every hour of every day across each break's full historical span. For 28 ocean breaks over a 12-year window that's ~2.9 million hourly rows, the vast majority of which would never join to a heat (heats happen on a handful of discrete days per year, not continuously). The v3 predecessor of this dataset stored ~129 MB primarily for that reason. v4 instead fetches ERA5 only for the actual heat days each break sees — one 24-hour ERA5 day per unique (break_id, heat_date) pair — producing 15,336 rows with 100% ocean-heat join coverage. Same usability, ~7× smaller file. Wave-pool venues (Surf Ranch, Surf Abu Dhabi) carry zero ERA5 rows by policy: pool conditions are mechanically generated and are not derivable from offshore reanalysis, so populating them would create joinable but physically meaningless values.
Surfer profile data (nationality, stance, DOB, height/weight) is scraped from individual athlete profile pages. Nationality follows WSL's competitive designation rather than legal citizenship (e.g. Hawaiian surfers are listed as "Hawaii", not "United States" — WSL treats Hawaii as a separate competitive territory).
No carry-forward. Every row of competition data was fetched fresh from WSL's current servers in 2026, parsed by an audited parser, and validated against per-heat consistency rules (e.g. total_score == sum(top-2 counted scores) for every surfer). Six events that were originally carried forward from a prior release were purged and re-crawled in this release.
Verification status
- Audit verdict: HEALTHY (0 Critical, 0 Major, 14 Minor, 36 Info findings).
- Stratified sample verifier: 365 / 365 heats verified clean. Sample stratifies by year (≥15 ocean heats per year) and per wave-pool event (≥3 heats per event, or all heats for events with fewer than 3 by structure).
- Per-heat consistency: Every
HeatSurfer.total_scorereconciles withSUMof the top-2 counted Wave scores within the same (heat, athlete) within ±0.011 tolerance, except where WSL applied an interference penalty. - Hash-chain integrity: Every
Wavetraces to aHeatSurfertraces to aHeattraces to aRoundtraces to anEvent; no orphan rows.
Known limitations (documented)
Heat times not stored. Granularity is day-only (
heat_date). WSL does not publish per-heat start times for historical heats. ERA5 joins use day-level matching and let the consumer decide which hour(s) to interpolate.Penalty 1 (interference halving) not detectable. WSL applies interference at three tiers: (1) second-best wave halved, (2) second-best wave zeroed, (3) best wave zeroed. Tiers 2 and 3 are captured via
Wave.is_zeroed_by_interference = 1(cell carrieswave--adjustedclass AND score = 0.0). Tier 1 is a score reduction with no machine-readable HTML signal — the pre-halving score is never published. The post-halving score (which we store) is correct as a score; only the "this was halved" annotation is missing. No re-crawl will fix this — it's a source-data limitation.TBD waves. WSL renders some wave-grid cells as the literal text "TBD" — slots that exist on the wave grid but never received a numeric score (likely WSL data-entry gaps). v4 stores TBD waves as
Waverows withscore = NULL,is_counted = 0. The wave_count column matches WSL's display; aggregations should filterWHERE score IS NOT NULLto exclude. There are 12 TBD waves total.Heat.wsl_heat_id = -1sentinel. 14 pre-2023 wave-pool heats (Surf Ranch 2018, Freshwater 2019, Jeep Surf Ranch 2021) carry the sentinel value-1because WSL's leaderboard rendering for those years does not expose individual heat IDs. The verifier uses a leaderboard-format branch for these. No data is missing — only the WSL-side ID.Source omissions in
wave_range/wind_condition. WSL did not consistently publish wave range or wind condition for 2014–2017 events, and a few 2023 events have event-wide gaps (Pipe Pro, Portugal, Bells Beach). NULL means absent at source. ERA5 covers these gaps numerically.ERA5 break coverage = 28 of 40 breaks. 98.5% of heats join. The 112 unjoined heats are at 12 breaks not yet pulled into
ERA5Conditions— Surf Ranch, Surf Abu Dhabi, plus 10 lower-volume venues. Open-Meteo data is available for these; pulling it is straightforward future work.Surfer height / weight ~40% populated. WSL profile pages omit these fields for many historical surfers. NULL = not published, not zero.
Suggested uses
Fantasy surf league optimization. The dataset was originally built for this. Per-event point totals, per-surfer break-history aggregates, and ERA5 conditions are all queryable in SQL. See [GitHub repo / paper / blog post — TBD] for prior modeling experiments.
Educational ML. A worked example of a domain-expert-driven ML project from data collection through audit. The v4 build itself is a story — the project includes documented bug discoveries, parser corrections, and audit-driven verification. Useful for teaching how to build trustworthy data pipelines from scraped web sources.
Sports analytics research. Wave-by-wave granularity over 12 years, multi-tour, multi-venue, with weather covariates. Suitable for studying career trajectories, condition-performance interactions, head-to-head matchup outcomes, etc.
What this dataset is NOT. It is not an official WSL product. It is not real-time. It does not include video, replays, or judge-by-judge score breakdown (WSL does not publish per-judge scores in popup HTML for completed heats). It does not include interference Penalty-1 halving annotations (see Limitations).
Schema details
Run .schema in sqlite3 against wsl-v4.sqlite for the canonical schema. Highlights:
Wave columns:
wave_id(PK),heat_id,athlete_id,wave_index(1-based per surfer-heat)score(REAL) — WSL's displayed score, post-penalty if applicable. NULL for TBD waves.is_counted(INTEGER 0/1) — 1 if this wave is one of the surfer's top-2 (counts toward heat total).is_zeroed_by_interference(INTEGER 0/1) — 1 only for Penalty 2/3 strict zeroing (see Limitations).direction(TEXT) —"right"or"left"for wave-pool waves; NULL for ocean.
Heat columns:
heat_id(PK),round_id,event_id,heat_numberheat_date(TEXT YYYY-MM-DD),heat_duration(TEXT ISO-8601, e.g.PT30M)wave_range,wind_condition(TEXT — WSL's rendered strings, may be NULL for archive gaps)break_id(TEXT) — joins toBreakandERA5Conditionswsl_heat_id(INTEGER) — sentinel-aware:> 0= popup-format with WSL-assigned ID;-1= leaderboard-format pre-2023 wave-pool; never NULLdata_quality_notes(TEXT) — non-NULL for ~35 heats with documented anomalies
Event columns:
event_id(PK),name,year,tour("MCT"or"WCT"),locationbreak_id(TEXT) — default break for the event; heat-level break_id is authoritative for split eventscontest_start_date,contest_end_date,is_split_event(INTEGER 0/1)note(TEXT) — descriptive notes for calendar-straddling, COVID-disrupted, multi-break sourcing, etc.
Citation
If you use this dataset in research, please cite:
@dataset{wsl_v4_2026,
author = {Friedlander, Mark},
title = {WSL Championship Tour Heat-Level Dataset (2014--2025), v4},
year = {2026},
publisher = {Hugging Face},
url = {https://huggingface.co/datasets/<TBD>}
}
License
This dataset is released under Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).
Required attributions:
- WSL data: Scraped from public results pages on
worldsurfleague.com. Not an official WSL product. - ERA5 weather data: "Weather data by Open-Meteo.com" (CC BY 4.0).
Changelog
- v4 (2026-04-30, this release): Fresh recrawl of all competition data from WSL. Hash chain locked. ERA5 join coverage 98.5%. 365/365 stratified-sample heats verified clean. Audit verdict HEALTHY.
- Total size
- 19.4 MB
- Files
- 3
- Last updated
- Nov 6
- Pre-warmed CDN
- US EU US EU