Is there an official NBA stats API?

League stats endpoints power the official stats site and are widely called by open-source wrappers, but they are not a documented, supported public API. They can throttle automated traffic and change without notice, which makes them suitable for research and risky for unattended production systems.

Why do NBA stats requests get blocked?

Unofficial endpoints commonly throttle or refuse traffic that looks automated, may expect particular request headers, and often treat requests from cloud hosting ranges with suspicion. Conservative pacing, caching, and retries help for research, but they do not turn an unsupported endpoint into a dependable one.

Can lineup data be built from play by play?

Yes. Substitution events in play by play let you reconstruct which five players were on the court at each moment. It is real engineering work, with edge cases at period boundaries and around missing substitution records, so validate reconstructed lineups against published minutes.

What makes NBA data different from other sports?

Granularity and lineups. Shot locations and substitution-level play by play are widely available, and because players substitute constantly, lineup-level analysis carries more weight than in most sports. Tracking-derived aggregates are published, while raw positional data is not generally public. That combination makes availability news unusually important.

How to Choose an NBA Data Source

Pick by layer and by reliability. Box scores and play by play are widely available, shot location and lineup data are available with more effort, and tracking-derived data is limited. Unofficial access to league stats endpoints is popular and fragile, so production systems usually need a source with an actual service agreement.

The layers of NBA data

Box scores. Player and team totals per game. Universally available and sufficient for a surprising amount of work.

Play by play. Every event in sequence: shots, rebounds, fouls, turnovers, substitutions, with game clock. Substitution events are what make lineup reconstruction possible, which is why play by play matters more in basketball than the equivalent layer does in some other sports.

Shot location. Coordinates for each shot attempt. The basis for shot charts, shot quality models, and most spatial analysis.

Lineup and on-off data. Performance while specific combinations of players are on the court. Either provided directly or reconstructed from play by play substitutions, and the reconstruction is a real engineering task with edge cases at period boundaries.

Tracking-derived statistics. Measures like speed, distance, touches, and defensive matchups derived from optical tracking. Aggregated versions are published; raw positional data is not generally public.

Odds. From separate providers, joined on game and team identifiers.

Why lineups are the distinctive layer

Basketball has five players on the court who substitute freely and constantly. Team strength on any given night depends heavily on who is available and how minutes are distributed, so lineup-level data does more analytical work here than in sports with fixed units or long shifts. That is also why availability news moves basketball analysis so much.

Official, unofficial, and commercial access

Unofficial access to league stats endpoints is how a very large amount of public NBA analysis is done. Open-source wrappers exist that make these endpoints easy to call from Python. They are not a supported API. They can require specific request headers, they are known to throttle or refuse traffic that looks automated, requests from cloud hosting ranges are often treated with particular suspicion, and endpoint parameters change without notice.

That is fine for research on a laptop and a real risk for anything that runs unattended on a schedule.

Reference sites publish extensive historical statistics in browsable form. They are excellent for exploration and verification. Automated collection is typically restricted by their terms and by rate limiting, so read the policy before building a scraper around one.

Commercial data providers offer documented APIs with service terms, uptime expectations, and support. The trade is cost for reliability, and for a production pipeline that trade is usually correct.

The common path is to prototype on unofficial access, then move the parts that need to be dependable onto a source with an agreement behind it.

Handling rate limits on unofficial endpoints

If you do use unofficial access for research, pace requests conservatively, cache every response to disk so you never request the same thing twice, and expect to back off and retry. A collection job that respects this finishes slowly and completes. One that does not gets blocked partway through and leaves an incomplete dataset that is easy to mistake for a complete one.

What to check before committing

Season and format changes. Play-in games, rule changes, and in-season tournament games all affect what counts as a regular season sample. Know how the source labels them.

Player identifiers. Confirm a persistent identifier and a way to map it to the identifiers your odds source uses.

Garbage time. Late minutes in lopsided games distort per-possession statistics. Some sources flag it; most do not. Decide on a definition and apply it consistently.

Pace adjustment. Raw totals conflate efficiency with tempo. Make sure the source gives you possessions or enough to estimate them.

Corrections. Statistics are occasionally revised after games. Know whether your source versions or overwrites them.

Availability data. Injury and rest designations matter more here than in most sports. As with every sport, the value is in knowing when each status was published.

This page describes data sourcing and is not betting advice.

A long season is not a clean sample

An NBA regular season gives each team far more games than an NFL season does, which makes samples look large. They fragment quickly once you account for roster turnover, trades, injuries, and rest. A team's full-season numbers can describe several meaningfully different rosters, so anything that relies on team-level history should weight recent games and account for who was actually available rather than treating the season as one population.

Frequently asked questions

Is there an official NBA stats API?: League stats endpoints power the official stats site and are widely called by open-source wrappers, but they are not a documented, supported public API. They can throttle automated traffic and change without notice, which makes them suitable for research and risky for unattended production systems.
Why do NBA stats requests get blocked?: Unofficial endpoints commonly throttle or refuse traffic that looks automated, may expect particular request headers, and often treat requests from cloud hosting ranges with suspicion. Conservative pacing, caching, and retries help for research, but they do not turn an unsupported endpoint into a dependable one.
Can lineup data be built from play by play?: Yes. Substitution events in play by play let you reconstruct which five players were on the court at each moment. It is real engineering work, with edge cases at period boundaries and around missing substitution records, so validate reconstructed lineups against published minutes.
What makes NBA data different from other sports?: Granularity and lineups. Shot locations and substitution-level play by play are widely available, and because players substitute constantly, lineup-level analysis carries more weight than in most sports. Tracking-derived aggregates are published, while raw positional data is not generally public. That combination makes availability news unusually important.