Nba Data

NBA 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 with a Python version error, the package requires Python 3.10+. Find a compatible Python:

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.

Quick Start

Prefer the CLI — it avoids Python import path issues:

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

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-18 → 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 NBA season runs October–June. If the current month is October–December, the active season year matches the current year. If January–June, the active season started the previous calendar year (use that year as the season).

Commands

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

Shaping Long NBA Stats Results

get_nbastats_game_log, get_nbastats_team_stats and get_nbastats_shot_chart accept sort_by, descending, limit and fields, so you can ask for the rows and columns you need instead of a full season:

# Miami's five highest-scoring games, four columns each
sports-skills nba get_nbastats_game_log --season=2025 --team=MIA \
  --sort_by=pts --limit=5 --fields=wl,pts

• 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.

Column names are NBA.com's, lowercased (pts, fg3m, plus_minus, shot_distance).

Using ESPN and NBA Stats Together

The get_nbastats_* commands read stats.nba.com — the analytics layer (advanced ratings, shot coordinates, deep history) that ESPN's endpoints do not carry. The two sources use unrelated id systems:

• Game ids. NBA Stats uses 10-digit ids ("0022400061"); ESPN uses event ids ("401704627"). There is no shared column — join on the game date plus the two team abbreviations.
• Team abbreviations. Six teams are spelled differently: ESPN GS/NO/NY/ SA/UTAH/WSH vs NBA GSW/NOP/NYK/SAS/UTA/WAS. Every get_nbastats_* team filter accepts either spelling, and result rows carry both (team_abbreviation and team_abbreviation_espn).
• Player ids. NBA person ids ("203999") and ESPN athlete ids are unrelated. Resolve names with find_nba_player; ASCII spellings match accented names ("jokic" finds "Nikola Jokić").
• Seasons. Pass the starting year (season=2024 means 2024-25). The NBA form ("2024-25") is also accepted.
• Dates. game_date is YYYY-MM-DD in game logs and shot charts alike.

stats.nba.com throttles by client and volume: heavy bursts (and many datacenter/cloud IPs) get silently tarpitted rather than refused. The commands fail fast with an explanatory error when that happens — wait before retrying; do not hammer. Responses are cached, and the ESPN-backed and get_live_* commands are unaffected.