sportsdataverse-js
sportsdataverse is the SportsDataverse's Node.js client for sports data. As
of v4.0.0 it is a cross-league ESPN client: a single, uniform surface of
126 endpoint wrappers generated for 40 leagues —
play-by-play, box scores, schedules, rosters, standings, rankings, odds, and more —
plus 1060 native-API wrappers across 27 families
(league APIs such as MLB Stats, NHL, NFL.com, MLS, NWSL and stats.nba.com, and
providers such as The Odds API, 247Sports, CBS, Fox, Yahoo, HockeyTech, BartTorvik,
On3 and American Soccer Analysis), 326 dataset loaders over the
SportsDataverse release assets, and the original hand-written scrapers it has
always shipped. The counts on this page come from the generated
sources matrix, so they track the code.
It is the Node.js sister to the sportsdataverse-py
Python package and the SportsDataverse R packages
(hoopR, wehoop, cfbfastR, fastRhockey, …).
Installation
npm install sportsdataverse
Requirements: Node ≥ 20.18.1. The package is ESM-only and ships TypeScript declarations.
import sdv from 'sportsdataverse';
Using CommonJS? Load it with a dynamic import:
const sdv = (await import('sportsdataverse')).default;
Sources covered
One card per upstream source — host, families, what you need to authenticate, where the endpoint definitions live, and how much of the returns documentation is verified. The Sources & coverage page has the legend.
23 sources · ESPN 126 endpoints × 40 leagues · 1060 native wrappers across 27 families · 326 dataset loaders
- ESPN site v2 25
- ESPN core v2 90
- ESPN web v3 5
- ESPN fitt v3 1
- ESPN cdn 5
- wrappers
- 126
- leagues
- 40 leagues
- parity
- —
- described
- 67%
Site v2 / Core v2 / Web v3 / FPI / CDN, one wrapper set bound on every league.
- NBA Stats API (stats.nba.com) 128
- wrappers
- 128
- leagues
- sdv.nba
- parity
- 126/126
- described
- 97%
NBA, G League and Summer League by `league_id`; TLS-impersonating transport, residential IP.
- WNBA Stats API (stats.wnba.com) 111
- wrappers
- 111
- leagues
- sdv.wnba
- parity
- 110/110
- described
- 97%
Same transport as stats.nba.com.
- MLB Stats API 78
- wrappers
- 78
- leagues
- sdv.mlb
- parity
- 46/46
- described
- 99%
- Baseball Savant / Statcast 39
- wrappers
- 39
- leagues
- sdv.mlb
- parity
- 1/37
- described
- 100%
CSV / JSON / HTML leaderboards, search and game feeds.
- NHL api-web (game feed) 27
- NHL EDGE (player tracking) 35
- NHL Stats REST 21
- NHL Records 44
- wrappers
- 127
- leagues
- sdv.nhl
- parity
- 100/108
- described
- 96%
api-web game feed, EDGE tracking, Stats REST and Records.
- NFL.com Shield API 15
- wrappers
- 15
- leagues
- sdv.nfl
- parity
- 0/11
- described
- 100%
Bearer token minted by the runtime; nothing to configure.
- NFL Pro (Next Gen Stats) 16
- wrappers
- 16
- leagues
- sdv.nfl
- parity
- 0/16
- described
- 97%
- PFF Developer API 68
- wrappers
- 68
- leagues
- sdv.nfl
- parity
- 0/67
- described
- 100%
- KenPom 30
- wrappers
- 30
- leagues
- sdv.mbb
- parity
- —
- described
- —
- BartTorvik (T-Rank) 5
- BartTorvik women's (T-Rank) 1
- wrappers
- 6
- leagues
- sdv.torvik
- parity
- —
- described
- 100%
Men's and women's T-Rank.
- On3 Recruit Database 78
- wrappers
- 78
- leagues
- sdv.on3
- parity
- 23/23
- described
- 100%
- 247Sports RDB 12
- 247Sports site pages 35
- wrappers
- 47
- leagues
- sdv.sports247
- parity
- 12/47
- described
- 89%
Guest JWT minted by the runtime; browser-impersonating transport (`npm install impit`).
- CBS Sports 82
- wrappers
- 82
- leagues
- sdv.cbs
- parity
- —
- described
- 96%
- Fox Sports 38
- wrappers
- 38
- leagues
- sdv.fox
- parity
- —
- described
- 100%
- Yahoo Sports 107
- Yahoo Sports (scores) 2
- wrappers
- 109
- leagues
- sdv.yahoo
- parity
- —
- described
- 63%
Stats graph + scores.
- The Odds API 10
- wrappers
- 10
- leagues
- sdv.odds
- parity
- —
- described
- 100%
- HockeyTech / LeagueStat 16
- wrappers
- 16
- leagues
- sdv.hockeytech
- parity
- —
- described
- 100%
PWHL + 19 junior / minor leagues by `league`; public per-league keys are built in.
- American Soccer Analysis 16
- wrappers
- 16
- leagues
- sdv.asa
- parity
- 7/16
- described
- 100%
- MLS web API 12
- wrappers
- 12
- leagues
- sdv.mls
- parity
- 9/12
- described
- 98%
- NWSL (StatsPerform SDP) 9
- wrappers
- 9
- leagues
- sdv.nwsl
- parity
- 6/8
- described
- 97%
- 247Sports 25
- wrappers
- 25
- leagues
- sdv.recruiting
- parity
- —
- described
- 100%
`api.247sports.com` answers HTTP 500; every method is deprecated in favour of 247Sports.
- sdv.cfb loaders 71
- sdv.mbb loaders 34
- sdv.mlb loaders 34
- sdv.nba loaders 42
- sdv.nfl loaders 29
- sdv.nhl loaders 27
- sdv.pwhl loaders 21
- sdv.wbb loaders 34
- sdv.wnba loaders 34
- loaders
- 326
- leagues
- sdv.cfb, sdv.mbb, sdv.mlb, sdv.nba, sdv.nfl, sdv.nhl, sdv.pwhl, sdv.wbb, sdv.wnba
- parity
- —
- described
- 98%
Pre-built parquet datasets (`load*`) published as GitHub release assets.
Quick start
Every league is a namespace on the default export. The cross-league ESPN
endpoints follow one naming rule — espn<League><Endpoint> (camelCase). Every
method also has a snake_case alias (espn_nba_scoreboard) for parity with the
Python / R packages:
import sdv from 'sportsdataverse';
// Today's NBA scoreboard
const board = await sdv.nba.espnNbaScoreboard({});
// A single game summary (box score + plays + win probability + ...)
const game = await sdv.nba.espnNbaSummary({ event_id: 401584793 });
// A team's roster
const roster = await sdv.nfl.espnNflTeamRoster({ team_id: 12 });
The same methods exist on every league, so switching sports is a one-token change:
await sdv.nfl.espnNflScoreboard({ week: 1, season_type: 2 });
await sdv.nhl.espnNhlScoreboard({});
await sdv.cfb.espnCfbRankings({}); // NCAA-scoped endpoint
await sdv.wnba.espnWnbaStandings({ season: 2024 });
Multi-league sports (soccer, cricket) take an extra league slug:
// English Premier League scoreboard
await sdv.soccer.espnSoccerScoreboard({ league: 'eng.1' });
// La Liga, same call
await sdv.soccer.espnSoccerScoreboard({ league: 'esp.1' });
Parameters: snake_case or camelCase
Every wrapper accepts either spelling, so it reads naturally from JS or matches the Python/R sister packages:
await sdv.nfl.espnNflTeamSchedule({ team_id: 12, season: 2024 });
await sdv.nfl.espnNflTeamSchedule({ teamId: 12, season: 2024 }); // identical
Legacy methods still work
Every pre-3.0 convenience method is preserved and merged alongside the generated wrappers:
const pbp = await sdv.nba.getPlayByPlay(401584793);
const box = await sdv.cfb.getBoxScore(401628319);
How the cross-league surface works
The ESPN client is generated from a single YAML source of truth
(tools/codegen/endpoints/*.yaml). Each endpoint is wrapped once and bound to
every applicable league, so the 126 endpoints × 40 leagues
stay perfectly in sync. Endpoints are grouped into scopes:
| Scope | Applies to | Examples |
|---|---|---|
universal | every league | scoreboard, summary, team_roster, standings |
ncaa | college leagues | rankings, conference groupings |
football | NFL + CFB + UFL | drive/play detail, betting endpoints |
mlb | MLB | baseball-specific feeds |
You can introspect the whole surface at runtime:
import sdv, { LEAGUES, WRAPPERS } from 'sportsdataverse';
LEAGUES.map((l) => l.prefix); // ['nba','nfl','nhl',...,'soccer','cricket','ufl',...]
WRAPPERS.length; // one definition per endpoint short
Object.keys(sdv.nba).filter((k) => k.startsWith('espnNba')); // every NBA wrapper
Where to next
- Quickstart — from an empty folder to a parsed table.
- Sources & coverage — every upstream source, with auth, ownership and parity.
- How this library is built — vendored vs JS-owned vs hand-written, per surface.
- Guides and Tutorials — recipes, and runnable scripts with frozen output.
- Reference — every
espn<League><Endpoint>wrapper, by league, plus the native families. - Utilities — parsers, analytics, odds math, transforms and errors.
- Playground — run live ESPN calls in your browser.
- API (TypeDoc) — the full typed module surface.
License
MIT © Saiem Gilani, part of the SportsDataverse.