NBA Stats API Status - Phase 0 Validation

November 6, 2025 · View on GitHub

Date: 2025-11-06 Status: Initial Investigation

Executive Summary

Initial testing reveals that the existing NBA stats API endpoints (https://stats.nba.com/stats/) are timing out with the current implementation. This suggests one or more of the following:

  1. API endpoints have changed - NBA may have restructured their API URLs
  2. Authentication/headers required - Additional authentication or different headers may now be required
  3. Rate limiting - More aggressive rate limiting may be in place
  4. API deprecation - The stats.nba.com API may have been deprecated in favor of a new API

Implications for Modernization

This finding validates our v2.0 breaking changes approach:

  • We cannot simply modernize the existing code if the API itself no longer works
  • We need to research and document the current NBA API structure
  • The new implementation must be built against working endpoints
  • Migration will require users to understand both code AND API changes

Testing Methodology

Test Setup

  • Environment: Python 3.14, virtual environment via uv
  • Dependencies: requests, retrying (legacy), httpx, tenacity (modern)
  • Test Approach:
    1. Updated HTTP → HTTPS in base URLs
    2. Removed Python 2 compatibility layers
    3. Attempted to call existing endpoints with current code
    4. Direct curl tests to validate API availability

Results

Endpoint: commonallplayers

  • URL: https://stats.nba.com/stats/commonallplayers
  • Parameters: LeagueID=00&Season=2024-25&IsOnlyCurrentSeason=1
  • Headers: Standard browser spoofing (User-Agent, Referer, etc.)
  • Result: ❌ TIMEOUT - No response after 10+ seconds

General Observations

  • All requests to stats.nba.com/stats/* endpoints are timing out
  • Both Python requests library and curl experience same behavior
  • HTTPS upgrade from HTTP does not resolve issues
  • Rate limiting delays (0.6s between requests) are in place but not helping

Known Issues from Codebase

The existing codebase already documented several blocked/unavailable endpoints:

Player Endpoints (BLOCKED BY NBA)

  • shot_log - Player shot-level logs
  • rebound_log - Player rebound-level logs
  • general_splits - Player general splits

Team Endpoints (BLOCKED BY NBA)

  • defense_dashboard - Team defense dashboard

League Endpoints (BLOCKED BY NBA)

  • daily_scoreboard - Daily game scores
  • league_leaders - League-wide statistical leaders

Historical Data Limitations

  • SportVU data: Only available for 2013-2015 seasons
  • PlayType data: Only available for 2015 season

Next Steps

Phase 0: Research (1-2 days)

  1. Investigate current NBA API:

    • Check if stats.nba.com has API documentation
    • Look for official NBA API offerings (NBA.com, CDN, etc.)
    • Research community knowledge (nba_api Python package, basketball-reference, etc.)
    • Determine if there's a new authentication mechanism

  2. Identify alternative data sources:

    • Official NBA APIs
    • stats.nba.com (if accessible with different approach)
    • Community-maintained endpoints
    • Consider if data.nba.net or other CDN URLs work

  3. Document findings:

    • Working endpoint URLs
    • Required headers/authentication
    • Available data scope
    • Rate limiting policies

Phase 1: Prototype (2-3 days)

Once we identify working endpoints:

  1. Create minimal proof-of-concept client
  2. Validate we can fetch player list, game logs, basic stats
  3. Document response schemas
  4. Test rate limiting behavior

Phase 2-6: Continue Modernization

Proceed with architectural modernization using working endpoints.

References

Community Resources to Investigate

Original Code Locations

  • Base URLs: goldsberry/masterclass.py:171,177,193
  • Header configuration: goldsberry/masterclass.py:17-25
  • Rate limiting: goldsberry/masterclass.py:27-28,62-68

Risks & Considerations

Risk: No Working Official API

Mitigation: May need to use unofficial/community endpoints or scraping

Risk: Authentication Required

Mitigation: Research API keys, OAuth, or other auth mechanisms

Risk: Scope Reduction

Mitigation: Document which historical endpoints are unavailable in v2.0

Risk: Completely Different API Structure

Mitigation: Design flexible adapter pattern to support multiple backend APIs

Decision Points

Before proceeding with Phase 2 core infrastructure:

  1. ✅ Do working NBA endpoints exist?

    • If YES → Document them and proceed
    • If NO → Consider alternative data sources or scraping approach

  2. ⏸️ What authentication is required?

    • None → Simplest implementation
    • API key → Add configuration management
    • OAuth → Add full OAuth flow

  3. ⏸️ What's the API structure?

    • REST with JSON → Proceed as planned with httpx + Pydantic
    • GraphQL → Adjust client architecture
    • HTML scraping → Different approach entirely

  4. ⏸️ Should we maintain backward compatibility with old endpoint names?

    • If API structure is similar → Could maintain class/method names
    • If completely different → Clean break, document migration

Research Update: nba_api Package Investigation

Date: 2025-11-06

Key Findings

  1. Same Endpoints: The actively maintained nba_api package (https://github.com/swar/nba_api) uses the same stats.nba.com/stats/* endpoints we're targeting.

  2. Same Problems: Their issue tracker shows multiple recent reports of timeouts and connection issues:

    • Issue #572: leaguegamefinder timing out
    • Issue #505: BoxscoreAdvancedV2/V3 timeouts
    • Issue #478: Defensehub endpoint not working
    • Issue #481: shotchartlineupdetail not working

  3. API Reliability: This is not our implementation problem - the NBA stats API itself is experiencing reliability issues. Both our package and nba_api face the same challenges.

  4. Their Architecture:

    • Python 3.7+, uses requests library
    • No special authentication required
    • Base URL: https://stats.nba.com/stats/
    • Multiple response formats: DataFrame, JSON, dict
    • No explicit rate limiting (relies on manual delays)

Implications

Good News:

  • Our technical approach is sound
  • The endpoints haven't fundamentally changed
  • No new authentication barriers

Bad News:

  • API is unreliable and prone to timeouts
  • Some endpoints may be deprecated or broken
  • No official NBA API documentation or support

Critical Requirement: Our v2.0 must be more resilient than v1.x or nba_api:

  • Aggressive retry logic with exponential backoff
  • Configurable timeouts (longer than 60s may be needed)
  • Graceful degradation when endpoints fail
  • Clear error messages distinguishing timeout vs. actual errors
  • Circuit breaker pattern to avoid hammering broken endpoints

Status: ✅ PROCEEDING

We can proceed with modernization using the existing endpoint structure, but with a focus on resilience:

  1. Use same base URLs as nba_api: https://stats.nba.com/stats/
  2. Design for failure: expect timeouts and handle them gracefully
  3. Implement robust retry mechanisms with tenacity
  4. Add timeout configuration at client level
  5. Build mocked tests so development doesn't depend on flaky API
  6. Document which endpoints are unreliable