sportsdataverse-py 
See CHANGELOG.md for details.
sportsdataverse-py gives the community free, tidy, analysis-ready sports data in Python. It is the Python member of the SportsDataverse family and deliberately mirrors its R sisters — hoopR (NBA/MBB), wehoop (WNBA/WBB), cfbfastR (CFB), baseballr (MLB), and fastRhockey (NHL/PWHL) — so the function you know in R is the function you call in Python. The NFL module mirrors the nflverse's nflreadpy, and the package plays well with the wider PySport ecosystem. Beyond aggregation and tidying, the project also exists to make open-source expected-points and win-probability models reproducible and benchmarkable, especially for American football.
New here? Read Ecosystem & philosophy for the design philosophy, the full function-naming paradigm, and how the Python and R packages line up.
Quickstart
pip install sportsdataverse
:::caution Deprecated
sportsdataverse.parsed.* is deprecated. The league wrappers already default to
return_parsed=True, so call sportsdataverse.nba (etc.) directly; the parsed
namespace is a thin alias kept for back-compat.
:::
# Today's NBA scoreboard: a polars DataFrame by default
from sportsdataverse.nba import espn_nba_scoreboard
df = espn_nba_scoreboard() # → polars
print(df.select(["game_id", "home_name", "away_name",
"home_score", "away_score"]).head())
raw = espn_nba_scoreboard(return_parsed=False) # → the raw Dict
# Aaron Judge's 2024 season stats from the official MLB API
from sportsdataverse.mlb import mlb_person_stats, parse_mlb_api_person_stats
judge = parse_mlb_api_person_stats(
mlb_person_stats(person_id=592450, stats="season", season=2024)
)
print(judge.select(["stats_group", "stat_home_runs", "stat_avg"]))
# Connor McDavid's 2024-25 EDGE skating speed profile
from sportsdataverse.nhl import nhl_edge_skater_detail, parse_edge_detail
mcdavid = parse_edge_detail(nhl_edge_skater_detail(8478402))
print(mcdavid.select(["player_first_name_default", "top_shot_speed_metric"]))
Parser-backed wrappers return a polars DataFrame by default (0.0.54+);
pass return_parsed=False for the raw Dict. Compose with the
matching parse_* function for NHL / MLB sibling APIs. See
Polars / pandas parser layer below.
Supported leagues and data sources
| League | Module | Data sources |
|---|---|---|
| NBA | sportsdataverse.nba | ESPN (123), sportsdataverse-data releases (53), NBA Stats API (130), Fox Sports API (26), Basketball-Reference (9), RealGM (18), Public model datasets (7) |
| WNBA | sportsdataverse.wnba | ESPN (127), sportsdataverse-data releases (39), WNBA Stats API (113), Fox Sports API (26) |
| NBA G League | sportsdataverse.nbagl | ESPN (112) |
| NBL | sportsdataverse.nbl | ESPN (112) |
| FIBA | sportsdataverse.fiba | ESPN (112) |
| Olympics men's basketball | sportsdataverse.olympics_mbk | ESPN (112) |
| Olympics women's basketball | sportsdataverse.olympics_wbk | ESPN (112) |
| NBA Summer League (Las Vegas) | sportsdataverse.nbasl_lv | ESPN (112) |
| NBA Summer League (Utah) | sportsdataverse.nbasl_ut | ESPN (112) |
| NBA Summer League (California) | sportsdataverse.nbasl_ca | ESPN (112) |
| NBA Summer League (Sacramento) | sportsdataverse.nbasl_sac | ESPN (112) |
| NBA Summer League (Orlando) | sportsdataverse.nbasl_orl | ESPN (112) |
| NBA Summer League (Golden State) | sportsdataverse.nbasl_gs | ESPN (112) |
| MBB | sportsdataverse.mbb | ESPN (129), sportsdataverse-data releases (34), stats.ncaa.org (136), KenPom (32), Bart Torvik T-Rank (5), Fox Sports API (27) |
| WBB | sportsdataverse.wbb | ESPN (132), sportsdataverse-data releases (34), stats.ncaa.org (114), Bart Torvik Women's T-Rank (1), Fox Sports API (27), Her Hoop Stats (5) |
| CFB | sportsdataverse.cfb | ESPN (132), sportsdataverse-data releases (74), stats.ncaa.org (1), On3 Recruit Database (82), 247Sports Recruit Database (47), Yahoo Sports Shangrila (7), Fox Sports API (29) |
| NFL | sportsdataverse.nfl | ESPN (125), NFL.com Shield API (22), NFL Pro (32), Sleeper fantasy API (15), PFF Developer API (68), PFF Premium Stats (LEGACY) (46), nflverse data releases (48), sportsdataverse-data releases (21), Fox Sports API (25) |
| MLB | sportsdataverse.mlb | ESPN (123), sportsdataverse-data releases (34), MLB Stats API (79), Baseball Savant (Statcast) (43), Fox Sports API (23) |
| NHL | sportsdataverse.nhl | ESPN (119), sportsdataverse-data releases (32), NHL Web API (28), NHL EDGE (35), NHL Stats REST (21), NHL Records (50), Fox Sports API (25) |
| MCH | sportsdataverse.hockey.mch | ESPN (118) |
| WCH | sportsdataverse.hockey.wch | ESPN (118) |
| College baseball | sportsdataverse.baseball.college_baseball | ESPN (122), stats.ncaa.org (3) |
| College softball | sportsdataverse.baseball.college_softball | ESPN (121) |
| UFL | sportsdataverse.football.ufl | ESPN (114) |
| XFL | sportsdataverse.football.xfl | ESPN (112) |
| CFL | sportsdataverse.football.cfl | ESPN (112) |
| Soccer (all) | sportsdataverse.soccer | ESPN (112), American Soccer Analysis (16), FotMob (14), UEFA (7), FIFA (9), Football-Data.co.uk (3), OpenLigaDB (11), kloppy open event data (8) |
| EPL | sportsdataverse.soccer.epl | ESPN (113) |
| LaLiga | sportsdataverse.soccer.laliga | ESPN (112) |
| Bundesliga | sportsdataverse.soccer.bundesliga | ESPN (112) |
| Serie A | sportsdataverse.soccer.seriea | ESPN (112) |
| Ligue 1 | sportsdataverse.soccer.ligue1 | ESPN (112) |
| MLS | sportsdataverse.soccer.mls | ESPN (113), MLS official web API (12) |
| Liga MX | sportsdataverse.soccer.ligamx | ESPN (112) |
| UCL | sportsdataverse.soccer.ucl | ESPN (113) |
| UEL | sportsdataverse.soccer.uel | ESPN (112) |
| NWSL | sportsdataverse.soccer.nwsl | ESPN (112), NWSL official web API (9) |
| WWC | sportsdataverse.soccer.wwc | ESPN (112) |
| WC | sportsdataverse.soccer.wc | ESPN (112) |
| Cricket | sportsdataverse.cricket | ESPN (112) |
| PWHL | sportsdataverse.pwhl | sportsdataverse-data releases (27), HockeyTech / LeagueStat (25) |
| AHL | sportsdataverse.hockey.ahl | HockeyTech / LeagueStat (11) |
| OHL | sportsdataverse.hockey.ohl | HockeyTech / LeagueStat (11) |
| WHL | sportsdataverse.hockey.whl | HockeyTech / LeagueStat (11) |
| QMJHL | sportsdataverse.hockey.qmjhl | HockeyTech / LeagueStat (11) |
| ECHL | sportsdataverse.hockey.echl | HockeyTech / LeagueStat (12) |
| SPHL | sportsdataverse.hockey.sphl | HockeyTech / LeagueStat (12) |
| CHL | sportsdataverse.hockey.chl | HockeyTech / LeagueStat (12) |
| USHL | sportsdataverse.hockey.ushl | HockeyTech / LeagueStat (12) |
| BCHL | sportsdataverse.hockey.bchl | HockeyTech / LeagueStat (12) |
| AJHL | sportsdataverse.hockey.ajhl | HockeyTech / LeagueStat (12) |
| SJHL | sportsdataverse.hockey.sjhl | HockeyTech / LeagueStat (12) |
| OJHL | sportsdataverse.hockey.ojhl | HockeyTech / LeagueStat (12) |
| CCHL | sportsdataverse.hockey.cchl | HockeyTech / LeagueStat (12) |
| GOJHL | sportsdataverse.hockey.gojhl | HockeyTech / LeagueStat (12) |
| MHL | sportsdataverse.hockey.mhl | HockeyTech / LeagueStat (12) |
| NOJHL | sportsdataverse.hockey.nojhl | HockeyTech / LeagueStat (12) |
| VIJHL | sportsdataverse.hockey.vijhl | HockeyTech / LeagueStat (12) |
| KIJHL | sportsdataverse.hockey.kijhl | HockeyTech / LeagueStat (12) |
| MJHL | sportsdataverse.hockey.mjhl | HockeyTech / LeagueStat (12) |
| Betting odds | sportsdataverse.odds | The Odds API (11), Polymarket (8), Kalshi (9) |
| CBS Sports | sportsdataverse.cbs | CBS Sports NAPI (82) |
| Yahoo Sports | sportsdataverse.yahoo | Yahoo Sports Shangrila (107) |
| Fox Sports | sportsdataverse.fox | Fox Sports API (33) |
| EuroLeague | sportsdataverse.euroleague | EuroLeague Competition Engine (15) |
| Formula 1 | sportsdataverse.f1 | Jolpica F1 API (Ergast-compatible) (16) |
| ESPN content (news) | sportsdataverse.espn_content | ESPN (3) |
| TheSportsDB | sportsdataverse.thesportsdb | TheSportsDB (12) |
| SIHF (Swiss hockey) | sportsdataverse.hockey.sihf | SIHF statistics API (33) |
| DEL | sportsdataverse.hockey.del_ | eSports hokejovyzapis (DEL, ICEHL, EIHL, Metal Ligaen) (12) |
| ICE Hockey League | sportsdataverse.hockey.icehl | eSports hokejovyzapis (DEL, ICEHL, EIHL, Metal Ligaen) (12) |
| EIHL | sportsdataverse.hockey.eihl | eSports hokejovyzapis (DEL, ICEHL, EIHL, Metal Ligaen) (9) |
| Metal Ligaen | sportsdataverse.hockey.metal | eSports hokejovyzapis (DEL, ICEHL, EIHL, Metal Ligaen) (8) |
| Czech Extraliga | sportsdataverse.hockey.elh | hokej.cz (Czech Extraliga) (9) |
| Liiga | sportsdataverse.hockey.liiga | Liiga API (23) |
| SHL | sportsdataverse.hockey.shl | SHL site API (29) |
| HockeyAllsvenskan | sportsdataverse.hockey.ha | HockeyAllsvenskan site API (12) |
| National League | sportsdataverse.hockey.nl | National League app API (17) |
| Ligue Magnus | sportsdataverse.hockey.magnus | Ligue Magnus (11) |
| KHL | sportsdataverse.hockey.khl | KHL (site REST + webcaster API) (25) |
| VHL | sportsdataverse.hockey.vhl | VHL (14) |
| FIBA (digital API and game pages) | sportsdataverse.basketball.fiba_hub | FIBA digital API and game pages (173) |
| Genius Sports LiveStats | sportsdataverse.basketball.genius | Genius Sports LiveStats (59) |
| Sportradar Atrium | sportsdataverse.basketball.atrium | Sportradar Atrium embed API (63) |
| NBL Australia (Rosetta) | sportsdataverse.basketball.nbl_au | NBL Rosetta proxy (NBL, WNBL, NBL1) (22) |
| Spanish FEB | sportsdataverse.basketball.feb | Spanish FEB LiveStats + baloncestoenvivo (11) |
| BBL / DBBL (SCB) | sportsdataverse.basketball.scb | SCB basketball API (BBL, DBBL) (23) |
| Lega Basket Serie A | sportsdataverse.basketball.lba | Lega Basket Serie A (19) |
| ACB | sportsdataverse.basketball.acb | ACB (Liga Endesa) (45) |
| Israeli Premier League | sportsdataverse.basketball.ibba | IBBA (Israeli Premier League) and Segev Stats (22) |
| W League (Japan) | sportsdataverse.basketball.wjbl | W League (Japan) (19) |
| VTB | sportsdataverse.basketball.vtb | VTB United League (38) |
| KBL | sportsdataverse.basketball.kbl | KBL (Korea) (22) |
| B.LEAGUE | sportsdataverse.basketball.bleague | B.LEAGUE (Japan) (14) |
| KZS | sportsdataverse.basketball.kzs | KZS (Basketball Federation of Slovenia) (23) |
| LKL | sportsdataverse.basketball.lkl | LKL (Lithuania) (14) |
| TBF | sportsdataverse.basketball.tbf | TBF app API (BSL, TBL, KBSL) (32) |
| CEBL | sportsdataverse.basketball.cebl | CEBL stats API (12) |
| ABA League | sportsdataverse.basketball.aba | ABA League (12) |
| EASL | sportsdataverse.basketball.easl | EASL (third-party sync server over Sportradar DataCore) (18) |
| BNXT League | sportsdataverse.basketball.bnxt | BNXT League (Sportpress) (28) |
| TPBL | sportsdataverse.basketball.tpbl | TPBL (Taiwan) (16) |
| P. LEAGUE+ | sportsdataverse.basketball.plg | P. LEAGUE+ (Taiwan) and Preciser (19) |
| CBA | sportsdataverse.basketball.cba | CBA data API (China) (27) |
| Basketligaen | sportsdataverse.basketball.dbl | Basketligaen (Denmark, Sportality) (27) |
Errors (0.1.5)
NoDataError— the fetch SUCCEEDED and there is nothing there (a 404, or ESPN's 200-with-code:404body).AssetFetchError— the fetch FAILED and the answer is unknown (403, rate limit, exhausted retries). Never record this as an empty season.ValueError— a 400 / 422: the request itself is wrong, so retrying cannot help.
As of 0.1.5 the hand-written ESPN scrapers and every generated flat-API getter raise rather than returning an error body or an empty dict.
Asking the package about itself
sdv-docs is an MCP server over a prebuilt index of this surface — exact columns,
function signatures, provider endpoints and released datasets:
claude mcp add sdv-docs -- uvx --from 'sportsdataverse[mcp]' sdv-docs
Needs 0.1.5 or newer and Python >= 3.10.
Polars / pandas parser layer
Parser-backed wrappers return a polars DataFrame by default (0.0.54+);
pass return_parsed=False for the raw Dict. The parser layer in
sportsdataverse._common_espn_parsers
(plus matching modules for the MLB and NHL sibling APIs) turns those
payloads into tidy polars (or pandas) DataFrames.
For ESPN wrappers, return_parsed=True is now the default for
parser-backed endpoints. Pass return_parsed=False to recover the
raw Dict, or return_as_pandas=True to get a pandas DataFrame:
from sportsdataverse.nba import espn_nba_team_roster
df = espn_nba_team_roster(team_id=13) # → polars (default)
raw = espn_nba_team_roster(team_id=13, return_parsed=False) # → Dict
pdf = espn_nba_team_roster(team_id=13,
return_as_pandas=True) # → pandas
For NHL / MLB sibling-API wrappers, compose the wrapper with its parser:
from sportsdataverse.nhl import nhl_web_pbp, parse_nhl_web_pbp
df = parse_nhl_web_pbp(nhl_web_pbp(2023030417)) # 331-row polars frame
See the Architecture and Parsers pages for full details.
Installation
pip install sportsdataverse (or uv add sportsdataverse). The
Install & CLI guide covers uv, the optional extras, the
supported Python and polars versions, the sdv command line and the sdv-docs MCP
server.
Our Authors
Citations
To cite the sportsdataverse-py Python package in publications, use:
BibTeX Citation
@misc{gilani_sdvpy_2021,
author = {Gilani, Saiem},
title = {sportsdataverse-py: The SportsDataverse's Python Package for Sports Data.},
url = {https://py.sportsdataverse.org},
season = {2021}
}