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
| Action | What it does |
|---|---|
| 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. |
| Find teams | Find teams by name, code, league, conference, division or ID, each with its city, logo and place in each league. |
| Get a game | Get one game by ID: when and where, its status, both teams and the score by quarter. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| List leagues | List the leagues API-NBA covers: standard (the NBA itself) and the summer leagues, by the names the League fields take. |
| List seasons | List 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 ID
player_idtext - Optional. Only this player, such as 882 for Jayson Tatum.
- Search
searchtext - Optional. Only names containing this, at least 3 characters.
- Team
team_idtext - Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Season
seasonnumber - 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.
- Country
countrytext - 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 ID
team_idtext - Optional. Only this team, by ID, such as 2.
- Search
searchtext - Optional. Only names containing this, at least 3 characters.
- Code
codetext - Optional. Only the team with this code, such as BOS.
- League
leaguetext - 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). - Conference
conferencetext - Optional. Only this conference: East or West.One of:
East,West. - Division
divisiontext - Optional. Only this division, such as Atlantic.One of:
Atlantic,Central,Southeast,Northwest,Pacific,Southwest. - Franchises only
franchises_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 ID
game_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 ID
game_idtext - Optional. Every player's box score in this game. Set this, or a season with a player or a team.
- Player ID
player_idtext - Optional. Only this player's box scores, such as 882. Needs a season.
- Team
team_idtext - Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Season
seasonnumber - 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
- League
leaguetextRequired - 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). - Season
seasonnumberRequired - 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.
- Team
team_idtext - Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Conference
conferencetext - Optional. Only this conference: East or West.One of:
East,West. - Division
divisiontext - 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 ID
game_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
- Team
team_idtextRequired - The team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- Season
seasonnumberRequired - 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.
- Stage
stagetext - 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
- Date
on_datedate - Optional. Only games on this day, in UTC. The free plan takes only yesterday, today or tomorrow.
- Season
seasonnumber - 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.
- League
leaguetext - 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). - Team
team_idtext - Optional. Only this team. Pick one from the list, or pass a team ID such as 2 for the Boston Celtics.
- In play
livetrue/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 team
first_team_idtextRequired - One of the two teams, such as 2 for the Boston Celtics. The summary counts its wins first.
- Second team
second_team_idtextRequired - The other team, such as 25 for the Oklahoma City Thunder.
- Season
seasonnumber - 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.
- League
leaguetext - 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
]
}