nba-api

Common errors

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

  cause 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)

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

  cause 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]`.

Warnings

• breaking Several 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.
• gotcha NBA.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.
• gotcha A 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.
• gotcha NBA.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.

Install

• pip install nba-api Install latest version

Imports

• 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

Quickstart

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]}...")