NFL recipes

Pro football lives under sdv.nfl, which spans two surfaces: the ESPN wrappers (espnNfl*) — scoreboard, rosters, standings, and the summary dispatcher (for football the summary additionally unrolls drives into a long-form play frame) — and the native NFL.com "Shield" API (nflApi*, host api.nfl.com) for standings, rosters, weekly game details, and more. Pass { parsed: true } for tidy rows.

Scoreboard

import sdv from 'sportsdataverse';

const games = await sdv.nfl.espnNflScoreboard({ parsed: true });
console.table(games);

Run it inline — edit a param and hit Run ▶ for live, parsed rows:

Loading live cell…

Open in playground ▶

Team roster

team_id 12 is the Chiefs.

import sdv from 'sportsdataverse';

const roster = await sdv.nfl.espnNflTeamRoster({ team_id: 12, parsed: true });
console.table(roster);

Open in playground ▶

Box score from a game id

import sdv from 'sportsdataverse';

const sb = await sdv.nfl.espnNflScoreboard({});
const id = sb.events[0].id;

const teamBox = await sdv.nfl.espnNflSummary({
  event_id: id,
  parsed: true,
  section: 'boxscore_team',
});
console.table(teamBox);

Open in playground ▶

Standings from the NFL.com Shield API (native)

api.nfl.com is NFL.com's own data API. A bearer token is minted automatically before each call — no credentials required. Scope with season, season_type (REG / POST / PRE), and week.

import sdv from 'sportsdataverse';

const standings = await sdv.nfl.nflApiStandings({
  season: 2024,
  season_type: 'REG',
  week: 1,
  parsed: true,
});
console.table(standings);

The same call, live and inline — a native api.nfl.com request, parsed to one row per team. season_type is a dropdown (REG / POST / PRE):

Loading live cell…

Open in playground ▶

Frozen output (real parser rows, no network)

The table below is real parse_nfl_standings output, rendered at build time from a committed sample fixture and frozen into this page (deterministic — CI reproduces it exactly). Regenerate with npm run docs:examples.

sdv.nfl.nflApiStandings({ season: 2024, parsed: true }) — the native NFL.com Shield standings, one row per team (sample fixture).

team_abbreviation	team_full_name	conference	division	wins	losses
KC	Kansas City Chiefs	AFC	AFC West	15	2
BUF	Buffalo Bills	AFC	AFC East	13	4
DET	Detroit Lions	NFC	NFC North	15	2
PHI	Philadelphia Eagles	NFC	NFC East	14	3

4 rows, 12 cols total — first 6 shown.

Rosters & weekly game details (native)

import sdv from 'sportsdataverse';

// every active roster for a season
const rosters = await sdv.nfl.nflApiRosters({ season: 2024, parsed: true });
console.table(rosters.slice(0, 10));

// rich weekly game details (drive chart, scoring, standings)
const details = await sdv.nfl.nflApiWeeklyGameDetails({
  season: 2024,
  season_type: 'REG',
  week: 1,
  parsed: true,
});
console.table(details);

Open rosters in playground ▶

tip

Full method + parameter tables: NFL reference (covers both the ESPN and NFL.com Shield families).