Embedded Files
by Papa-Yaw Afari
This wiki touches on the niche NBA API laws for potential programmers who want to utilize the NBA API for projects. There are some inconsistencies and discrepancies in information on the API that I believe proves to important when utilizing said API.
OVERVIEW
OVERVIEW
The NBA provides a rich but often frustrating set of APIs through its stats.nba.com endpoints. While the documentation is limited and unofficial, many developers and analysts use it for pulling player stats, game logs, and team-level metrics.
However, one of the most difficult challenges is accessing shot chart detail — the exact x/y coordinates of each player’s shots during a game — due to both technical limitations and legal constraints built into how the NBA handles player data.
EXPERIEnCE WITH THE API/FRUSTATIONS & PIvoting
EXPERIEnCE WITH THE API/FRUSTATIONS & PIvoting
For my project called "Court Vision: Immersive Basketball Shot Chart in VR" (which is linked the VR Software Wiki at Brown University), I had set to figure how immersive VR environents can be used to visualize and compare basketball players' field goal patterns and what advantages this VR representation has over traditional 2D methods. However, along this process involved trying to utilize the NBA API which I eventually had to drop.
In this project, I initially planned to pull live shot location data directly from the NBA API using endpoints like:
"https://stats.nba.com/stats/shotchartdetail"
But no matter how I configured the headers or parameters, the requests were blocked or returned empty datasets. Eventually, I realized:
The NBA now restricts shot chart data based on IP, rate-limiting, and browser fingerprinting
Requests from anything other than a real Chrome browser were often denied
Some endpoints are region-locked or rate-limited specifically for international users or academic IPs
Even when data is returned, some games are deliberately obfuscated or scrubbed, especially those that involve player movement data
Troubleshooting Tips for the NBA API
Troubleshooting Tips for the NBA API
If you're trying to work with NBA data, here are important tips to save hours of frustration:
1. Mimic A REAL BROWSER
1. Mimic A REAL BROWSER
"{
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
"Referer": "https://www.nba.com/",
"Origin": "https://www.nba.com"
}"
2. USE DELAY AND RETRY LOGIC
2. USE DELAY AND RETRY LOGIC
The NBA's public backend, like many public services, utilizes Cloudflare rate limiting.
Too many requests = temporary IP ban.
For how this would look coding wise:
"//await new Promise(resolve => setTimeout(resolve, 750));"
3. STAY AWAY FROM PUBLIC PROXIES
3. STAY AWAY FROM PUBLIC PROXIES
Most public proxies are blacklisted. Instead you should work from a personal IP or with a VPN that is able to rotate clean exit nodes.
4. SHOT CHARt access is very restricted
4. SHOT CHARt access is very restricted
The shotchartdetail endpoint only works reliably on game days or for archived games within certain windows
Some high-profile games or players have missing coordinate data
Games from older seasons are more stable (pre-2020), newer games are heavily filtered
5. CONSIDER SCRAPPING (AS LAST RESORT)
5. CONSIDER SCRAPPING (AS LAST RESORT)
In cases where the API blocks you:
Use headless Chrome + Puppeteer to scrape data directly from the NBA.com shot chart visualization tool
Still needs care, as NBA updates their front-end constantly
PRIVACY LAWS And DATA LoCKdown
PRIVACY LAWS And DATA LoCKdown
One of the less talked-about developments is how player data has become a privacy issue — especially after 2020:
Collective Bargaining Agreements between NBA and NBPA now include clauses about player tracking data privacy
Players must consent for their biometric or shot chart data to be used in commercial tools
The NBA has quietly rolled back public access to location-based shot data to avoid third-party resellers profiting from it
Some data feeds (like SportVU or Second Spectrum) are now locked behind partnerships and paywalls, unlike earlier in the 2010s when more was public
KEY TAKEAWAYS
KEY TAKEAWAYS
Accessing detailed NBA shot data isn’t just a technical hurdle — it’s a legal and institutional one. If you're building immersive analytics tools like this project, you’ll often have to pivot to public data sources, scrape visualization sites, or manually build your own JSON formats (which is exactly what I ended up doing).
What to uSE INSTEAD:
What to uSE INSTEAD:
Since the official NBA API is limited, try:
Basketball Reference for static historical data (no coordinates, but clean stats) I personally utilized this option.
NBA API + manual scraping for building your own datasets
Open-source projects like nba_api in Python, but know they may break due to NBA updates
Or generate your own JSON shot data by mapping out court dimensions and manually inputting key shots, like I did for the Game 7 Jayson Tatum dataset
SOURCES/REFERENCES
SOURCES/REFERENCES
NBA Official Stats API (Undocumented)
Base URL: https://stats.nba.com/stats/
Frequently used but undocumented endpoints like shotchartdetail, playergamelog, commonplayerinfo
Header requirements and rate-limiting behavior observed through browser DevTools
NBA API Browser Blocking Behavior
Developer community reports that NBA.com blocks requests without specific headers
Verified via GitHub issues and StackOverflow:
NBA’s Partnership with Second Spectrum & Data Licensing
Second Spectrum provides NBA’s player tracking data, including SportVU-like 3D coordinates
Access requires an enterprise agreement — not public:
NBA announces Second Spectrum as official tracking provider
NBPA Privacy Protections
New CBA clauses (2020 onwards) emphasize biometric data restrictions
Mentioned in articles like:
ESPN: NBA's player tracking data use now involves NBPA consent
The Athletic: Why player data is protected under NBPA agreements
nba_api (Python wrapper)
Popular community-maintained wrapper for the NBA Stats API
Documents known issues with endpoint reliability and workarounds
Basketball Reference
Stable historical data resource used as a fallback when NBA Stats API data fails
Page updated
Google Sites
Report abuse