NBA data

Access and plan boundaries

Scores, schedules, standings, NBA leaders, matchup data, lineups, injuries and player props have Free entry points. Full NBA play-by-play is Pro. Current and historical odds use the plan shown by the endpoint reference; do not infer access from another data type on the same game.

The enforceable source is the route's plan badge and response. See the current plan ladder and authentication guide.

History and coverage

Dataset depth is not uniform: games, linescores, plays, box scores, props and odds can cover different season spans. Read GET /v1/coverage?sport=basketball before choosing a training or backtest window, and inspect the per-data-type status instead of treating a game count as proof that every related table is populated.

curl "https://api.bigballsdata.com/v1/coverage?sport=basketball" \
  -H "Authorization: Bearer $BBS_API_KEY"

Live scores and WebSockets

Use /v1/matches?sport=basketball&league=nba as the canonical schedule and score list. Polling clients should follow rate-limit headers and back off on 429. Pro clients can subscribe to match rooms over WebSockets; a connected socket does not imply that a game is currently producing events.

Player props and freshness

/v1/nba/players/:player_id/props returns the lines held for a player and a response-level freshness block. Treat freshness.status and data_as_of as part of the product contract: a returned off-season line is a stored line, not automatically a current price.

Play-by-play

/v1/nba/games/:game_id/plays is the NBA-native play stream and has a Pro floor. It returns event order, period and clock fields, the running score and involved player fields when present. Use the game identifier returned by the NBA game surface; do not substitute a canonical match UUID where a route documents the league game id.

Shot coordinates

Shot-chart data is exposed through the dedicated player-shot surface, with court coordinates, shot type, distance and make/miss state where that season is loaded. Check coverage before promising a multi-season chart.

Odds

Historical odds and current per-match prices answer different questions. Historical snapshots support backtests; /v1/matches/:id/odds represents prices held for a specific game. Check timestamps and the coverage response before calling either feed current.

Identifiers and media

NBA responses can carry both a Big Balls canonical UUID and a league-native numeric id. Route parameters are not interchangeable; follow the identifier documented by the route you are calling. headshot_url and logo_url are nullable capabilities. Render initials or a team abbreviation when either is null, and never reconstruct or guess an external image URL from a player name.