API-NBA

App · Sports · 12 actions

Follow the NBA with API-NBA: every game since 2015 with its score by quarter, both teams' and every player's box scores, team season statistics, teams, players and the standings, and the summer leagues. Needs an API-SPORTS key; the free plan allows 100 requests a day.

Actions

ActionWhat it does
Find playersFind players by name, by team and season, by country or by ID, each with their birth, height, weight, college, years in the NBA and number and position in each league.
Find teamsFind teams by name, code, league, conference, division or ID, each with its city, logo and place in each league.
Get a gameGet one game by ID: when and where, its status, both teams and the score by quarter.
Get account statusSee the connected key's API-NBA plan, when it renews, and how many of today's requests are used and left.
Get player box scoresGet players' box scores: every player's in a game, or a player's or a team's in every game of a season.
Get standingsGet a season's standings by conference and record: each team's wins and losses in all, at home, away and in the last ten, its win percentage, its places in its conference and division, games behind and streak.
Get team box scoresGet both teams' box scores for a game: points, shooting with its percentages, rebounds, assists, steals, blocks, turnovers, fouls and plus-minus.
Get team statisticsGet a team's totals for a season, or for its pre-season, regular season or play-in and playoffs: games, points, shooting with its percentages, rebounds, assists, steals, blocks, turnovers and plus-minus.
List gamesList games and results by day, season, league or team, or the games in play, each with its arena, status, both teams and the score by quarter.
List head-to-head gamesList the games two teams have played each other, in every season or only one season or league, with a count of each side's wins and points across the finished ones.
List leaguesList the leagues API-NBA covers: standard (the NBA itself) and the summer leagues, by the names the League fields take.
List seasonsList the seasons API-NBA has games for, oldest first, as the years the Season fields take.

Find players

Find players by name, by team and season, by country or by ID, each with their birth, height, weight, college, years in the NBA and number and position in each league.

Inputs

Player IDplayer_idtext
Optional. Only this player, such as 882 for Jayson Tatum.
Searchsearchtext
Optional. Only names containing this, at least 3 characters.
Teamteam_idtext
Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
Seasonseasonnumber
Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
Countrycountrytext
Optional. Only players born in this country, such as USA.

Outputs

countnumber
How many came back.
playerslist
The players.
Example output
{
  "count": 1,
  "players": [
    {
      "affiliation": "Duke/USA",
      "birth": {
        "country": "USA",
        "date": "1998-03-03"
      },
      "college": "Duke",
      "firstname": "Jayson",
      "height": {
        "feet": 6,
        "inches": 8,
        "meters": 2.03
      },
      "id": 882,
      "lastname": "Tatum",
      "leagues": [
        {
          "active": true,
          "jersey": null,
          "league": "standard",
          "position": "F-G"
        }
      ],
      "name": "Jayson Tatum",
      "nba": {
        "pro": 4,
        "start": 2017
      },
      "weight": {
        "kilograms": 95.3,
        "pounds": 210
      }
    }
  ]
}

Find teams

Find teams by name, code, league, conference, division or ID, each with its city, logo and place in each league. The API's teams include All-Star sides and international clubs; Franchises only keeps the 30 NBA franchises.

Inputs

Team IDteam_idtext
Optional. Only this team, by ID, such as 2.
Searchsearchtext
Optional. Only names containing this, at least 3 characters.
Codecodetext
Optional. Only the team with this code, such as BOS.
Leagueleaguetext
Optional. Only this league: the NBA, or one of its summer leagues.One of: standard (The NBA), vegas (Las Vegas Summer League), utah (Salt Lake City Summer League), sacramento (California Classic), orlando (Orlando Summer League), africa (NBA Africa Game).
Conferenceconferencetext
Optional. Only this conference: East or West.One of: East, West.
Divisiondivisiontext
Optional. Only this division, such as Atlantic.One of: Atlantic, Central, Southeast, Northwest, Pacific, Southwest.
Franchises onlyfranchises_onlytrue/false
Optional. Only the 30 NBA franchises, leaving out All-Star sides and international clubs.

Outputs

countnumber
How many came back.
teamslist
The teams.
Example output
{
  "count": 1,
  "teams": [
    {
      "all_star": false,
      "city": "Boston",
      "code": "BOS",
      "id": 2,
      "leagues": [
        {
          "conference": "East",
          "division": "Atlantic",
          "league": "standard"
        },
        {
          "conference": "summer",
          "division": null,
          "league": "vegas"
        },
        {
          "conference": "East",
          "division": "Atlantic",
          "league": "utah"
        },
        {
          "conference": "East",
          "division": "Atlantic",
          "league": "sacramento"
        }
      ],
      "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
      "name": "Boston Celtics",
      "nba_franchise": true,
      "nickname": "Celtics"
    }
  ]
}

Get a game

Get one game by ID: when and where, its status, both teams and the score by quarter.

Inputs

Game IDgame_idtextRequired
The game's ID, such as 14145. List games returns them.

Outputs

arenaobject
Where it is played.
dateobject
When.
idnumber
The game's ID.
lead_changesnumber
Lead changes, when known.
leaguetext
The league, such as standard for the NBA.
nuggettext
A note on the game, when the API has one.
officialslist
The referees, when the API has them.
periodsobject
Quarters.
scoresobject
Both sides' scores.
seasonnumber
The season, as the year it starts in.
stagenumber
1 for the pre-season, 2 the regular season, 3 the play-in and playoffs.
statusobject
Where the game stands.
teamsobject
Both sides.
times_tiednumber
Times the score was tied, when known.
Example output
{
  "arena": {
    "city": "Chicago",
    "country": null,
    "name": "United Center",
    "state": "IL"
  },
  "date": {
    "duration": null,
    "end": null,
    "start": "2024-10-27T00:00:00.000Z"
  },
  "id": 14145,
  "lead_changes": null,
  "league": "standard",
  "nugget": null,
  "officials": [],
  "periods": {
    "current": 4,
    "end_of_period": false,
    "total": 4
  },
  "scores": {
    "home": {
      "linescore": [
        21,
        18,
        26,
        30
      ],
      "points": 95
    },
    "visitors": {
      "linescore": [
        26,
        33,
        29,
        26
      ],
      "points": 114
    }
  },
  "season": 2024,
  "stage": 2,
  "status": {
    "clock": null,
    "halftime": false,
    "long": "Finished",
    "short": 3
  },
  "teams": {
    "home": {
      "code": "CHI",
      "id": 6,
      "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
      "name": "Chicago Bulls",
      "nickname": "Bulls"
    },
    "visitors": {
      "code": "OKC",
      "id": 25,
      "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
      "name": "Oklahoma City Thunder",
      "nickname": "Thunder"
    }
  },
  "times_tied": null
}

Get account status

See the connected key's API-NBA plan, when it renews, and how many of today's requests are used and left. It is free: it never counts against the day.

Inputs

None.

Outputs

activetrue/false
True while the subscription is active.
daily_limitnumber
Requests allowed a day.
plantext
The plan, such as Free.
requests_remainingnumber
Requests left today; the day starts at midnight UTC.
requests_todaynumber
Requests used today.
subscription_endtext
When the plan renews or ends.
Example output
{
  "active": true,
  "daily_limit": 100,
  "plan": "Free",
  "requests_remaining": 88,
  "requests_today": 12,
  "subscription_end": "2027-10-01T00:00:00+00:00"
}

Get player box scores

Get players' box scores: every player's in a game, or a player's or a team's in every game of a season. Each has minutes, points, shooting, rebounds, assists, steals, blocks, turnovers and plus-minus.

Inputs

Game IDgame_idtext
Optional. Every player's box score in this game. Set this, or a season with a player or a team.
Player IDplayer_idtext
Optional. Only this player's box scores, such as 882. Needs a season.
Teamteam_idtext
Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
Seasonseasonnumber
Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.

Outputs

countnumber
How many came back.
playerslist
The players' box scores.
Example output
{
  "count": 2,
  "players": [
    {
      "assists": 2,
      "blocks": 0,
      "comment": null,
      "field_goals": {
        "attempted": 8,
        "made": 1,
        "percentage": 12.5
      },
      "fouls": 1,
      "free_throws": {
        "attempted": 0,
        "made": 0,
        "percentage": null
      },
      "game_id": 14145,
      "minutes": "26",
      "player": {
        "firstname": "Patrick",
        "id": 2664,
        "lastname": "Williams",
        "name": "Patrick Williams"
      },
      "plus_minus": -12,
      "points": 3,
      "position": null,
      "rebounds": {
        "defensive": 6,
        "offensive": 2,
        "total": 8
      },
      "steals": 1,
      "team": {
        "code": "CHI",
        "id": 6,
        "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
        "name": "Chicago Bulls",
        "nickname": "Bulls"
      },
      "three_pointers": {
        "attempted": 4,
        "made": 1,
        "percentage": 25.0
      },
      "turnovers": 1
    },
    {
      "assists": 2,
      "blocks": 1,
      "comment": null,
      "field_goals": {
        "attempted": 12,
        "made": 7,
        "percentage": 58.3
      },
      "fouls": 2,
      "free_throws": {
        "attempted": 2,
        "made": 2,
        "percentage": 100.0
      },
      "game_id": 14145,
      "minutes": "33",
      "player": {
        "firstname": "Nikola",
        "id": 534,
        "lastname": "Vucevic",
        "name": "Nikola Vucevic"
      },
      "plus_minus": -14,
      "points": 18,
      "position": null,
      "rebounds": {
        "defensive": 10,
        "offensive": 3,
        "total": 13
      },
      "steals": 0,
      "team": {
        "code": "CHI",
        "id": 6,
        "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
        "name": "Chicago Bulls",
        "nickname": "Bulls"
      },
      "three_pointers": {
        "attempted": 2,
        "made": 2,
        "percentage": 100.0
      },
      "turnovers": 3
    }
  ]
}

Get standings

Get a season's standings by conference and record: each team's wins and losses in all, at home, away and in the last ten, its win percentage, its places in its conference and division, games behind and streak. Narrow to one conference, division or team.

Inputs

LeagueleaguetextRequired
The league: the NBA, or one of its summer leagues.One of: standard (The NBA), vegas (Las Vegas Summer League), utah (Salt Lake City Summer League), sacramento (California Classic), orlando (Orlando Summer League), africa (NBA Africa Game).
SeasonseasonnumberRequired
The season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
Teamteam_idtext
Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
Conferenceconferencetext
Optional. Only this conference: East or West.One of: East, West.
Divisiondivisiontext
Optional. Only this division, such as Atlantic.One of: Atlantic, Central, Southeast, Northwest, Pacific, Southwest.

Outputs

countnumber
How many came back.
standingslist
Each team's line, by conference and then best record first.
Example output
{
  "count": 2,
  "standings": [
    {
      "conference": {
        "name": "east",
        "rank": 1
      },
      "division": {
        "name": "atlantic",
        "rank": 1
      },
      "games_behind": null,
      "league": "standard",
      "losses": {
        "away": 14,
        "home": 4,
        "last_ten": 3,
        "percentage": 0.22,
        "total": 18
      },
      "season": 2023,
      "streak": 2,
      "team": {
        "code": "BOS",
        "id": 2,
        "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
        "name": "Boston Celtics",
        "nickname": "Celtics"
      },
      "tie_breaker_points": null,
      "win_streak": true,
      "wins": {
        "away": 27,
        "home": 37,
        "last_ten": 7,
        "percentage": 0.78,
        "total": 64
      }
    },
    {
      "conference": {
        "name": "west",
        "rank": 1
      },
      "division": {
        "name": "northwest",
        "rank": 1
      },
      "games_behind": null,
      "league": "standard",
      "losses": {
        "away": 17,
        "home": 8,
        "last_ten": 3,
        "percentage": 0.305,
        "total": 25
      },
      "season": 2023,
      "streak": 5,
      "team": {
        "code": "OKC",
        "id": 25,
        "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
        "name": "Oklahoma City Thunder",
        "nickname": "Thunder"
      },
      "tie_breaker_points": null,
      "win_streak": true,
      "wins": {
        "away": 24,
        "home": 33,
        "last_ten": 7,
        "percentage": 0.695,
        "total": 57
      }
    }
  ]
}

Get team box scores

Get both teams' box scores for a game: points, shooting with its percentages, rebounds, assists, steals, blocks, turnovers, fouls and plus-minus.

Inputs

Game IDgame_idtextRequired
The game's ID, such as 14145. List games returns them.

Outputs

countnumber
How many came back.
game_idnumber
The game asked about.
teamslist
Each side's box score.
Example output
{
  "count": 2,
  "game_id": 14145,
  "teams": [
    {
      "assists": 23,
      "blocks": 2,
      "field_goals": {
        "attempted": 92,
        "made": 32,
        "percentage": 34.8
      },
      "fouls": 19,
      "free_throws": {
        "attempted": 22,
        "made": 16,
        "percentage": 72.7
      },
      "minutes": "240:00",
      "plus_minus": -19,
      "points": 95,
      "rebounds": {
        "defensive": 50,
        "offensive": 11,
        "total": 61
      },
      "steals": 6,
      "team": {
        "code": "CHI",
        "id": 6,
        "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
        "name": "Chicago Bulls",
        "nickname": "Bulls"
      },
      "three_pointers": {
        "attempted": 53,
        "made": 15,
        "percentage": 28.3
      },
      "turnovers": 26
    },
    {
      "assists": 21,
      "blocks": 5,
      "field_goals": {
        "attempted": 107,
        "made": 45,
        "percentage": 42.1
      },
      "fouls": 18,
      "free_throws": {
        "attempted": 20,
        "made": 16,
        "percentage": 80.0
      },
      "minutes": "240:00",
      "plus_minus": 19,
      "points": 114,
      "rebounds": {
        "defensive": 45,
        "offensive": 9,
        "total": 54
      },
      "steals": 15,
      "team": {
        "code": "OKC",
        "id": 25,
        "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
        "name": "Oklahoma City Thunder",
        "nickname": "Thunder"
      },
      "three_pointers": {
        "attempted": 40,
        "made": 8,
        "percentage": 20.0
      },
      "turnovers": 10
    }
  ]
}

Get team statistics

Get a team's totals for a season, or for its pre-season, regular season or play-in and playoffs: games, points, shooting with its percentages, rebounds, assists, steals, blocks, turnovers and plus-minus.

Inputs

Teamteam_idtextRequired
The team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
SeasonseasonnumberRequired
The season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
Stagestagetext
Optional. Only this part of the season: the pre-season, the regular season, or the play-in and playoffs.One of: 1 (Pre-season), 2 (Regular season), 3 (Play-in and playoffs).

Outputs

assistsnumber
Assists.
blocksnumber
Blocks.
field_goalsobject
Field goals.
foulsnumber
Personal fouls.
free_throwsobject
Free throws.
gamesnumber
Games played.
plus_minusnumber
The points margin while on the court.
pointsnumber
Points.
reboundsobject
Rebounds.
stealsnumber
Steals.
three_pointersobject
Three-pointers.
turnoversnumber
Turnovers.
Example output
{
  "assists": 2144,
  "blocks": 451,
  "field_goals": {
    "attempted": 7380,
    "made": 3413,
    "percentage": 46.2
  },
  "fouls": 1303,
  "free_throws": {
    "attempted": 1565,
    "made": 1251,
    "percentage": 79.9
  },
  "games": 82,
  "plus_minus": 747,
  "points": 9534,
  "rebounds": {
    "defensive": 2783,
    "offensive": 932,
    "total": 3715
  },
  "steals": 590,
  "three_pointers": {
    "attempted": 3954,
    "made": 1457,
    "percentage": 36.8
  },
  "turnovers": 975
}

List games

List games and results by day, season, league or team, or the games in play, each with its arena, status, both teams and the score by quarter.

Inputs

Dateon_datedate
Optional. Only games on this day, in UTC. The free plan takes only yesterday, today or tomorrow.
Seasonseasonnumber
Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
Leagueleaguetext
Optional. Only this league: the NBA, or one of its summer leagues.One of: standard (The NBA), vegas (Las Vegas Summer League), utah (Salt Lake City Summer League), sacramento (California Classic), orlando (Orlando Summer League), africa (NBA Africa Game).
Teamteam_idtext
Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
In playlivetrue/false
Optional. Only the games the API has in play right now.

Outputs

countnumber
How many came back.
gameslist
The games, in the order given.
Example output
{
  "count": 1,
  "games": [
    {
      "arena": {
        "city": "Chicago",
        "country": null,
        "name": "United Center",
        "state": "IL"
      },
      "date": {
        "duration": null,
        "end": null,
        "start": "2024-10-27T00:00:00.000Z"
      },
      "id": 14145,
      "lead_changes": null,
      "league": "standard",
      "nugget": null,
      "officials": [],
      "periods": {
        "current": 4,
        "end_of_period": false,
        "total": 4
      },
      "scores": {
        "home": {
          "linescore": [
            21,
            18,
            26,
            30
          ],
          "points": 95
        },
        "visitors": {
          "linescore": [
            26,
            33,
            29,
            26
          ],
          "points": 114
        }
      },
      "season": 2024,
      "stage": 2,
      "status": {
        "clock": null,
        "halftime": false,
        "long": "Finished",
        "short": 3
      },
      "teams": {
        "home": {
          "code": "CHI",
          "id": 6,
          "logo": "https://upload.wikimedia.org/wikipedia/en/6/67/Chicago_Bulls_logo.svg",
          "name": "Chicago Bulls",
          "nickname": "Bulls"
        },
        "visitors": {
          "code": "OKC",
          "id": 25,
          "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
          "name": "Oklahoma City Thunder",
          "nickname": "Thunder"
        }
      },
      "times_tied": null
    }
  ]
}

List head-to-head games

List the games two teams have played each other, in every season or only one season or league, with a count of each side's wins and points across the finished ones.

Inputs

First teamfirst_team_idtextRequired
One of the two teams, such as 2 for the Boston Celtics. The summary counts its wins first.
Second teamsecond_team_idtextRequired
The other team, such as 25 for the Oklahoma City Thunder.
Seasonseasonnumber
Optional. Only this season, as the year it starts in, such as 2024 for 2024-25. The free plan reads the 2022 to 2024 seasons.From 1900 to 2100.
Leagueleaguetext
Optional. Only this league: the NBA, or one of its summer leagues.One of: standard (The NBA), vegas (Las Vegas Summer League), utah (Salt Lake City Summer League), sacramento (California Classic), orlando (Orlando Summer League), africa (NBA Africa Game).

Outputs

countnumber
How many came back.
gameslist
Their games, oldest first.
summaryobject
A count of the finished games among them.
Example output
{
  "count": 2,
  "games": [
    {
      "arena": {
        "city": "Oklahoma City",
        "country": null,
        "name": "Paycom Center",
        "state": "OK"
      },
      "date": {
        "duration": null,
        "end": null,
        "start": "2025-01-05T20:30:00.000Z"
      },
      "id": 14601,
      "lead_changes": null,
      "league": "standard",
      "nugget": null,
      "officials": [],
      "periods": {
        "current": 4,
        "end_of_period": false,
        "total": 4
      },
      "scores": {
        "home": {
          "linescore": [
            32,
            23,
            21,
            29
          ],
          "points": 105
        },
        "visitors": {
          "linescore": [
            35,
            30,
            15,
            12
          ],
          "points": 92
        }
      },
      "season": 2024,
      "stage": 2,
      "status": {
        "clock": null,
        "halftime": false,
        "long": "Finished",
        "short": 3
      },
      "teams": {
        "home": {
          "code": "OKC",
          "id": 25,
          "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
          "name": "Oklahoma City Thunder",
          "nickname": "Thunder"
        },
        "visitors": {
          "code": "BOS",
          "id": 2,
          "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
          "name": "Boston Celtics",
          "nickname": "Celtics"
        }
      },
      "times_tied": null
    },
    {
      "arena": {
        "city": "Boston",
        "country": null,
        "name": "TD Garden",
        "state": "MA"
      },
      "date": {
        "duration": null,
        "end": null,
        "start": "2025-03-12T23:30:00.000Z"
      },
      "id": 15060,
      "lead_changes": null,
      "league": "standard",
      "nugget": null,
      "officials": [],
      "periods": {
        "current": 4,
        "end_of_period": false,
        "total": 4
      },
      "scores": {
        "home": {
          "linescore": [
            30,
            30,
            28,
            24
          ],
          "points": 112
        },
        "visitors": {
          "linescore": [
            33,
            30,
            25,
            30
          ],
          "points": 118
        }
      },
      "season": 2024,
      "stage": 2,
      "status": {
        "clock": null,
        "halftime": false,
        "long": "Finished",
        "short": 3
      },
      "teams": {
        "home": {
          "code": "BOS",
          "id": 2,
          "logo": "https://upload.wikimedia.org/wikipedia/en/8/8f/Boston_Celtics.svg",
          "name": "Boston Celtics",
          "nickname": "Celtics"
        },
        "visitors": {
          "code": "OKC",
          "id": 25,
          "logo": "https://upload.wikimedia.org/wikipedia/en/5/5d/Oklahoma_City_Thunder.svg",
          "name": "Oklahoma City Thunder",
          "nickname": "Thunder"
        }
      },
      "times_tied": null
    }
  ],
  "summary": {
    "first_team_points": 204,
    "first_team_wins": 0,
    "played": 2,
    "second_team_points": 223,
    "second_team_wins": 2
  }
}

List leagues

List the leagues API-NBA covers: standard (the NBA itself) and the summer leagues, by the names the League fields take.

Inputs

None.

Outputs

countnumber
How many came back.
leagueslist
The leagues, by name.
Example output
{
  "count": 6,
  "leagues": [
    "africa",
    "orlando",
    "sacramento",
    "standard",
    "utah",
    "vegas"
  ]
}

List seasons

List the seasons API-NBA has games for, oldest first, as the years the Season fields take. A season is named by the year it starts in.

Inputs

None.

Outputs

countnumber
How many came back.
seasonslist
The seasons, oldest first.
Example output
{
  "count": 5,
  "seasons": [
    2022,
    2023,
    2024,
    2025,
    2026
  ]
}

On this page