nba-api

library1.11.4pypypi✓ verified 85d ago

nba-api is a free and active Python client package designed to access statistics from the Official NBA stats page (nba.com). It provides a robust interface for developers to retrieve data on NBA teams, seasons, players, and games in various formats, including pandas DataFrames. The library is actively maintained with frequent updates to adapt to changes in the underlying NBA.com API.

http-networking data

pip install nba-api

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · NBA-API

nba-api

http-networkingpythonv1.11.4

Install

8.4s avg

Import

1601ms

Disk

170MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.11.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.643s · 171.3MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 8.4s · import 1.558s · 164MB

170MB installed

● package 170MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PlayerCareerStats

✓ from nba_api.stats.endpoints import playercareerstats

get_players

✓ from nba_api.stats.static import players

ScoreBoard

✓ from nba_api.live.nba.endpoints import scoreboard

This quickstart demonstrates how to fetch a player's ID using the static module and then retrieve their career statistics from an endpoint. It shows how to access the data as a pandas DataFrame, which is a common and convenient way to work with the results.

from nba_api.stats.static import players from nba_api.stats.endpoints import playercareerstats # Find LeBron James' player ID nba_players = players.get_players() lebron = [player for player in nba_players if player['full_name'] == 'LeBron James'][0] lebron_id = lebron['id'] # Get LeBron James' career stats career_stats = playercareerstats.PlayerCareerStats(player_id=lebron_id) # Access data as a pandas DataFrame (requires pandas installed) career_df = career_stats.get_data_frames()[0] print(f"LeBron James' Career Stats (first 5 rows):\n{career_df.head()}") # Access data as a JSON dictionary career_json = career_stats.get_json() # print(f"\nLeBron James' Career Stats (JSON excerpt):\n{career_json[:200]}...")

Debug

Known issues

breakingSeveral API endpoints, including `BoxScorePlayerTrackV2` and `PlayerFantasyProfile`, have been removed due to NBA.com API discontinuation. `PlayByPlayV2` and `ScoreboardV2` are also deprecated, requiring migration to their `V3` counterparts.

fix

Review the `nba-api` release notes for removed and deprecated endpoints. Migrate your code to use the recommended `V3` versions (e.g., `BoxScorePlayerTrackV3`, `PlayByPlayV3`, `ScoreboardV3`) or alternative endpoints.

affects: v1.11.3 and later

gotchaNBA.com has updated its HTTP header requirements, causing requests from older `nba-api` versions to be blocked with timeout or forbidden errors (e.g., outdated User-Agent).

fix

Upgrade `nba-api` to version 1.11.4 or newer. This version includes updated request headers to ensure compatibility with NBA.com's API.

affects: Prior to v1.11.4

gotchaA critical bug fix in v1.11.2 altered the dataset order returned by several parser functions (e.g., `BoxScoreAdvancedV3`, `BoxScoreDefensiveV2`, `BoxScoreFourFactorsV3`). If your code expects a specific order (e.g., `[0]` for player stats, `[1]` for team stats), it might now receive incorrect data.

fix

After upgrading to v1.11.2+, verify the order of datasets returned by affected `BoxScore` endpoints using `endpoint.get_data_frames()`. Adjust your indexing (`[0]`, `[1]`, etc.) accordingly to match the corrected order.

affects: v1.11.2 and later

gotchaNBA.com's API can aggressively rate-limit or temporarily block IP addresses, especially from cloud environments, leading to `Read timed out` or `403 Forbidden` errors for multiple consecutive requests.

fix

Implement delays (e.g., `time.sleep(1)` to `time.sleep(3)`) between requests, particularly when looping through multiple API calls. For cloud deployments, consider using proxies as NBA.com may block known cloud IP ranges.

affects: All versions

Errors

Common errors & fixes

AttributeError: module 'nba_api.stats.endpoints' has no attribute 'BoxScorePlayerTrackV2'

You are attempting to use an NBA API endpoint that has been removed from the `nba-api` library due to discontinuation by NBA.com.

fix

Update your code to use the replacement endpoint, `BoxScorePlayerTrackV3`. For other removed endpoints like `PlayerFantasyProfile`, there may not be a direct replacement; refer to `nba-api` release notes for guidance.

urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='stats.nba.com', port=443): Read timed out. (read timeout=30)

Your requests are either being blocked by NBA.com due to an outdated `User-Agent` header, or you are hitting aggressive rate limits, especially common from cloud IP addresses.

fix

Upgrade `nba-api` to v1.11.4+ for updated headers. If the issue persists, introduce `time.sleep()` delays between requests (e.g., 1-3 seconds) and consider running from a local IP or using proxies if deployed on a cloud server.

KeyError: 'Some_Expected_Column_Name' or unexpected data in DataFrame columns for BoxScore endpoints.

In `nba-api` v1.11.2, the order of datasets returned by certain `BoxScore` parsers (e.g., `BoxScoreAdvancedV3`, `BoxScoreDefensiveV2`, `BoxScoreFourFactorsV3`) was fixed. Your code might be accessing data from the wrong index in the list of DataFrames.

fix

Ensure you are using `nba-api` v1.11.2 or newer. After calling an endpoint, inspect the list of DataFrames returned by `get_data_frames()` (e.g., `endpoint.get_data_frames()`) to confirm the current order and adjust your indexing accordingly. For example, player stats might be `[0]` and team stats `[1]`.

Upgrade

Version history

1.11.4latest on PyPI · released Feb 20, 2026

Audit

Dependencies

requestsrequiredRequired for making HTTP requests to the NBA.com API.

numpyrequiredRequired by the underlying data structures.

pandasoptionalOptional, but recommended for convenient data manipulation and outputting results as DataFrames.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/swar/nba_api ↗

packagehttps://pypi.org/project/nba-api/ ↗

docshttps://github.com/swar/nba_api/blob/master/README.md ↗