{"id":7442,"library":"nba-api","title":"nba-api","description":"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.","status":"active","version":"1.11.4","language":"en","source_language":"en","source_url":"https://github.com/swar/nba_api","tags":["NBA","basketball","sports","API client","data"],"install":[{"cmd":"pip install nba-api","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for making HTTP requests to the NBA.com API.","package":"requests","optional":false},{"reason":"Required by the underlying data structures.","package":"numpy","optional":false},{"reason":"Optional, but recommended for convenient data manipulation and outputting results as DataFrames.","package":"pandas","optional":true}],"imports":[{"symbol":"PlayerCareerStats","correct":"from nba_api.stats.endpoints import playercareerstats"},{"symbol":"get_players","correct":"from nba_api.stats.static import players"},{"symbol":"ScoreBoard","correct":"from nba_api.live.nba.endpoints import scoreboard"}],"quickstart":{"code":"from nba_api.stats.static import players\nfrom nba_api.stats.endpoints import playercareerstats\n\n# Find LeBron James' player ID\nnba_players = players.get_players()\nlebron = [player for player in nba_players if player['full_name'] == 'LeBron James'][0]\nlebron_id = lebron['id']\n\n# Get LeBron James' career stats\ncareer_stats = playercareerstats.PlayerCareerStats(player_id=lebron_id)\n\n# Access data as a pandas DataFrame (requires pandas installed)\ncareer_df = career_stats.get_data_frames()[0]\nprint(f\"LeBron James' Career Stats (first 5 rows):\\n{career_df.head()}\")\n\n# Access data as a JSON dictionary\ncareer_json = career_stats.get_json()\n# print(f\"\\nLeBron James' Career Stats (JSON excerpt):\\n{career_json[:200]}...\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"v1.11.3 and later"},{"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.","message":"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).","severity":"gotcha","affected_versions":"Prior to v1.11.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"v1.11.2 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"AttributeError: module 'nba_api.stats.endpoints' has no attribute 'BoxScorePlayerTrackV2'"},{"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.","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.","error":"urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='stats.nba.com', port=443): Read timed out. (read timeout=30)"},{"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]`.","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.","error":"KeyError: 'Some_Expected_Column_Name' or unexpected data in DataFrame columns for BoxScore endpoints."}]}