What it is

nba_api is a Python package that acts as an API client for the web APIs used by NBA.com. It lives in the Python developer tools ecosystem and is distributed as an open-source project under the MIT license. The package is designed to make official NBA.com data accessible through Python code, while also documenting the endpoints and parameters that the site exposes.

The concrete problem it solves is the difficulty of calling NBA.com data endpoints directly. Without this package, a developer or analyst must discover endpoint URLs, construct parameters, send HTTP requests, and parse raw responses. nba_api wraps that work in Python classes for official stats and live data, and it provides examples and documentation so users can retrieve player, game, team, scoreboard, and play-by-play information more quickly.

Key capabilities

• Accesses NBA.com official stats endpoints through Python classes, including player career statistics.
• Accesses NBA.com live data endpoints, including the current scoreboard.
• Returns data as JSON, Python dictionaries, or optional Pandas DataFrames when pandas is installed.
• Supports proxy configuration, custom headers, and timeout settings for HTTP requests.
• Provides static data sets for players and teams to reduce repeated HTTP requests for common identifiers.
• Maintains detailed endpoint documentation and analysis for many NBA.com API endpoints.
• Includes practical Jupyter Notebook examples for basic calls, game lookup, play-by-play data, and live game data.

Who uses it and how

• Python analysts use it to pull official NBA.com stats into notebooks or scripts for basketball analysis.
• Developers use it to integrate scoreboard and live game data into applications without hand-writing HTTP calls.
• Researchers and fans use it to retrieve player career data, team data, and play-by-play records for further processing.
• Contributors use the project to report new, changed, or deprecated endpoints because NBA.com does not publish a stable API change feed.

Getting started

Install the package with pip install nba_api. It requires Python 3.10 or newer, plus the requests and numpy packages; pandas is optional unless you want DataFrame output.

When to use it — and when not to

Use nba_api when you need a Python client for NBA.com stats and live endpoints and you value endpoint documentation, examples, and community help. Avoid it if you need a guaranteed stable external API, because NBA.com can change or remove endpoints without notice and users must report broken endpoints through GitHub issues. It is not a hosted database or storage service, so users must run their own Python environment and handle any data storage, transformation, or production scheduling themselves.

pip install nba_api

from nba_api.stats.endpoints import playercareerstats

# Nikola Jokić
career = playercareerstats.PlayerCareerStats(player_id='203999')

# pandas data frames (optional: pip install pandas)
career.season_totals_regular_season.get_data_frame()

# json
career.get_json()

# dictionary
career.get_dict()

from nba_api.live.nba.endpoints import scoreboard

# Today's Score Board
games = scoreboard.ScoreBoard()

# json
games.get_json()

# dictionary
games.get_dict()