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 yourself​

The two-step script above, as a ready-to-run Node sandbox (it installs the published npm package and hits ESPN live — no API key needed):

Opens a Node sandbox in a new tab with this script as index.mjs; runs live (no API key for ESPN).

Every tutorial carries the same button under its script. To run a snippet in the page itself, see live code blocks; for any single endpoint with editable params, the Playground.

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​