Nfl Data

NFL Data

Before writing queries, consult references/api-reference.md for endpoints, ID conventions, and data shapes.

Setup

Before first use, check if the CLI is available:

which sports-skills || pip install sports-skills

If pip install fails (package not found or Python version error), install from GitHub:

pip install git+https://github.com/machina-sports/sports-skills.git

The package requires Python 3.10+. If your default Python is older, use a specific version:

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

No API keys required.

For nflverse-backed commands (get_nflverse_*), install the NFL extra:

pip install sports-skills[nfl]

On Python 3.10+ this installs nflreadpy (the preferred backend) plus pyarrow, which is needed for most nflverse data beyond schedules. On Python 3.9 it installs nfl-data-py instead, since nflreadpy requires 3.10+.

The nfl-data-py backend is a reduced fallback: it cannot serve get_nflverse_team_stats, which returns an explanatory error there. Use Python 3.10+ for full nflverse coverage.

Quick Start

Prefer the CLI — it avoids Python import path issues:

sports-skills nfl get_scoreboard
sports-skills nfl get_standings --season=2025
sports-skills nfl get_teams

Python SDK (alternative):

from sports_skills import nfl

scores = nfl.get_scoreboard({})
standings = nfl.get_standings({"params": {"season": "2025"}})

CRITICAL: Before Any Query

CRITICAL: Before calling any data endpoint, verify:

• Season year is derived from the system prompt's currentDate — never hardcoded.
• If only a team name is provided, call get_teams to resolve the team ID before using team-specific commands.

Choosing the Season

Derive the current year from the system prompt's date (e.g., currentDate: 2026-02-16 → current year is 2026).

• If the user specifies a season, use it as-is.
• If the user says "current", "this season", or doesn't specify: The NFL season runs September–February. If the current month is March–August, use season = current_year (upcoming season). If September–February, the active season started in the previous calendar year if you're in Jan/Feb, otherwise current year.

Commands

See references/api-reference.md for full parameter lists and return shapes.

Do not infer a bye from an empty get_schedule response: inspect its coverage block, whose completeness is unknown or partial, never complete. For a whole team season use get_team_schedule; season-only get_schedule is refused because ESPN's scoreboard mixes and truncates it. An absent or unresolved injury record is not evidence that a player is healthy.

Fantasy Trending (Sleeper)

get_fantasy_trending reads Sleeper's public trending endpoint: the NFL players most added (or dropped) in Sleeper fantasy leagues over a recent window.

sports-skills nfl get_fantasy_trending --trend_type=add --lookback_hours=24 --limit=10
sports-skills nfl get_fantasy_trending --trend_type=drop

• trend_type: add (default) or drop. lookback_hours: whole hours, 1-168 (default 24). limit: 1-100 (default 10).
• count is the add/drop tally Sleeper's trending API reports for the player over the window. It is a popularity signal, not a projection, ranking, or betting edge — say so when reporting it.
• Player IDs are sleeper_player_id, Sleeper's own namespace — keep them as the identifier. There is no mapping to ESPN athlete IDs or nflverse GSIS IDs: do not attach one, and do not present a name or team match against another provider as the same confirmed player.
• name_resolved: false means Sleeper's player catalog had no name for that ID. team and position are resolved separately and may still be filled in. If the catalog itself could not be fetched, catalog_status is unavailable and warnings[] says why; counts and IDs are still valid.
• Report freshness from source.trending_fetched_at. Trending results are cached in memory for 5 minutes, within one process only — each new CLI call fetches them again. Sleeper's player catalog (trimmed to IDs, names, teams and positions) is also saved under $XDG_CACHE_HOME/sports-skills/sleeper/ (default ~/.cache/...) and reused across processes until 24 hours after it was fetched, since Sleeper asks clients to fetch it at most once a day. That disk cache is best effort: if it cannot be written, the call still succeeds and the next process fetches the catalog again.

Shaping Wide nflverse Results

nflverse tables are wide: one week of get_nflverse_player_stats is ~960 rows with 100+ stat columns (millions of characters). Every get_nflverse_* command accepts sort_by, descending, limit and fields so you can ask for just the rows you need:

# Week 5 passing leaders, 5 rows, 2 stat columns
sports-skills nfl get_nflverse_player_stats --season=2025 --week=5 --position=QB \
  --sort_by=passing_yards --limit=5 --fields=passing_yards,attempts

• sort_by: one column to sort by. Numbers (and numeric strings) sort numerically; missing values always go last.
• descending: true (default) or false; only used with sort_by.
• limit: positive integer, applied after sorting.
• fields: comma-separated keep-list. The identity columns below and the sort_by column are always kept.
• An unknown sort_by/fields column returns an error listing the valid columns.
• With any of these set, the response adds total_rows (matching rows before limit) and returned_rows. With none set, output is unchanged. They are applied after the fetch, so they never change the upstream request or its replay entry.
• Stat columns inside stats (e.g. passing_yards) are addressable directly; fields keeps stats as an object holding only the selected keys.

Using ESPN and nflverse Together

The two backends use different identifier systems. get_nflverse_schedule is the bridge: each event carries espn_event_id, which is exactly the ESPN event ID.

To combine nflverse analytics (EPA, win probability, betting lines) with ESPN detail (box scores, drives) for the same game:

1. Call get_nflverse_schedule(season=..., week=...).
2. Read espn_event_id off the event you want.
3. Pass it as event_id to get_game_summary, get_play_by_play, or get_win_probability.

Two things that do not line up automatically:

• Team abbreviations. ESPN uses LAR and WSH; nflverse uses LA and WAS. The get_nflverse_* functions accept either and translate. Going the other way (nflverse → ESPN), resolve via get_teams.
• Player IDs. ESPN athlete IDs and nflverse GSIS IDs (00-0033873) are unrelated, and no crosswalk is available. Match on name plus team instead.

Field to watch on schedule rows: total is the combined points actually scored, while total_line is the betting over/under. Use total_line for market work.