The README says pandas is optional, the manifest requires it

The getting-started text and the dependency manifest disagree about pandas

The README says the package needs Python 3.10 or newer along with the HTTP and numeric libraries, and adds that while pandas is not required, it is required to work with Pandas DataFrames. The manifest says otherwise. The runtime dependency list contains pandas, gated on the Python version, alongside the numeric library and the HTTP library, and an install from the package index will therefore bring pandas in whether you asked for it or not. The README's own example makes the contradiction visible: it imports nothing, calls a stats endpoint for a named player, and then offers three ways to get the result out, one of which is a pandas data frame. So on a Python 3.10 or 3.11 install you cannot avoid pandas, and on 3.12 or 3.13 you get a newer floor for it. That matters for deployment size and for environments with pinned dependency sets, and it is the kind of mismatch worth fixing in one direction or the other rather than leaving to the reader.

There is no change feed from NBA.com, so breakage arrives as a user bug report

The endpoints section explains the maintenance model more honestly than most wrappers do. A stated purpose of the package is to map and analyse as many endpoints on the site as possible, and the README argues its documentation of the endpoints and their parameters is among the most extensive available. Then it states the constraint directly: NBA.com does not provide information regarding new, changed or removed endpoints. The consequence is structural. There is no changelog to read, no deprecation notice to subscribe to and no version of the site that announces what moved. The detection mechanism is that somebody's code raises an error or returns something empty, that person opens an issue, and the package is updated by hand. The README asks for exactly that report when you find a new, changed or deprecated endpoint. That makes the issue tracker the actual API change log, and it means a pinned version of this library can break without any signal from either side.

The test suite replays recorded HTTP responses instead of calling the site

Among the development dependencies is a recording-based test plugin, which is how a wrapper around a live third-party endpoint keeps its tests deterministic. The mechanism is familiar: a test makes a real request once, the request and response are written to a cassette, and subsequent runs replay the recording rather than reaching the network. For this package that is close to mandatory, since without it every test run would depend on the upstream service being up and on a live scoreboard being in a particular state. The cost is that the recordings are a snapshot. They capture one moment of one season's responses and they do not update themselves, so a cassette that matches production behaviour today is exactly the thing that stops matching when the upstream changes. That makes the recordings a useful regression surface and an unreliable oracle, and it explains why the repository also carries a document about release testing: a library whose tests cannot hit the network still needs a way to check that the network has not moved.

Static data sets exist specifically to reduce requests to the site

One documented feature is described purely in terms of load rather than capability: static data sets that reduce HTTP requests for common and frequently accessed player and team data, with separate pages for the player set and the team set. That framing tells you the problem being solved. An application that looks up a player's identifier or a team's abbreviation on every call would otherwise send a request per lookup, and the identifiers are among the least volatile data on the site. Shipping a local copy converts a repeated network round trip into a dictionary lookup and, not incidentally, reduces the request count against a service the package does not control. There is a request-shaping section alongside it covering proxy support, custom headers, timeout settings, return types and raw responses, which is the other half of the story: when you do make live calls, the package lets you configure timeouts and inspect the raw response rather than only the parsed result. Both features point the same way, toward not leaning on the upstream more than necessary.

The Makefile documents linters that the visible dependency list does not contain

The build file leads with a large comment block explaining itself, which is helpful, and the tool names in it do not match the manifest. Its help text says lint runs flake8 and pylint, and that format runs black and isort. The visible development dependency list contains neither. What it does contain is a single linter and formatter, ruff, alongside the test framework, a coverage plugin, the release tool, a second copy of pandas for the test environment, the pre-commit runner and the recording plugin for HTTP fixtures. So either the Makefile's comments describe a toolchain the project has moved off, or the older tools sit further down a dependency list that is cut off in what is visible here. The distinction matters if you are setting up a development environment: following the Makefile's prose would have you installing four tools the project may no longer use, while the pre-commit configuration at the repository root is the more reliable statement of what actually runs on a commit.

Two endpoint namespaces and three return types for every call

Install is one line from the package index:

pip install nba_api

The package is split into two distinct surfaces that live at different import paths. Historical statistics come from a stats endpoints module, where each endpoint is a class you construct with named parameters, and live data comes from a nested path under a live namespace and a site namespace. The fact that live data is nested one level deeper suggests the live endpoints are grouped by which site surface they belong to, which would leave room for other live sources alongside it. Every endpoint object exposes the same three accessors, which is the package's central convenience:

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

Consistent accessors mean you can change how you consume results without changing which endpoint you call. Note that the data frame line is the one the getting-started text calls optional while the manifest requires it, which is the mismatch described earlier.

Careful version pins across four Python versions, one maintainer, and a refactor in progress

The dependency constraints are more precise than the README suggests. The numeric library has one floor below Python 3.13 and a higher one at 3.13 and above, and the data frame library has one floor below 3.12 and a higher one at 3.12 and above, which is the standard way of absorbing the breaking releases in those two libraries. The HTTP library is bounded above as well as below, so a future major version will not be pulled in silently. Supported interpreters are declared from 3.10 to 3.13, and the package is built with a dedicated Python build backend at a pinned major version. Two structural notes. Everything here is maintained by a single named author, who is also the only listed maintainer, and the repository carries a document about an in-progress refactoring alongside a changelog and a release testing guide, which is the shape of a project mid-change. The newest release is version 1.11.4 from February 2026, while the last commit on the default branch is dated 2026-08-16, so the branch carries several months of work beyond the last tag.

Editorial conclusion

nba_api suits someone building a personal or research tool on NBA data who accepts that the interface is undocumented and can change without notice. Four things to know before you build on it. Read the terms of use for the site itself rather than the package licence, since the MIT licence covers the client and says nothing about the data. Expect to pin a version and expect it to break, because there is no upstream change feed and the issue tracker is the de facto record. Prefer the shipped static data sets for player and team lookups so you are not issuing a request per lookup. And if you are setting up a development environment, trust the pre-commit configuration over the build file's comments, which name a linter and formatter toolchain that the dependency list does not appear to use.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. swar/nba_api on GitHub