sportsdataverse-js

sportsdataverse is the SportsDataverse's Node.js client for sports data. As of v3.0.0 it is a cross-league ESPN client: a single, uniform surface of 116 endpoint wrappers generated for 29 leagues — play-by-play, box scores, schedules, rosters, standings, rankings, odds, and more — plus the original hand-written scrapers it has always shipped.

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;

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 116 endpoints × 29 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;                          // 116 endpoint definitions
Object.keys(sdv.nba).filter((k) => k.startsWith('espnNba'));  // every NBA wrapper

Where to next

Tutorials — guided, copy-pasteable walkthroughs.
Reference — every espn<League><Endpoint> wrapper, by league.
Playground — run live ESPN calls in your browser.
API (TypeDoc) — the full typed module surface.

Installation​

Quick start​

Parameters: snake_case or camelCase​

Legacy methods still work​

How the cross-league surface works​

Where to next​

License​