NBA Overview

Introduction

Sportradar is the Official Data Provider of NBA statistics. We combine on-venue speed, detailed game and seasonal statistics, and advanced metrics for a full basketball experience. Every NBA game – including preseason – updates in real-time, with live event positional data.

The NBA API is consistent in structure, format, and behavior with our other League Specific APIs. Our primary feeds return schedules, standings, team/player data, and real-time scores.

Our other NBA feeds provide a host of complementary statistics and information, including:

• Rankings
• League leaders
• Game splits
• Season splits
• Injuries
• Free agents
• Draft information
• Live advanced metrics
• In-game substitution info
• Live event positional data

Real-time customers are also offered five delivery Push Feeds to enhance speed.

🗝️

Authentication is required for all API calls.

API Map

To best utilize the NBA API v8, you will need several parameters to create your API calls. The map below illustrates how you can obtain the parameters you need.

The primary feeds require only a date or season to call the endpoints. Those feeds provide Game, Team, or Player Ids which can be used to generate the game, team, and player feeds. All of the other feeds require no variables.

Endpoint Descriptions

Daily Change Log – Provides IDs and timestamps for teams, players, game statistics, schedules, and standings that have been modified on a given date. To receive the data updates, use these unique IDs to pull relevant API feeds.

Daily Schedule – Date, time, location, and other event details for every game taking place in the league-defined day.

Daily Transfers – Information for all transfers added or edited during the league-defined day.

Draft Summary – Provides pre-draft pick order with live pick selections during the draft. Displays information on draft rounds, picks, teams, and prospects for a given draft year.

Free Agents – Detailed player information for all current free agents in the league.

Game Boxscore – Top-level team scores by quarter, along with full statistics for each team’s leader in points, rebounds, and assists.

Game Summary – Top-level boxscore information, along with detailed game stats at the team and player levels.

Injuries – Information concerning all active player injuries for each NBA team.

League Hierarchy – League, conference, division, and team identification and association information.

League Leaders – NBA leader information for various offensive and defensive categories including full player seasonal statistics for each player in each category.

Play-By-Play – Detailed, real-time information on every team possession and game event.

Player Profile – Provides player biographical information, draft information, and seasonal statistics.

Prospects – Provides a list of upcoming or historical draft prospects for a given year.

Rankings – Conference and division rank for each team, including playoff clinching status.

Schedule – Date, time, location, and other event details for every match-up taking place in the full league season.

Seasonal Statistics – Provides complete team and player seasonal statistics for a given season and season type.

Seasons – Provides a list of all available seasons, including preseasons and postseasons.

Series Schedule – Playoff participant information as well as the date, time, location, and other event details for every match-up taking place for the entire playoffs.

Series Statistics – Detailed team and player statistics for a given playoff series.

Splits – Detailed splits divided into game, hierarchy, in-game, and schedule splits.

Standings – Detailed team records across various views including, overall, conference, and division information.

Team Draft Summary – Provides pre-draft pick order with live pick selections during the draft for a given team.

Team Profile – Provides top-level team information and a full roster of active players.

Teams – Provides a complete list of teams in the NBA API database.

Top Prospects – Provides a list of the top prospects for a given year.

Trades – Provides summary details of all in-draft trades.

Push Clock – Game clock with high level scoring and possession information.

Push Draft Picks – Provides pre-draft pick order with real-time pick selections during the draft.

Push Draft Trades – Provides summary details of all in-draft trades in real-time.

Push Events – Detailed, real-time information on every game event.

Push Statistics – Detailed, real-time game stats at the team and player level for all live games.

Data Retrieval Samples

To find a team's leader in assists for a given game:

1. Call the schedule or series schedule feed and find the Game Id for the game of your choice
2. Call the Game Boxscore using the Game Id
3. Find the Team of your choice, locate the Leaders statistics, then locate the player full_name attribute

The name of the team's leader in assists is displayed.

To find a player's average points per game:

1. Call the schedule or series schedule and find id for the team the player is on
2. Call the Team Profile using the Team ID
3. Locate the Player ID for your chosen player and call the Player Profile.
4. Find the average element with the points attribute

The players's average points are displayed.

Coverage Levels

We provide two different levels of detail to ensure maximum coverage. We combine coverage levels with the correct feeds to ensure you are getting the most comprehensive data offering in the most efficient manner possible. Full coverage is available for all regular and postseason games. Most preseason games will also have full coverage, though in some rare cases extended boxscore may be used.

Full – We provide live play-by-play coverage for the entire game. We provide updated scores and time remaining as well as team- and player-level data in near real time.

Extended Boxscore – We provide scores, time remaining, and team leaders (assists, points, and rebounds), in a timely manner, as the game progresses. We provide team- and player-level data for the game within 30 minutes of the official results being posted.

🏀

Preseason Coverage Note:

Preseason coverage of NBA games may vary. Due to data-entry coverage (from venue) not being available, some games may be covered via our extended boxscore coverage.

Integration Links

Postman Workspace

Our entire Media APIs are available on Postman. Click the link above to be taken directly to our NBA API collection.

Feel free to follow and/or fork any collections to receive updates.

Schema Download

Open the zip file below to access our entire NBA API XSD schema.

NBA v8 Schema

Failover Information

Reference the below files to find data points unavailable when Sportradar's data team provides game updates due to a NBA data interruption. Please note that when the game is over, all data entered by Sportradar is deleted and replaced with the official data provided by the NBA.

Failover Details

Failover Statistics Summary

In-Season Tournament

The inaugural NBA In-Season Tournament will take place during the 2023-24 NBA season. The tournament is divided into a group play stage and a knockout stage.

In group play, all 30 teams are randomly drawn into groups of five (six groups overall) within their conference based on their previous season’s win-loss record. Each team will play four designated group play games against each opponent in its group, with two games at home and two on the road.

Eight teams advance to the knockout rounds: the six teams with the best standing in their group and two wild card teams (the team from each conference with the best record in Group Play games that finished second in its group).

All 67 In-Season Tournament games count towards the regular season standings except for the In-Season Tournament Championship game. Each team will continue to play 82 regular season games.

Season Types

A new season type was created in the NBA API for the NBA In-Season Tournament called In-Season Tournament with code (also referred to as parameter) of IST. This season type can be retrieved via the NBA Seasons feed:

https://api.sportradar.com/nba/production/v8/en/league/seasons.xml?api_key=

</season>
    <season id="170cfa7b-54e8-468b-ab9f-21244769bd75" year="2023" start_date="2023-12-09" end_date="2023-12-10" status="scheduled">
        <type code="IST" name="In-Season Tournament"/>
</season>

This code (or parameter) can be used to retrieve endpoints for the following feeds:

• League Leaders
• Rankings
• Schedule
• Seasonal Statistics
• Seasons
• Series Schedule
• Splits (Game)
• Splits (Hierarchy)
• Splits (In-Game)
• Splits (Schedule)
• Standings

Click here for XML and JSON samples of the Seasons feed with the IST season included.

Tournament Schedule

Group Play

With the exception of the In-season Championship Game, all NBA In-Season Tournament games will appear in the NBA API Regular Season (REG) schedule.

Example for 2023 season: https://api.sportradar.com/nba/production/v8/en/games/2023/REG/schedule.xml?api_key=

The regular season games included in the NBA In-Season Tournament will have a game attribute called inseason_tournament with a value of true.

<game id="d4d3c86e-43f3-48e6-bdf6-b92f18b172e5" status="scheduled" coverage="full" 
 scheduled="2023-11-03T23:00:00Z" inseason_tournament="true" reference="0022300001" 
 home_team="583ec7cd-fb46-11e1-82cb-f4ce4684ea4c" away_team="583ec773-fb46-11e1-82cb-f4ce4684ea4c">

Click here for XML and JSON samples of the Schedule feed with the inseason_tournament games included.

Quarterfinals & Semifinals

In the knockout rounds, all games will be created as a part of a one-game series. The quarterfinals and semifinals will be created in the regular season and will appear in the regular season schedule paths (League Schedule and Series Schedule):

League Schedule: https://api.sportradar.us/nba/production/v8/en/games/2023/REG/schedule.xml?api_key=

Series Schedule:
https://api.sportradar.us/nba/production/v8/en/series/2023/REG/schedule.xml?api_key=

<league
	xmlns="http://feed.elasticstats.com/schema/basketball/schedule-v5.0.xsd" id="4353138d-4c22-4396-95d8-
5f587d2df25c" name="NBA" alias="NBA">
	<season-schedule id="93f22ddf-a842-47ea-bdba-4306461c7219" year="2023" type="REG">
		<series id="0a8d5e26-9843-41cc-be41-6e3f85a8b8a7" title="NBA In-Season Tournament Quarterfinals - PHI vs
MIL" round="1" start_date="2023-12-05" status="scheduled">
			<participant name="76ers" seed="3" record="0">
				<team id="583ec87d-fb46-11e1-82cb-f4ce4684ea4c" name="76ers" alias="PHI" market="Philadelphia"
reference="1610612755"/>
			</participant>
			<participant name="Bucks" seed="2" record="0">
				<team id="583ecefd-fb46-11e1-82cb-f4ce4684ea4c" name="Bucks" alias="MIL" market="Milwaukee"
reference="1610612749"/>
			</participant>
			<games>
				<game id="d6f0f89e-b9b4-4726-ae6b-533292dba030" status="scheduled" title="NBA In-Season
Tournament Quarterfinals - Game 4" coverage="full" scheduled="2023-12-06T02:30:00+00:00" neutral_site="false"
inseason_tournament="true" track_on_court="true" reference="4444444444" home_team="583ecefd-fb46-11e1-82cbf4ce4684ea4c" away_team="583ec87d-fb46-11e1-82cb-f4ce4684ea4c">
					<time_zones venue="US/Central" home="US/Central" away="US/Eastern"/>
					<venue id="50b75324-b994-46af-a0a7-28db7bea67d0" name="Fiserv Forum" capacity="17500"
address="1111 Vel R Phillips Avenue" city="Milwaukee" state="WI" zip="53203" country="USA">
						<location lat="43.045028" lng="-87.918167"/>
					</venue>
					<home name="Milwaukee Bucks" alias="MIL" id="583ecefd-fb46-11e1-82cb-f4ce4684ea4c" seed="2"
reference="1610612749"></home>
					<away name="Philadelphia 76ers" alias="PHI" id="583ec87d-fb46-11e1-82cb-f4ce4684ea4c" seed="3"
reference="1610612755"></away>
				</game>
			</games>
		</series>

Click here for XML and JSON samples of the knockout rounds.

Championship Game

The NBA In-Season Tournament Championship game, due to not counting towards the regular season standings, will appear in the In-Season Tournament (IST) season and series schedule:

Season Schedule: https://api.sportradar.us/nba/production/v8/en/games/2023/IST/schedule.xml?api_key=

Series Schedule:
https://api.sportradar.us/nba/production/v8/en/series/2023/IST/schedule.xml?api_key=

<league
	xmlns="http://feed.elasticstats.com/schema/basketball/schedule-v5.0.xsd" id="4353138d-4c22-4396-95d8-
5f587d2df25c" name="NBA" alias="NBA">
	<season-schedule id="8d181bc8-11cf-48e9-9d99-570799735ece" year="2023" type="IST">
		<series id="243f30ae-1a9e-4c33-8d5b-ea4c7a498463" title="NBA In-Season Tournament Championship - BOS
vs MIN" round="3" start_date="2023-12-09" status="scheduled">
			<participant name="Timberwolves" seed="2" record="0">
				<team id="583eca2f-fb46-11e1-82cb-f4ce4684ea4c" name="Timberwolves" alias="MIN"
market="Minnesota" reference="1610612750"/>
			</participant>
			<participant name="Celtics" seed="1" record="0">
				<team id="583eccfa-fb46-11e1-82cb-f4ce4684ea4c" name="Celtics" alias="BOS" market="Boston"
reference="1610612738"/>
			</participant>
			<games>
				<game id="9d4faf8e-e518-4736-8b08-5bcdcf423627" status="scheduled" title="NBA In-Season
Tournament Championship Game" coverage="full" scheduled="2023-12-10T01:00:00+00:00" neutral_site="false"
inseason_tournament="true" track_on_court="true" reference="7777777777" home_team="583eccfa-fb46-11e1-82cbf4ce4684ea4c" away_team="583eca2f-fb46-11e1-82cb-f4ce4684ea4c">
					<time_zones venue="US/Eastern" home="US/Eastern" away="US/Central"/>
					<venue id="7d69b080-91ca-53c9-9302-45c1a72c5549" name="TD Garden" capacity="18624"
address="100 Legends Way" city="Boston" state="MA" zip="02114" country="USA">
						<location lat="42.366303" lng="-71.062228"/>
					</venue>
					<home name="Boston Celtics" alias="BOS" id="583eccfa-fb46-11e1-82cb-f4ce4684ea4c" seed="1"
reference="1610612738"></home>
					<away name="Minnesota Timberwolves" alias="MIN" id="583eca2f-fb46-11e1-82cb-f4ce4684ea4c"
seed="2" reference="1610612750"></away>
				</game>
			</games>
		</series>
	</season-schedule>
</league>

Click here for XML and JSON samples of the Championship game.

Standings

To access the In-Season Tournament standings, you need use the IST season parameter. In the endpoint below, you will see teams placed in the In-Season Tournament groups.

Please note that no in-season tournament data will exist in the Regular Season standings.

https://api.sportradar.us/nba/production/v8/en/seasons/2023/IST/standings.xml?api_key=

<league
	xmlns="http://feed.elasticstats.com/schema/basketball/nba/standings-v4.0.xsd" id="4353138d-4c22-4396-
95d8-5f587d2df25c" name="NBA" alias="NBA">
	<season id="170cfa7b-54e8-468b-ab9f-21244769bd75" year="2023" type="IST">
		<conference id="02e1f608-b72d-484c-9fb3-c9df903bc54d" name="EASTERN CONFERENCE" alias="EASTERNIST">
			<division id="34643105-9549-4682-9801-fc72fb4880c4" name="East Group A" alias="EAST_GROUP_A">
				<team id="583ecb8f-fb46-11e1-82cb-f4ce4684ea4c" name="Hawks" market="Atlanta" wins="0" losses="0"
win_pct="0.0" points_for="0.0" points_against="0.0" point_diff="0.0" sr_id="sr:team:3423" reference="1610612737">
					<games-behind league="0.0" conference="0.0" division="0.0"/>
					<streak></streak>
					<calc_rank/>
					<records></records>
				</team>
				<team id="583ec773-fb46-11e1-82cb-f4ce4684ea4c" name="Cavaliers" market="Cleveland" wins="0"
losses="0" win_pct="0.0" points_for="0.0" points_against="0.0" point_diff="0.0" sr_id="sr:team:3432"
reference="1610612739">
					<games-behind league="0.0" conference="0.0" division="0.0"/>
					<streak></streak>
					<calc_rank/>
					<records></records>
				</team>
				<team id="583ec928-fb46-11e1-82cb-f4ce4684ea4c" name="Pistons" market="Detroit" wins="0" losses="0"
win_pct="0.0" points_for="0.0" points_against="0.0" point_diff="0.0" sr_id="sr:team:3424" reference="1610612765">
					<games-behind league="0.0" conference="0.0" division="0.0"/>
					<streak></streak>
					<calc_rank/>
					<records></records>
				</team>
				<team id="583ec7cd-fb46-11e1-82cb-f4ce4684ea4c" name="Pacers" market="Indiana" wins="0" losses="0"
win_pct="0.0" points_for="0.0" points_against="0.0" point_diff="0.0" sr_id="sr:team:3419" reference="1610612754">
					<games-behind league="0.0" conference="0.0" division="0.0"/>
					<streak></streak>
					<calc_rank/>
					<records></records>
				</team>
				<team id="583ec87d-fb46-11e1-82cb-f4ce4684ea4c" name="76ers" market="Philadelphia" wins="0"
losses="0" win_pct="0.0" points_for="0.0" points_against="0.0" point_diff="0.0" sr_id="sr:team:3420"
reference="1610612755">
					<games-behind league="0.0" conference="0.0" division="0.0"/>
					<streak></streak>

Click here for XML and JSON samples of the IST Standings.

Play-In Tournament

Each NBA season will feature a play-in tournament to determine the 7th and 8th seeds for each conference’s playoff bracket. The 2024 Play-In Tournament will take place from April 16-19.

In the NBA API, these games will be found in the Play-in Tournament (PIT) season schedule:

https://api.sportradar.com/nba/production/v8/en/games/2023/PIT/schedule.xml?api=

The season parameter of PIT must also be used to retrieve seasonal statistics for these games.

At the conclusion of the regular season but prior to the first round of the playoffs, the team with the 7th-highest winning percentage in each conference will host the team with the 8th-highest winning percentage in a Play-In Game (the “Seven-Eight Game”). The winner of the Seven-Eight Game in each conference will earn the No. 7 seed.

In the below example, the Miami Heat would host the Charlotte Hornets in the Seven-Eight Game. The winner of that game would be the 7th seed in the Eastern Conference playoffs and would play the 2nd seed in the first round.

  <team id="583ecea6-fb46-11e1-82cb-f4ce4684ea4c" name="Heat" market="Miami" sr_id="sr:team:3435" reference="1610612748">
  <rank conference="7" division="2"/>

  <team id="583ec97e-fb46-11e1-82cb-f4ce4684ea4c" name="Hornets" market="Charlotte" sr_id="sr:team:3430" reference="1610612766">
  <rank conference="8" division="3"/>

Additionally, the team with the 9th-highest winning percentage in each conference will host the team with the 10th-highest winning percentage in the “Nine-Ten Game”.

 <team id="583ec7cd-fb46-11e1-82cb-f4ce4684ea4c" name="Pacers" market="Indiana" sr_id="sr:team:3419" reference="1610612754">
 <rank conference="9" division="2"/>
   
 <team id="583ec8d4-fb46-11e1-82cb-f4ce4684ea4c" name="Wizards" market="Washington" sr_id="sr:team:3431" reference="1610612764">
 <rank conference="10" division="4"/>

In this example, the Indiana Pacers would host the Washington Wizards in the “Nine-Ten Game.” The loser of that game would be eliminated from playoff contention. The winner would play the loser of the Heat/Hornets game (Seven-Eight Game). The winner of that game would earn the 8th seed and play the 1st seed in the first round of the playoffs.

While all playoff series will appear in the postseason series schedule feed at the completion of the regular season, the final playoff matchups will not be determined until the play-in tournament is complete.

https://api.sportradar.com/nba/{access_level}/v8/{language_code}/series/{season_year}/PST/schedule.{format}?api_key={your_api_key}

Simulations

Our NBA simulations give you the opportunity to test your code against a simulation of live data before the preseason starts or any time! Our simulation system replays select completed games allowing you to view our API feeds as if they were happening live.

Simulations run every day according to the below schedule. Data is reset for each day's simulations at 12:45pm UTC.

Quick Access

To retrieve the game IDs, team IDs, and other associated information for each game listed above, you can use the following URL with the syntax noted below. If you have an existing NBA API key, simply replace the access_level (trial or production) in the URL of a feed with simulation.

https://api.sportradar.com/nba/simulation/`{version}`/`{language_code}`/games/2017/SIM/schedule.`{format}`?api_key=`{your_api_key}

Feeds Available: Schedule, Standings, League Hierarchy, Game Boxscore, Game Summary, Play-By-Play, Team Profile, Seasonal Statistics, Injuries, Rankings, Push Events, and Push Statistics

For syntax structure on each feed, please reference the below documentation.

Data Entry Workflow

See below for a daily breakdown of data updates for the NBA API.

<home name="East NBA All Stars" alias="EST" id="592d3144-895b-43e9-ab15-e84666a845d5" reference="1610616833">

<away name="West NBA All Stars" alias="WST" id="787ff06f-f0cc-484e-8114-04e0cdc444fa" reference="1610616834">