Skip to navigation

Basketball

The NBA, NCAAB and WNBA, field by field. The live state, plays, box score and what isn't filled yet.

The NBA (nba), NCAA Division I men’s basketball (ncaab) and the WNBA (wnba) share one data model. A game in any of them fills the same endpoints and the same basketball blocks, so the same code reads all three. The leagues differ in period length and in a few fields, listed under League differences.

The examples come from two recorded games: the Lakers at the Hawks in the NBA on November 9, 2026, and Wagner at UConn in NCAAB the same night.

Live state

live_state on GET /v1/{league}/games/{id} carries the situation in its basketball block. The other sports’ blocks are null.

FieldWhat it is
periodThe quarter in the NBA and WNBA, the half in NCAAB. A later period is an overtime.
clock_secondsSeconds left in the period, rounded up, so 0 means the period is over.
clock_runningAlways null. The basketball feed doesn’t say whether the clock is running.
possession_team_idThe team with the ball, or null when the feed doesn’t say, as after the final.
basketball.home_timeouts, basketball.away_timeoutsTimeouts each team has left.
basketball.home_fouls, basketball.away_foulsEach team’s fouls in the current period.

The basketball block is there only while the game is in progress. After the final it’s null, and period and clock_seconds keep the end of the game, such as period 4 at 0.

Each count is null when the feed doesn’t report it. The feed doesn’t track timeouts and fouls for most college games, so in NCAAB the four counts are often null all game.

Periods and overtime

Leagueperiod_kindregulation_periodsRegulationOvertime
NBAquarter4Four 12-minute quarters5 minutes each
WNBAquarter4Four 10-minute quarters5 minutes each
NCAABhalf2Two 20-minute halves5 minutes each

Every period after regulation is another overtime, so an NBA game’s period 6 is its second overtime and an NCAAB game’s period 3 is its first. Build a scoreboard turns a period number into a label such as 2nd half or 2OT, and the clock section formats clock_seconds.

Plays

GET /v1/{league}/games/{id}/plays lists every event. It returns a page of events, 500 by default and up to 1,000 with limit, with a next_cursor for the rest. Lists, pagination and dates shows how to page. A play’s type and its basketball.play_type are the same value, one of these:

play_typeThe event
field_goalA two- or three-point shot, made or missed
free_throwA free throw, made or missed
offensive_rebound, defensive_reboundA rebound
reboundA rebound the feed doesn’t call offensive or defensive, such as a dead-ball team rebound
turnover, steal, blockA turnover, or a steal or block filed as its own event
foul, technical_foul, flagrant_foulA foul
violationA violation such as goaltending, a kicked ball or a lane violation
timeout, substitution, jump_ball, review, ejectionWhat the name says
period_start, period_end, game_endThe start or end of a period, and the end of the game
otherAnything else

The basketball block on each play:

FieldWhat it is
points_attemptedWhat a shot was worth: 1 for a free throw, 2 or 3 for a field goal, and 0 for any other event.
is_madeWhether the shot went in.
shot_typeA field goal’s style: jump_shot, layup, dunk, hook_shot or tip_shot. null on other events, or when the feed doesn’t say.
free_throw, free_throwsA free throw’s place in its trip to the line, so the second of two is 2 of 2. null when the feed doesn’t say, as on a technical free throw.
court_x, court_yWhere a field goal was taken from, in feet. court_x runs across the court from 0 to 50. court_y runs along it from the basket the team attacks, so it’s negative behind the basket. null when the feed has no position.

points and is_scoring say what the play scored, and home_score and away_score are the score after it. team_id is the team credited with the event, which for a shot is the shooting team, even when another team’s player blocked it.

Each play’s participants lists the players in it with a role: shooter, assist, blocker, rebounder, stealer, fouler, player_in and player_out on a substitution, or player for any other part, such as the players in a jump ball or the player who turned it over. A team rebound has no participants. Join each participant’s player_id to players[].id in the game roster response, not to the box score, because a player in a play can have no stat line. description is the feed’s play text.

This is a made three in the NBA sample, from plays.json, unedited:

{
"away_score": 0,
"basketball": {
"court_x": 27,
"court_y": 25,
"free_throw": null,
"free_throws": null,
"is_made": true,
"play_type": "field_goal",
"points_attempted": 3,
"shot_type": "jump_shot"
},
"clock_seconds": 690,
"description": "Onyeka Okongwu makes 24-foot running jump shot (Kingston Flemings assists)",
"football": null,
"game_id": "01a1e5f6-6d6c-730b-995a-c3fd2a14a9a2",
"group_id": null,
"hockey": null,
"home_score": 3,
"id": "01a1e5f6-6d6c-7395-bdbf-0e01da948e73",
"is_official": true,
"is_scoring": true,
"participants": [
{
"player_id": "01a1e5f6-6d6c-736a-beb4-29cabc88d024",
"role": "assist",
"team_id": "01a1e5f6-6d6c-7312-8095-49b16b3b06a5"
},
{
"player_id": "01a1e5f6-6d6c-735a-80b8-5687fdb6155d",
"role": "shooter",
"team_id": "01a1e5f6-6d6c-7312-8095-49b16b3b06a5"
}
],
"period": 1,
"period_half": null,
"points": 3,
"sequence": 10030000000009,
"soccer": null,
"team_id": "01a1e5f6-6d6c-7312-8095-49b16b3b06a5",
"type": "field_goal",
"updated_at": "2026-11-16T20:04:54.762239Z",
"version": 1,
"wall_clock": "2026-11-10T00:10:57Z"
}

The Hawks went up 3 to 0 with 11:30 left in the 1st quarter. The assist is a second participant on the same play.

Play groups

Basketball has no drives or possessions in the data. Every play’s group_id is null, and GET /v1/{league}/games/{id}/play-groups returns an empty list.

Box score

GET /v1/{league}/games/{id}/boxscore has one line per player who played. Each line holds one category, basketball:

CodeWhat it is
minutesMinutes played, in whole minutes
pointsPoints
field_goals_made, field_goals_attField goals made and attempted, threes included
three_points_made, three_points_attThree-pointers made and attempted
free_throws_made, free_throws_attFree throws made and attempted
rebounds, offensive_rebounds, defensive_reboundsRebounds, in total and by end
assists, turnovers, steals, blocksWhat the names say
personal_foulsPersonal fouls
plus_minusThe point difference while the player was on the court. NBA and WNBA only.

These are the stats of a Lakers player in the NBA sample, unedited:

{
"basketball": {
"blocks": 0,
"points": 12,
"steals": 2,
"assists": 2,
"minutes": 28,
"rebounds": 2,
"turnovers": 0,
"plus_minus": 5,
"personal_fouls": 1,
"field_goals_att": 10,
"free_throws_att": 0,
"field_goals_made": 5,
"free_throws_made": 0,
"three_points_att": 5,
"three_points_made": 2,
"defensive_rebounds": 2,
"offensive_rebounds": 0
}
}

Treat every code as optional, and ignore codes you don’t use. Build a scoreboard joins the lines to player names and adds up team totals.

Rosters

GET /v1/{league}/games/{id}/roster lists every player in the box score, with their team, jersey, position (G, F or C) and whether they started. A player who didn’t play is on the roster but has no box-score line.

What isn’t filled yet

DataWhat you get today
InjuriesGET /v1/{league}/injuries returns an empty list in all three leagues.
clock_running on the live statenull. Use status and clock_seconds.
Timeouts and fouls in most NCAAB gamesnull, because the feed doesn’t track them

Coverage by league lists the gaps every sport shares, such as team totals and the score by period.

League differences

NBAWNBANCAAB
PeriodsFour 12-minute quartersFour 10-minute quartersTwo 20-minute halves
plus_minusYesYesNo
Blocks and steals in playsOn the shot and the turnover, as blocker and stealerAs in the NBAOften their own block and steal events
Timeouts and fouls on the live stateReported when the feed has themReported when the feed has themUsually null
Season yearThe year the season starts, so 2026-27 is 2026The year it’s playedThe year the season starts

NBA play-in games belong to the postseason, so their season’s type is PST.