nba_api
A Python client for the APIs behind NBA.com
Documentation · Endpoints · Notebooks · Slack
The NBA's stats, in Python. nba_api wraps 130+ stats.nba.com endpoints and the live game feeds behind NBA.com, no API key required, and hands stats back as pandas DataFrames.
- Every corner of NBA.com stats: player and team stats, box scores, game logs, shot charts, play-by-play, standings, and more, with each endpoint's parameters and data sets documented
- Live game data: scoreboard, box scores, play-by-play, and odds, updated during games
- pandas built in: stats come back as DataFrames, dicts, or JSON
- Player and team IDs offline: reference data ships with the package, so lookups need no request
- More than the NBA: many endpoints also cover the WNBA and G League through
league_id
Installation
pip install nba_api
Requires Python 3.10+. Installs requests and pandas.
Quick start
Look up a player or team
Player and team reference data ships with the package, so lookups are instant and work offline.
from nba_api.stats.static import players, teams
players.find_players_by_full_name("donovan mitchell")
# [{'id': 1628378, 'full_name': 'Donovan Mitchell', 'first_name': 'Donovan',
# 'last_name': 'Mitchell', 'is_active': True}]
teams.find_team_by_abbreviation("cle")
# {'id': 1610612739, 'full_name': 'Cleveland Cavaliers', 'abbreviation': 'CLE', ...}
Searches take case-insensitive regular expressions, and player name searches ignore accents ("žydrūnas" finds "Zydrunas Ilgauskas").
Get stats from stats.nba.com
from nba_api.stats.endpoints import playercareerstats
career = playercareerstats.PlayerCareerStats(player_id=1628378) # sends the request
df = career.season_totals_regular_season.get_data_frame()
df[["SEASON_ID", "TEAM_ABBREVIATION", "PTS"]].tail(3)
# SEASON_ID TEAM_ABBREVIATION PTS
# 6 2023-24 CLE 1463
# 7 2024-25 CLE 1701
# 8 2025-26 CLE 1952
Every stats endpoint works the same way: constructing it sends the request, and each data set it returns is an attribute with get_data_frame(), get_dict(), and get_json(). To grab everything at once, use career.get_data_frames() or career.get_dict(). To find the endpoint that has the data you want, see the endpoint guide. The endpoint reference lists every endpoint's parameters and data sets.
Follow live games from cdn.nba.com
from nba_api.live.nba.endpoints import scoreboard
games = scoreboard.ScoreBoard() # today's games
cavs = [
g for g in games.games.get_dict()
if "CLE" in (g["homeTeam"]["teamTricode"], g["awayTeam"]["teamTricode"])
] # tonight's Cavs game, if they play
Live endpoints: ScoreBoard, BoxScore(game_id), PlayByPlay(game_id), and Odds. They return dicts and JSON.
Request options
Every endpoint, stats or live, accepts the same request options:
career = playercareerstats.PlayerCareerStats(
player_id=1628378,
timeout=60, # seconds; default 30
proxy="http://127.0.0.1:8080", # or a list of proxies to pick from at random
headers={"User-Agent": "..."}, # replaces the default headers entirely
get_request=False, # build the request without sending it
)
career.get_request() # send it later
Rate limits and hosting
Requests hanging or timing out?
stats.nba.comthrottles rapid requests and does not respond to many cloud-hosting IP ranges (AWS, GCP, Azure, Colab, and others).
- Pause between requests when fetching in a loop, for example
time.sleep(1). - Increase
timeout. - Route requests through a
proxy, or set theNBA_API_PROXYenvironment variable.
More detail is in the stats examples.
Documentation
- Table of contents: start here
- Stats examples: request options, return formats, static data
- Jupyter notebooks: basic calls, finding games, play-by-play, live data
- Endpoint data structure: the methods every endpoint shares
- Parameters: valid values and defaults
- Using nba_api with AI agents: rules, an endpoint picker, and common errors for AI coding agents
- Changelog
Community
- Slack: join the workspace to get help, help others, share projects, and discuss the API.
- Stack Overflow: ask questions tagged
nba-api.
Contributing
Contributions of all sizes are welcome, from fixing a typo to adding an endpoint. See CONTRIBUTING.md to set up a development environment and open a pull request.
NBA.com does not announce new, changed, or removed endpoints. If you find one, or hit a bug, open an issue.
License and terms of use
nba_api is open source under the MIT License.
Data retrieved with this package comes from NBA.com and is subject to the NBA.com Terms of Use.
nba_api is an independent, community-maintained project and is not affiliated with, endorsed by, or sponsored by the NBA.
Release files for nba-api 1.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| nba_api-1.12.0.tar.gz | 187.1 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nba_api-1.12.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 521.9 kB
Release files / nba_api-1.12.0.tar.gz
| Download URL | nba_api-1.12.0.tar.gz |
|---|---|
| Size | 187.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
72a405ada9acc209a3028cd4f6ab7e075cfc49fd809515f58aaa72b3715924fd
|
|
BLAKE2b-256 checksum How to use checksums |
02a96088b3077c425b17accdbb248a3a871ea453b55094db9533279e8357f1de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logRelease files / nba_api-1.12.0-py3-none-any.whl
| Download URL | nba_api-1.12.0-py3-none-any.whl |
|---|---|
| Size | 334.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f684ec847e41c84776a9b86062a4c26e4edfa31091c3dd5f8d93ecf66ef19053
|
|
BLAKE2b-256 checksum How to use checksums |
e1d034331d1abd4bdfdf620f2523e38f9d38633a419047e1a05030283c9897b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logSecurity for nba-api 1.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for nba_api-1.12.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
