Skip to main content

Quickstart

sportsdataverse is a single package that wraps ESPN plus a set of native provider APIs (MLB Stats API, NHL api-web, The Odds API, CBS, Fox, Yahoo, 247Sports). Every method takes a single options object and returns a Promise.

// ESM-only — import the default export (there is no CommonJS `require`):
import sdv from 'sportsdataverse';

The one pattern to learn: pass { parsed: true } to get tidy rows instead of the raw upstream JSON. Without it you get the provider's exact payload; with it you get an array of flat row objects ready for a table or a DataFrame.

Your first call — raw vs parsed​

Every endpoint accepts the same { parsed } switch. Here is the NBA scoreboard both ways:

import sdv from 'sportsdataverse';

// Raw ESPN payload (nested events[] etc.)
const raw = await sdv.nba.espnNbaScoreboard({});
console.log(raw.events.length);

Open in playground ▶

import sdv from 'sportsdataverse';

// Tidy: one flat row per game.
const rows = await sdv.nba.espnNbaScoreboard({ parsed: true });
console.table(rows.slice(0, 5));

Open in playground ▶

tip

The same { parsed: true } flag works on every method across every league and provider. See the per-area pages in this section, or the ESPN reference for the full method list.

A two-step workflow​

Most real work is "get a list, then drill into one item". Here we take a game id off the scoreboard and pull just the team-boxscore sub-frame from the summary dispatcher:

import sdv from 'sportsdataverse';

const sb = await sdv.nba.espnNbaScoreboard({});
const eventId = sb.events[0].id;

const teamBox = await sdv.nba.espnNbaSummary({
  event_id: eventId,
  parsed: true,
  section: 'boxscore_team',
});
console.table(teamBox);

Open in playground ▶

The summary endpoint returns 21 sub-frames (boxscore_team, boxscore_player, plays, leaders, …); pass section to pick one, or omit it to get the whole dict.

Run it live​

The cell below runs the published npm package end to end — scoreboard, then a summary drill-down — right in your browser:

const sdv = (await import('sportsdataverse')).default;

// 1) today's NBA slate
const sb = await sdv.nba.espnNbaScoreboard({});
const id = sb.events[0].id;

// 2) the team boxscore for the first game, tidied
const teamBox = await sdv.nba.espnNbaSummary({
event_id: id,
parsed: true,
section: 'boxscore_team',
});

teamBox;
note

RunKit cells install sportsdataverse from npm, so the v3 method names above (espnNbaScoreboard, provider namespaces, the parsed/section options) light up once v3 is published. Until then the embed may resolve v2, whose surface differs. Copy any snippet into Node to run it against your installed version.

Real parsed output (frozen at build)​

The tables below are real parser output, rendered at build time from committed ESPN fixtures and frozen into this page. They are deterministic (fixture-driven, no network) so CI reproduces them exactly — the same injector could instead run live and refresh against today's data. Regenerate with npm run docs:examples.

sdv.nba.espnNbaScoreboard({ parsed: true }) — one row per game.

game_iduiddatenameshort_nameseason_year
401704871s:40l:46e:4017048712024-12-01T20:30ZOrlando Magic at Brooklyn NetsORL @ BKN2025
401704872s:40l:46e:4017048722024-12-01T20:30ZIndiana Pacers at Memphis GrizzliesIND @ MEM2025
401704873s:40l:46e:4017048732024-12-01T23:00ZBoston Celtics at Cleveland CavaliersBOS @ CLE2025
401704874s:40l:46e:4017048742024-12-01T23:00ZNew Orleans Pelicans at New York KnicksNO @ NY2025
401704875s:40l:46e:4017048752024-12-01T23:00ZMiami Heat at Toronto RaptorsMIA @ TOR2025
401704876s:40l:46e:4017048762024-12-02T00:00ZOklahoma City Thunder at Houston RocketsOKC @ HOU2025
401704877s:40l:46e:4017048772024-12-02T01:00ZLos Angeles Lakers at Utah JazzLAL @ UTAH2025
401704878s:40l:46e:4017048782024-12-02T02:00ZDallas Mavericks at Portland Trail Bl…DAL @ POR2025

10 rows total — first 8 shown, 50 cols total — first 6 shown.

sdv.nba.espnNbaStandings({ parsed: true }) — one row per team.

group_namegroup_abbreviationteam_idteam_nameteam_abbreviationteam_display_name
Eastern ConferenceEast19MagicORLOrlando Magic
Eastern ConferenceEast15BucksMILMilwaukee Bucks
Eastern ConferenceEast14HeatMIAMiami Heat
Eastern ConferenceEast2076ersPHIPhiladelphia 76ers
Eastern ConferenceEast11PacersINDIndiana Pacers
Eastern ConferenceEast5CavaliersCLECleveland Cavaliers
Eastern ConferenceEast18KnicksNYNew York Knicks
Eastern ConferenceEast1HawksATLAtlanta Hawks

30 rows total — first 8 shown, 31 cols total — first 6 shown.

sdv.nba.espnNbaTeamRoster({ team_id: 13, parsed: true }) — one row per player.

iduidguidalternate_ids_sdrfirst_namelast_name
4278129s:40l:46a:42781299af41ea8-a24c-025f-a63f-8263fbf0ca664278129DeandreAyton
3945274s:40l:46a:3945274583794eb-0f38-9bbd-3e25-9dd33b7f83b83945274LukaDoncic
4066648s:40l:46a:406664840c1bcf6-675b-f217-f97c-1d628073f9274066648RuiHachimura
4397077s:40l:46a:43970774cd92ac1-73ce-653d-c3b1-9c68e9c7a4d04397077JaxsonHayes
4683774s:40l:46a:4683774456f71fd-2ce5-3f50-8d0d-f30c0159789d4683774BronnyJames
1966s:40l:46a:19661f6592b3-ff53-d321-8dc5-6038d48c17862126588LeBronJames
3913174s:40l:46a:3913174668a6a14-4003-d79c-c252-0ece0a960d363913174LukeKennard
2960236s:40l:46a:2960236d06ad722-26ff-5865-1433-061e2e6fbb322960236MaxiKleber

17 rows total — first 8 shown, 68 cols total — first 6 shown.

Where next​