nba_api
An API client for NBA.com. nba_api makes the APIs behind NBA.com easy to call from Python and documents them extensively — 130+ stats.nba.com endpoints, the live game data feeds on cdn.nba.com, and bundled player and team reference data.
Installation
pip install nba_api
Requires Python 3.10+. Installs requests, numpy, and pandas.
Quick start
Find a player or team (no HTTP request)
Player and team reference data ships with the package, so lookups are instant and offline.
from nba_api.stats.static import players, teams
players.find_players_by_full_name("jokic")
# [{'id': 203999, 'full_name': 'Nikola Jokić', 'first_name': 'Nikola',
# 'last_name': 'Jokić', 'is_active': True}]
teams.find_team_by_abbreviation("bos")
# {'id': 1610612738, 'full_name': 'Boston Celtics', 'abbreviation': 'BOS', ...}
Searches take case-insensitive regular expressions, and player name searches ignore accents ("jokic" matches "Jokić").
Official stats (stats.nba.com)
from nba_api.stats.endpoints import playercareerstats
career = playercareerstats.PlayerCareerStats(player_id=203999) # sends the request
career.season_totals_regular_season.get_data_frame() # one data set as a pandas DataFrame
career.get_data_frames() # every data set, as a list of DataFrames
career.get_dict() # the full response as a dict
Every stats endpoint works the same way: constructing it sends the request, and each data set the endpoint returns is available as an attribute with get_data_frame(), get_dict(), and get_json(). See the endpoint reference for each endpoint's parameters and data sets.
Live game data (cdn.nba.com)
from nba_api.live.nba.endpoints import scoreboard
games = scoreboard.ScoreBoard() # today's games
games.score_board_date
games.games.get_dict()
Live endpoints: ScoreBoard, BoxScore(game_id), PlayByPlay(game_id), and Odds.
Request options
Every endpoint, stats or live, accepts the same request options:
career = playercareerstats.PlayerCareerStats(
player_id=203999,
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
stats.nba.com throttles rapid requests and does not respond to some cloud-hosting IP ranges. If requests hang or time out, add a delay between calls, increase timeout, or route through a proxy. 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
- 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 are welcome. 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.
Release files for nba-api 1.11.5
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.11.5.tar.gz | 181.8 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nba_api-1.11.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 508.7 kB
Release files / nba_api-1.11.5.tar.gz
| Download URL | nba_api-1.11.5.tar.gz |
|---|---|
| Size | 181.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6f08130e8a4bc645a7a6ce733229f90f34f2dac99b5811f00327861c3fa3eb33
|
|
BLAKE2b-256 checksum How to use checksums |
49c96dc2ad00f65cf1ac38c017c38084e62e31bf3d76c1f8637690cbb67e1b01
|
| 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 22, 2026.
Transparency logRelease files / nba_api-1.11.5-py3-none-any.whl
| Download URL | nba_api-1.11.5-py3-none-any.whl |
|---|---|
| Size | 326.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
00c5364a505faedb6d6d0c3d3993246336c175efdae36ac2ef5f0796796b99db
|
|
BLAKE2b-256 checksum How to use checksums |
0ebfba4bf0d47823caba0e87c3b882b78fd9416bf39c3df94ec3d2d596fc4762
|
| 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 22, 2026.
Transparency logSecurity for nba-api 1.11.5
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.11.5.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 22, 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.
