Rosters
This guide helps you access comprehensive information on NBA transfers, rosters, and injuries. You'll learn how to effectively query endpoints for real-time transaction updates, specific team rosters, position on the court and how to keep track of daily injuries and depth charts.
Introduction to Rosters
An NBA roster is essentially the lineup of players registered under a team. You can access rosters using the Team Profile feed. This endpoint provides top-level team information and a full roster of active players.
Roster Updates
- During the preseason, we match team roster information with the NBA. As training camp approaches, teams release their official rosters.
- For NBA training camps, we include players signed to the 15-man active roster, up to three two-way contract players per team, and those with a training camp invite.
- Preseason camps are capped at 21 players, but the roster is trimmed to 18 players when the season starts (15 active players and 3 two-way contracts).
Two-Way Contracts
A two-way contract allows a player to divide their time between an NBA team and its affiliated G-League team.
Accessing Rosters
- Get a team ID: You can access a list of all active teams in the NBA API database with the Teams endpoint.
- Use your team ID to call the Team Profile endpoint.
Recommended Pull Frequency:
- Updates are as necessary as changes are made to rosters or player profiles.
- Pull every hour or less depending on your use case.
- The TTL/Cache is 300 seconds.
Tip - Utilize Team Franchise Data
You can also use the Team Roster and Team Profile endpoints to access detailed franchise data for NBA teams. This information includes the team's founding year, current owner, nicknames, records of championships and division titles won and more.
Example - Team Roster:
{
"id": "583ecf50-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Mavericks",
"market": "Dallas",
"alias": "DAL",
"founded": 1980,
"sr_id": "sr:team:3411",
"owner": "Miriam Adelson",
"general_manager": "Nico Harrison",
"president": "Cynthia Marshall",
"mascot": "Champ, MavsMan",
"nicknames": "Mavs",
"sponsor": "Chime",
"championships_won": 1,
"championship_seasons": "2011",
"conference_titles": 2,
"division_titles": 5,
"retired_numbers": "12, 15, 22, 41",
"playoff_appearances": 25,
"gleague_affiliate": "Texas Legends",
"reference": "1610612742",
"venue": {
"id": "401ba62f-19b5-5bfc-84d6-021772943311",
"name": "American Airlines Center",
"capacity": 19200,
"address": "2500 Victory Avenue",
"city": "Dallas",
"state": "TX",
"zip": "75219",
"country": "USA",
"sr_id": "sr:venue:5988",
"location": {
"lat": "32.79087",
"lng": "-96.810338"
}
},
"league": {
"id": "4353138d-4c22-4396-95d8-5f587d2df25c",
"name": "NBA",
"alias": "NBA"
},
"conference": {
"id": "7fe7e212-de01-4f8f-a31d-b9f0a95731e3",
"name": "WESTERN CONFERENCE",
"alias": "WESTERN"
},
"division": {
"id": "1d29f94c-9587-494b-a232-feb20a40eb4c",
"name": "Southwest",
"alias": "SOUTHWEST"
},
"coaches": [
{
"id": "ccbac6eb-99fd-4343-ba17-1f35bdd2ffef",
"full_name": "Jason Kidd",
"first_name": "Jason",
"last_name": "Kidd",
"position": "Head Coach",
"experience": "9",
"reference": "203456"
}
],
"team_colors": [
{
"type": "secondary",
"hex_color": "#00285e",
"rgb_color": {
"red": 0,
"green": 40,
"blue": 94
}
},
{
"type": "primary",
"hex_color": "#0053bc",
"rgb_color": {
"red": 0,
"green": 83,
"blue": 188
}
}
],
"players": [
{
"id": "0d187d04-4cd9-44b3-9a29-408fac5b011e",
"status": "ACT",
"full_name": "Dante Exum",
"first_name": "Dante",
"last_name": "Exum",
"abbr_name": "D.Exum",
"height": 77,
"weight": 214,
"position": "G",
"primary_position": "PG",
"jersey_number": "0",
"experience": "7",
"high_school": "Lake Ginninderra (AUS)",
"birth_place": "Melbourne,, AUS",
"birthdate": "1995-07-13",
"updated": "2024-07-21T01:20:38Z",
"sr_id": "sr:player:607872",
"rookie_year": 2014,
"reference": "203957",
"draft": {
"team_id": "583ece50-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2014,
"round": "1",
"pick": "5"
}
},
{
"id": "1b31afe2-7fb7-42d1-8eef-003c5eb619c2",
"status": "ACT",
"full_name": "Dereck Lively II",
"first_name": "Dereck",
"last_name": "Lively",
"abbr_name": "D.Lively",
"height": 85,
"weight": 230,
"position": "C",
"primary_position": "C",
"jersey_number": "2",
"experience": "1",
"college": "Duke",
"high_school": "Westtown School (PA)",
"birth_place": "Philadelphia, PA, USA",
"birthdate": "2004-02-12",
"updated": "2024-07-16T18:19:14Z",
"name_suffix": "II",
"sr_id": "sr:player:2444995",
"rookie_year": 2023,
"reference": "1641726",
"draft": {
"team_id": "583ecfff-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2023,
"round": "1",
"pick": "12"
}
},
{
"id": "23e33381-1d9d-4415-b3bc-3e3d747aa103",
"status": "ACT",
"full_name": "Melvin Ajinça",
"first_name": "Melvin",
"last_name": "Ajinça",
"abbr_name": "M.Ajinça",
"height": 80,
"weight": 218,
"position": "F",
"primary_position": "SF",
"jersey_number": "17",
"experience": "0",
"birth_place": "Villeneuve-Saint-Georges,, FRA",
"birthdate": "2004-06-26",
"updated": "2024-09-16T12:56:27Z",
"sr_id": "sr:player:2685285",
"draft": {
"team_id": "583ec70e-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2024,
"round": "2",
"pick": "51"
}
},
{
"id": "25c4a949-c310-4bd3-af3f-10441215b323",
"status": "ACT",
"full_name": "Markieff Morris",
"first_name": "Markieff",
"last_name": "Morris",
"abbr_name": "M.Morris",
"height": 81,
"weight": 245,
"position": "F",
"primary_position": "PF",
"experience": "12",
"college": "Kansas",
"high_school": "APEX Academy (NJ)",
"birth_place": "Philadelphia, PA, USA",
"birthdate": "1989-09-02",
"updated": "2024-09-07T21:05:27Z",
"sr_id": "sr:player:607346",
"rookie_year": 2011,
"reference": "202693",
"draft": {
"team_id": "583ecfa8-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2011,
"round": "1",
"pick": "13"
}
},
{
"id": "3ef70a50-cd0d-4148-a1ad-ca830a1a9046",
"status": "ACT",
"full_name": "Maxi Kleber",
"first_name": "Maxi",
"last_name": "Kleber",
"abbr_name": "M.Kleber",
"height": 82,
"weight": 240,
"position": "F",
"primary_position": "PF",
"jersey_number": "42",
"experience": "7",
"birth_place": "Wurzburg,, DEU",
"birthdate": "1992-01-29",
"updated": "2024-07-21T01:22:20Z",
"sr_id": "sr:player:921210",
"rookie_year": 2017,
"reference": "1628467",
"draft": {
"year": 2014
}
},
{
"id": "4e152a06-673e-4701-b115-aa7e2cd00d2d",
"status": "ACT",
"full_name": "Klay Thompson",
"first_name": "Klay",
"last_name": "Thompson",
"abbr_name": "K.Thompson",
"height": 78,
"weight": 220,
"position": "G",
"primary_position": "SG",
"jersey_number": "31",
"experience": "11",
"college": "Washington State",
"high_school": "Santa Margarita Catholic (CA)",
"birth_place": "Los Angeles, CA, USA",
"birthdate": "1990-02-08",
"updated": "2024-07-21T01:22:15Z",
"sr_id": "sr:player:607470",
"rookie_year": 2011,
"reference": "202691",
"draft": {
"team_id": "583ec825-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2011,
"round": "1",
"pick": "11"
}
},
{
"id": "52cd8137-c791-4569-ad70-433e25d34882",
"status": "ACT",
"full_name": "Daniel Gafford",
"first_name": "Daniel",
"last_name": "Gafford",
"abbr_name": "D.Gafford",
"height": 82,
"weight": 234,
"position": "F-C",
"primary_position": "PF",
"jersey_number": "21",
"experience": "5",
"college": "Arkansas",
"high_school": "El Dorado (AR)",
"birth_place": "El Dorado, AR, USA",
"birthdate": "1998-10-01",
"updated": "2024-07-21T01:22:06Z",
"sr_id": "sr:player:1286466",
"rookie_year": 2019,
"reference": "1629655",
"draft": {
"team_id": "583ec5fd-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2019,
"round": "2",
"pick": "38"
}
},
{
"id": "599e6bbf-54a5-431b-b542-1817a0942369",
"status": "ACT",
"full_name": "Olivier-Maxence Prosper",
"first_name": "Olivier-Maxence",
"last_name": "Prosper",
"abbr_name": "O.Prosper",
"height": 79,
"weight": 230,
"position": "F",
"primary_position": "PF",
"jersey_number": "18",
"experience": "1",
"college": "Marquette",
"high_school": "NBA Academy Latin America (MEX)",
"birth_place": "Montreal, QC, CAN",
"birthdate": "2002-07-03",
"updated": "2024-07-16T18:25:16Z",
"sr_id": "sr:player:2078595",
"rookie_year": 2023,
"reference": "1641765",
"draft": {
"team_id": "583ed0ac-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2023,
"round": "1",
"pick": "24"
}
},
{
"id": "6bc71e02-9a03-40db-aed4-332ab5193336",
"status": "ACT",
"full_name": "A.J. Lawson",
"first_name": "A.J.",
"last_name": "Lawson",
"abbr_name": "A.Lawson",
"height": 78,
"weight": 179,
"position": "G",
"primary_position": "SG",
"jersey_number": "9",
"experience": "2",
"college": "South Carolina",
"high_school": "GTA Prep (CAN)",
"birth_place": "Toronto, ON, CAN",
"birthdate": "2000-07-15",
"updated": "2024-07-21T01:21:39Z",
"sr_id": "sr:player:1593864",
"rookie_year": 2022,
"reference": "1630639",
"draft": {
"year": 2021
}
},
{
"id": "6d7f4f2f-7ea7-4c56-8082-dfdce67f5487",
"status": "ACT",
"full_name": "P.J. Washington Jr.",
"first_name": "P.J.",
"last_name": "Washington",
"abbr_name": "P.Washington",
"height": 79,
"weight": 230,
"position": "F",
"primary_position": "PF",
"jersey_number": "25",
"experience": "5",
"college": "Kentucky",
"high_school": "Prime Prep (TX)",
"birth_place": "Louisville, KY, USA",
"birthdate": "1998-08-23",
"updated": "2024-07-21T01:22:11Z",
"name_suffix": "Jr.",
"sr_id": "sr:player:1307734",
"rookie_year": 2019,
"reference": "1629023",
"draft": {
"team_id": "583ec97e-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2019,
"round": "1",
"pick": "12"
}
},
{
"id": "8426ab40-888d-4f89-976c-cd9e23717653",
"status": "ACT",
"full_name": "Spencer Dinwiddie",
"first_name": "Spencer",
"last_name": "Dinwiddie",
"abbr_name": "S.Dinwiddie",
"height": 77,
"weight": 215,
"position": "G",
"primary_position": "PG",
"jersey_number": "26",
"experience": "10",
"college": "Colorado",
"high_school": "William Howard Taft (CA)",
"birth_place": "Los Angeles, CA, USA",
"birthdate": "1993-04-06",
"updated": "2024-08-14T19:20:36Z",
"sr_id": "sr:player:607360",
"rookie_year": 2014,
"reference": "203915",
"draft": {
"team_id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2014,
"round": "2",
"pick": "38"
}
},
{
"id": "a15f73b1-f757-4af2-b09a-f0185e09c8bf",
"status": "ACT",
"full_name": "Naji Marshall",
"first_name": "Naji",
"last_name": "Marshall",
"abbr_name": "N.Marshall",
"height": 78,
"weight": 220,
"position": "F",
"primary_position": "SF",
"jersey_number": "13",
"experience": "4",
"college": "Xavier",
"high_school": "Hargrave Military Academy (VA)",
"birth_place": "Atlantic City, NJ, USA",
"birthdate": "1998-01-24",
"updated": "2024-07-21T01:21:50Z",
"sr_id": "sr:player:2106618",
"rookie_year": 2020,
"reference": "1630230",
"draft": {
"year": 2020
}
},
{
"id": "a465418b-0933-40b4-8f01-253d046872e1",
"status": "ACT",
"full_name": "Dwight Powell",
"first_name": "Dwight",
"last_name": "Powell",
"abbr_name": "D.Powell",
"height": 82,
"weight": 240,
"position": "F-C",
"primary_position": "C",
"jersey_number": "7",
"experience": "10",
"college": "Stanford",
"high_school": "IMG Academy (FL)",
"birth_place": "Toronto, ON, CAN",
"birthdate": "1991-07-20",
"updated": "2024-07-21T01:21:32Z",
"sr_id": "sr:player:608166",
"rookie_year": 2014,
"reference": "203939",
"draft": {
"team_id": "583ec97e-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2014,
"round": "2",
"pick": "45"
}
},
{
"id": "a8d25a06-b47e-4a08-a945-7bf0dd945584",
"status": "ACT",
"full_name": "Jaden Hardy",
"first_name": "Jaden",
"last_name": "Hardy",
"abbr_name": "J.Hardy",
"height": 75,
"weight": 198,
"position": "G",
"primary_position": "SG",
"jersey_number": "1",
"experience": "2",
"high_school": "Coronado (NV)",
"birth_place": "Detroit, MI, USA",
"birthdate": "2002-07-05",
"updated": "2024-07-21T01:20:50Z",
"sr_id": "sr:player:2299171",
"rookie_year": 2022,
"reference": "1630702",
"draft": {
"team_id": "583ed0ac-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2022,
"round": "2",
"pick": "37"
}
},
{
"id": "c2ad9bcf-7920-46ce-a124-dc21e98ca72d",
"status": "TWO-WAY",
"full_name": "Kessler Edwards",
"first_name": "Kessler",
"last_name": "Edwards",
"abbr_name": "K.Edwards",
"height": 79,
"weight": 203,
"position": "F",
"primary_position": "SF",
"jersey_number": "20",
"experience": "3",
"college": "Pepperdine",
"high_school": "Etiwanda (CA)",
"birth_place": "Glendale, CA, USA",
"birthdate": "2000-08-09",
"updated": "2024-08-21T00:22:08Z",
"sr_id": "sr:player:1586640",
"rookie_year": 2021,
"reference": "1630556",
"draft": {
"team_id": "583ec9d6-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2021,
"round": "2",
"pick": "44"
}
},
{
"id": "c8efed0b-f365-4440-84f7-df8c8078d1c0",
"status": "TWO-WAY",
"full_name": "Brandon Williams",
"first_name": "Brandon",
"last_name": "Williams",
"abbr_name": "B.Williams",
"height": 74,
"weight": 190,
"position": "G",
"primary_position": "PG",
"jersey_number": "00",
"experience": "2",
"college": "Arizona",
"high_school": "Crespi Carmelite (CA)",
"birth_place": "Los Angeles, CA, USA",
"birthdate": "1999-11-22",
"updated": "2024-07-21T01:20:43Z",
"sr_id": "sr:player:2281033",
"rookie_year": 2021,
"reference": "1630314",
"draft": {
"year": 2020
}
},
{
"id": "d2ee92e9-3e72-45eb-b156-2dc5adc1e6f7",
"status": "ACT",
"full_name": "Luka Dončić",
"first_name": "Luka",
"last_name": "Dončić",
"abbr_name": "L.Dončić",
"height": 79,
"weight": 230,
"position": "F-G",
"primary_position": "PG",
"jersey_number": "77",
"experience": "6",
"birth_place": "Ljubljana,, SVN",
"birthdate": "1999-02-28",
"updated": "2024-09-16T12:56:48Z",
"sr_id": "sr:player:926008",
"rookie_year": 2018,
"reference": "1629029",
"draft": {
"team_id": "583ecb8f-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2018,
"round": "1",
"pick": "3"
}
},
{
"id": "dd146010-902b-4ad7-b98c-650d0363a2f0",
"status": "ACT",
"full_name": "Kyrie Irving",
"first_name": "Kyrie",
"last_name": "Irving",
"abbr_name": "K.Irving",
"height": 74,
"weight": 195,
"position": "G",
"primary_position": "PG",
"jersey_number": "11",
"experience": "13",
"college": "Duke",
"high_school": "St. Patrick (NJ)",
"birth_place": "Melbourne,, AUS",
"birthdate": "1992-03-23",
"updated": "2024-07-21T01:21:44Z",
"sr_id": "sr:player:608268",
"rookie_year": 2011,
"reference": "202681",
"draft": {
"team_id": "583ec773-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2011,
"round": "1",
"pick": "1"
}
},
{
"id": "e8486226-53e1-4857-b5f0-8b6fe88bdd8a",
"status": "ACT",
"full_name": "Quentin Grimes",
"first_name": "Quentin",
"last_name": "Grimes",
"abbr_name": "Q.Grimes",
"height": 77,
"weight": 210,
"position": "G",
"primary_position": "SG",
"jersey_number": "5",
"experience": "3",
"college": "Houston",
"high_school": "The Woodlands College Park (TX)",
"birth_place": "Houston, TX, USA",
"birthdate": "2000-05-08",
"updated": "2024-07-21T01:21:22Z",
"sr_id": "sr:player:1491436",
"rookie_year": 2021,
"reference": "1629656",
"draft": {
"team_id": "583ecdfb-fb46-11e1-82cb-f4ce4684ea4c",
"year": 2021,
"round": "1",
"pick": "25"
}
}
]
}
Use Cases:
If you are developing a mobile app for fantasy basketball enthusiasts, you might want to display the active players on NBA teams. This feature allows users to make informed decisions for their fantasy drafts and team management by providing up-to-date information on which players are currently active and eligible to score points in upcoming games.
The following is an example of how you can display a team roster on your platform, showcasing key details such as player names, jersey numbers, positions, age, height, and weight.
Accessing Headshots and Team Logos
To access team logos and player headshots, use the Images API.
Position on the Court
Primary Position
Since basketball positions can be more fluid than in sports like football or hockey, with players often switching roles during a game, we use primary_position to highlight a player’s main role on the court.
This designation focuses on key positions: PG (Point Guard), SG (Shooting Guard), SF (Small Forward), PF (Power Forward), or C (Center). You can find this data in the following feeds:
- Daily Transfers
- Free Agents
- Game Boxscore
- Game Summary
- Injuries
- League Leaders
- Player Profile
- Seasonal Statistics
- Splits
- Team Profile
- Push Statistics
You’ll typically see Primary Position added closer to the start of the season, once there’s more information about what position the player will play or has already played in the NBA. That’s why primary position for rookies won’t be finalized until just before the season begins.
Position
Position is a broader term used to distinguish between frontcourt and backcourt players. This information is provided directly by the NBA, and as their official partner, we maintain consistency with the league’s designations.
Some players may switch between SF, PF, or C depending on the lineup. In these cases, you might opt to use the position field as "F-C" for simplicity, as it's more concise than listing "SF-PF-C."
Depth Charts
The NBA Depth Charts serve as a general guide to what a team's rotation looks like when all active players are fully healthy (i.e., not missing more than a few consecutive games).
How to Access Depth Chart Data: You can access depth chart data using the Team Depth Charts feed. This endpoint provides a current depth chart for all positions on a given team.
Recommended Pull Frequency (During the REG Season):
- Depth charts are updated several times during the week to ensure it's up-to-date
- Pull every hour or less, depending on your use case.
- The TTL for this feed is 120 seconds.
Please Note
Depth charts are not updated on a game-by-game basis.
Example:
{
"id": "583eca2f-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Timberwolves",
"market": "Minnesota",
"alias": "MIN",
"founded": 1989,
"sr_id": "sr:team:3426",
"reference": "1610612750",
"venue": {
"id": "7aed802e-3562-5b73-af1b-3859529f9b95",
"name": "Target Center",
"capacity": 19356,
"address": "600 First Avenue North",
"city": "Minneapolis",
"state": "MN",
"zip": "55403",
"country": "USA",
"sr_id": "sr:venue:6930",
"location": {
"lat": "44.979444",
"lng": "-93.276111"
}
},
"league": {
"id": "4353138d-4c22-4396-95d8-5f587d2df25c",
"name": "NBA",
"alias": "NBA"
},
"conference": {
"id": "7fe7e212-de01-4f8f-a31d-b9f0a95731e3",
"name": "WESTERN CONFERENCE",
"alias": "WESTERN"
},
"division": {
"id": "12bf14ba-eb16-4c6f-8275-e801b6947c1e",
"name": "Northwest",
"alias": "NORTHWEST"
},
"coaches": [
{
"id": "fc135b85-7a10-4df9-b32b-6e23b0ca04a2",
"full_name": "Chris Finch",
"first_name": "Chris",
"last_name": "Finch",
"position": "Head Coach",
"experience": "5",
"reference": "202896"
}
],
"positions": {
"SG": {
"id": "0b314789-ce5c-4b4b-af0d-c7152001e5b7",
"name": "SG",
"desc": "Shooting Guard",
"players": [
{
"id": "d0c7135a-1aea-40cb-ba20-df656de71749",
"full_name": "Anthony Edwards",
"primary_position": "SG",
"position": "G",
"jersey_number": "5",
"reference": "1630162",
"depth": 1,
"sr_id": "sr:player:1876136"
}
]
},
"PG": {
"id": "c631de0f-3422-4c9e-9aa6-88c742038416",
"name": "PG",
"desc": "Point Guard",
"players": [
{
"id": "460b7264-b98f-483e-b841-59a18c2e4d67",
"full_name": "Mike Conley",
"primary_position": "PG",
"position": "G",
"jersey_number": "10",
"reference": "201144",
"depth": 1,
"sr_id": "sr:player:608194"
}
]
},
"C": {
"id": "1e4023e1-cd67-4a43-bb51-e731b7d4dc2b",
"name": "C",
"desc": "Center",
"players": [
{
"id": "37fbc3a5-0d10-4e22-803b-baa2ea0cdb12",
"full_name": "Rudy Gobert",
"primary_position": "C",
"position": "C",
"jersey_number": "27",
"reference": "203497",
"depth": 1,
"sr_id": "sr:player:607808"
}
]
},
"PF": {
"id": "70c1dd00-e304-4932-8d8b-09500dfafc01",
"name": "PF",
"desc": "Power Forward",
"players": [
{
"id": "ab532a66-9314-4d57-ade7-bb54a70c65ad",
"full_name": "Karl-Anthony Towns",
"primary_position": "C",
"position": "C-F",
"jersey_number": "32",
"reference": "1626157",
"depth": 1,
"sr_id": "sr:player:852120"
}
]
},
"SF": {
"id": "7b9bacc9-e15b-449c-83e8-ddf9e25b8f66",
"name": "SF",
"desc": "Small Forward",
"players": [
{
"id": "aa5536d2-4d75-43fb-8df3-47fbf99d3b7c",
"full_name": "Jaden McDaniels",
"primary_position": "PF",
"position": "F",
"jersey_number": "3",
"reference": "1630183",
"depth": 1,
"sr_id": "sr:player:1837406"
},
{
"id": "5b297372-b2af-445e-a4bc-777982dbc1e3",
"full_name": "Joe Ingles",
"primary_position": "SF",
"position": "F-G",
"jersey_number": "7",
"reference": "204060",
"depth": 2,
"sr_id": "sr:player:611966"
}
]
}
}
}
This code sample outlines the Minnesota Timberwolves' roster, showing the depth chart for key positions such as Shooting Guard (SG), Point Guard (PG), Center (C), Power Forward (PF), and Small Forward (SF). It provides details for each position, including primary and backup players, along with their unique player IDs, names, jersey numbers, and roles within the team. The code also includes team information like the Timberwolves' ID, market, founding year, and venue details (Target Center), along with coaching staff data, specifically the head coach Chris Finch and his experience.
Transactions
NBA transactions refer to the movements of players between teams through trades, free agency signings, releases, or waivers.
How Transactions are Monitored and Updated:
- Once reputable sources have sourced a trade, our team will process the trade.
- NBA transactions occur year-round, with the only quiet period being the few weeks between the NBA Finals and the start of Free Agency in June. Otherwise, player movement and team changes happen continuously throughout the year.
How to Access Transactions: You can access daily transaction updates using the Daily Transfers feed, which provides details of all transactions added or edited throughout each league-defined day.
Waiving Players
In the NBA, the term "waive" refers to a process where players with less than four years of service time are put on the waiver wire, making them available for other teams to claim under the same contract conditions. If unclaimed, these players become unrestricted free agents. This system allows teams to potentially pick up young talent that has been let go by other teams.
Recommended Pull Frequency:
- The feed updates in real-time as transactions occur.
- Depending on your needs, you might consider pulling data hourly.
- The TTL for this feed is 300 seconds.
Tip - Track Effective Dates
To ensure accuracy in tracking player movements, always check the
effective_datein transaction data as it specifies when changes officially take place.
Example:
{
"league": {
"id": "4353138d-4c22-4396-95d8-5f587d2df25c",
"name": "NBA",
"alias": "NBA"
},
"start_time": "2024-02-07T05:00:00Z",
"end_time": "2024-02-08T04:59:59Z",
"players": [
{
"id": "239f0ff0-3d09-4991-bb67-ad8c8b7fd0cb",
"full_name": "Kevin Knox II",
"first_name": "Kevin",
"last_name": "Knox",
"position": "F",
"primary_position": "SF",
"name_suffix": "II",
"sr_id": "sr:player:1307730",
"reference": "1628995",
"transfers": [
{
"id": "12116b87-e93c-4964-af89-73bf5404c590",
"desc": "The Detroit Pistons traded F Kevin Knox II to the Utah Jazz.",
"effective_date": "2024-02-07",
"last_modified": "2024-02-07T18:05:48Z",
"transaction_type": "Traded",
"transaction_code": "TRD",
"from_team": {
"id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Pistons",
"market": "Detroit",
"reference": "1610612765"
},
"to_team": {
"id": "583ece50-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Jazz",
"market": "Utah",
"reference": "1610612762"
}
}
]
},
{
"id": "5350a897-aa31-4510-8feb-e709e1feb844",
"full_name": "Troy Brown Jr.",
"first_name": "Troy",
"last_name": "Brown",
"position": "F",
"primary_position": "SF",
"name_suffix": "Jr.",
"sr_id": "sr:player:1320578",
"reference": "1628972",
"transfers": [
{
"id": "3529719b-4b79-467a-9668-b6a718b05317",
"desc": "The Minnesota Timberwolves traded F Troy Brown Jr. to the Detroit Pistons.",
"effective_date": "2024-02-07",
"last_modified": "2024-02-07T21:56:56Z",
"transaction_type": "Traded",
"transaction_code": "TRD",
"from_team": {
"id": "583eca2f-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Timberwolves",
"market": "Minnesota",
"reference": "1610612750"
},
"to_team": {
"id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Pistons",
"market": "Detroit",
"reference": "1610612765"
}
}
]
},
{
"id": "5722e429-752c-41f7-9b75-e3fc712f14f1",
"full_name": "Shake Milton",
"first_name": "Shake",
"last_name": "Milton",
"position": "G",
"primary_position": "SG",
"sr_id": "sr:player:1495351",
"reference": "1629003",
"transfers": [
{
"id": "35a353d7-0083-4384-ba57-1cabc7685b0d",
"desc": "The Minnesota Timberwolves traded G Shake Milton to the Detroit Pistons.",
"effective_date": "2024-02-07",
"last_modified": "2024-02-07T21:57:15Z",
"transaction_type": "Traded",
"transaction_code": "TRD",
"from_team": {
"id": "583eca2f-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Timberwolves",
"market": "Minnesota",
"reference": "1610612750"
},
"to_team": {
"id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Pistons",
"market": "Detroit",
"reference": "1610612765"
}
}
]
},
{
"id": "fda266ab-06e1-4591-80fa-73f027979b63",
"full_name": "Simone Fontecchio",
"first_name": "Simone",
"last_name": "Fontecchio",
"position": "F",
"primary_position": "SF",
"sr_id": "sr:player:927466",
"reference": "1631323",
"transfers": [
{
"id": "71b61feb-1c89-4515-bd83-2ecee0e2d964",
"desc": "The Utah Jazz traded F Simone Fontecchio to the Detroit Pistons.",
"effective_date": "2024-02-07",
"last_modified": "2024-02-07T18:02:09Z",
"transaction_type": "Traded",
"transaction_code": "TRD",
"from_team": {
"id": "583ece50-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Jazz",
"market": "Utah",
"reference": "1610612762"
},
"to_team": {
"id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Pistons",
"market": "Detroit",
"reference": "1610612765"
}
}
]
},
{
"id": "48b05ddf-0a9f-4426-9394-231c54726eaa",
"full_name": "Monte Morris",
"first_name": "Monte",
"last_name": "Morris",
"position": "G",
"primary_position": "PG",
"sr_id": "sr:player:1142586",
"reference": "1628420",
"transfers": [
{
"id": "a3351cb0-5c33-4941-9446-2224904ff52f",
"desc": "The Detroit Pistons traded G Monte Morris to the Minnesota Timberwolves.",
"effective_date": "2024-02-07",
"last_modified": "2024-02-07T21:56:11Z",
"transaction_type": "Traded",
"transaction_code": "TRD",
"from_team": {
"id": "583ec928-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Pistons",
"market": "Detroit",
"reference": "1610612765"
},
"to_team": {
"id": "583eca2f-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Timberwolves",
"market": "Minnesota",
"reference": "1610612750"
}
}
]
},
{
"id": "fb60c435-dd40-401e-977b-15bdbb753444",
"full_name": "Xavier Tillman Sr.",
"first_name": "Xavier",
"last_name": "Tillman",
"position": "F-C",
"primary_position": "PF",
"name_suffix": "Sr.",
"sr_id": "sr:player:1316832",
"reference": "1630214",
"transfers": [
{
"id": "f45c151b-9d0d-4118-a927-6cb8ff9a4e30",
"desc": "The Memphis Grizzlies traded F-C Xavier Tillman Sr. to the Boston Celtics.",
"effective_date": "2024-02-07",
"last_modified": "2024-02-07T19:36:36Z",
"transaction_type": "Traded",
"transaction_code": "TRD",
"from_team": {
"id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Grizzlies",
"market": "Memphis",
"reference": "1610612763"
},
"to_team": {
"id": "583eccfa-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Celtics",
"market": "Boston",
"reference": "1610612738"
}
}
]
}
]
}
This code sample illustrates how you can use the NBA's transaction feed to track player movements within the league. It provides detailed information on trades involving players such as Kevin Knox II, Troy Brown Jr., and Simone Fontecchio. Each transaction includes data like the player's ID, name, position, and details about the trade, such as the teams involved (e.g., the Detroit Pistons and Utah Jazz), the transaction type (e.g., traded), and the effective date. This allows for real-time tracking of player movements, making it useful for building applications that monitor team rosters and player transfers throughout the season.
Use Case: As a developer working on a sports news aggregation app, you can use this NBA transaction feed to provide real-time updates on player moves and status changes directly on your platform. This keeps your users informed with the latest happenings in the league, especially during the active trading and signing periods. For example, you could highlight major transactions like trades, signings, or injury-related changes, enhancing the timeliness and relevance of the content on your app.
Transaction and Code Types
For the full list of transaction and code types, visit our NBA FAQ.
Injury Data
Accessing injury data is crucial for managing NBA rosters, as it helps teams assess player availability and make strategic decisions.
How to Access Injury Data: You can access injury data using the Daily Injuries feed. This endpoint provides a list of injured players for each team for a given day, including practice status. Please note, we do not provide live injuries.
What if a Player Is Listed as Out Prior to a Game?
Our roster team updates injury reports before games; however, players listed as questionable or expected to play may still not participate. To get the most accurate player status, it's best to check the game endpoints (PBP, Game Boxscore, and Game Summary) for real-time updates.
Recommended Pull Frequency:
- We monitor and update injuries throughout the day during the season, using a combination of official and reliable sources.
- Pull every hour or less during the season, depending on your use case.
- The TTL for this feed is 300 seconds.
Example - Daily Injuries:
{
"league": {
"id": "4353138d-4c22-4396-95d8-5f587d2df25c",
"name": "NBA",
"alias": "NBA"
},
"date": "2024-03-20",
"teams": [
{
"id": "583ecefd-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Bucks",
"market": "Milwaukee",
"sr_id": "sr:team:3410",
"reference": "1610612749",
"players": [
{
"id": "fc036630-debc-44bf-9663-03c3fbd3045c",
"full_name": "MarJon Beauchamp",
"first_name": "MarJon",
"last_name": "Beauchamp",
"position": "F",
"primary_position": "SF",
"jersey_number": "3",
"sr_id": "sr:player:2299173",
"reference": "1630699",
"injuries": [
{
"id": "0811fc9c-d6f6-4d86-acc2-95158c5569c3",
"comment": "The Bucks have listed Beauchamp as PROBABLE for Wednesday's game (Mar. 20) against the Celtics.",
"desc": "Ankle",
"status": "Day To Day",
"start_date": "2024-03-11",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583ecfa8-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Suns",
"market": "Phoenix",
"sr_id": "sr:team:3416",
"reference": "1610612756",
"players": [
{
"id": "6395ff32-c9b6-4ad0-8f0f-dce474274725",
"full_name": "Bol Bol",
"first_name": "Bol",
"last_name": "Bol",
"position": "C-F",
"primary_position": "PF",
"jersey_number": "11",
"sr_id": "sr:player:1491398",
"reference": "1629626",
"injuries": [
{
"id": "0dc890c5-dba7-4789-97dd-99aa2d7546c7",
"comment": "The Suns have listed Bol as PROBABLE for Wednesday's game (Mar. 20) against the 76ers.",
"desc": "Ankle",
"status": "Day To Day",
"start_date": "2024-03-20",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583ec825-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Warriors",
"market": "Golden State",
"sr_id": "sr:team:3428",
"reference": "1610612744",
"players": [
{
"id": "5e5099d1-4a58-43f2-8d03-f2ae5dd49337",
"full_name": "Draymond Green",
"first_name": "Draymond",
"last_name": "Green",
"position": "F",
"primary_position": "PF",
"jersey_number": "23",
"sr_id": "sr:player:608020",
"reference": "203110",
"injuries": [
{
"id": "117e08c1-9102-451a-8f00-56dfacc7a2c3",
"comment": "The Warriors have listed Green as QUESTIONABLE for Wednesday's game (Mar. 20) against the Grizzlies.",
"desc": "Back",
"status": "Day To Day",
"start_date": "2024-03-20",
"update_date": "2024-03-20"
}
]
},
{
"id": "a316cf6a-693d-4c6a-b0d9-ebf80e73e832",
"full_name": "Moses Moody",
"first_name": "Moses",
"last_name": "Moody",
"position": "G",
"primary_position": "SG",
"jersey_number": "4",
"sr_id": "sr:player:2077831",
"reference": "1630541",
"injuries": [
{
"id": "f10991eb-75ee-4418-8402-ca6903faff87",
"comment": "The Warriors have listed Moody as QUESTIONABLE for Wednesday's game (Mar. 20) against the Grizzlies.",
"desc": "Knee",
"status": "Day To Day",
"start_date": "2024-03-20",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583ed056-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Trail Blazers",
"market": "Portland",
"sr_id": "sr:team:3414",
"reference": "1610612757",
"players": [
{
"id": "632adcc4-97f1-4e67-a132-e0b79f013c67",
"full_name": "Anfernee Simons",
"first_name": "Anfernee",
"last_name": "Simons",
"position": "G",
"primary_position": "SG",
"jersey_number": "1",
"sr_id": "sr:player:1479148",
"reference": "1629014",
"injuries": [
{
"id": "28013efe-4db9-4f3c-990c-73841c638a28",
"comment": "THe Trail Blazers listed Simons as QUESTIONABLE for Wednesday's (Mar. 20) game against the Clippers. ",
"desc": "Knee",
"status": "Day To Day",
"start_date": "2024-03-20",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583ece50-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Jazz",
"market": "Utah",
"sr_id": "sr:team:3434",
"reference": "1610612762",
"players": [
{
"id": "28a2e698-9f33-4d4d-9a5d-9bea66ee42a1",
"full_name": "John Collins",
"first_name": "John",
"last_name": "Collins",
"position": "F-C",
"primary_position": "PF",
"jersey_number": "20",
"sr_id": "sr:player:1141198",
"reference": "1628381",
"injuries": [
{
"id": "28550d1b-1495-4fd0-932d-e34b9a98004e",
"comment": "The Jazz have listed Collins as QUESTIONABLE for Wednesday's game (Mar. 20) against the Thunder.",
"desc": "Face",
"status": "Day To Day",
"start_date": "2024-03-20",
"update_date": "2024-03-20"
}
]
},
{
"id": "583d7994-36f9-4a9a-b527-c18704406981",
"full_name": "Lauri Markkanen",
"first_name": "Lauri",
"last_name": "Markkanen",
"position": "F-C",
"primary_position": "PF",
"jersey_number": "23",
"sr_id": "sr:player:1141204",
"reference": "1628374",
"injuries": [
{
"id": "a3b888da-1700-4226-b61e-fd7581c7a500",
"comment": "The Jazz have listed Markkanen as OUT for Wednesday's game (Mar. 20) against the Thunder.",
"desc": "Rest-Injury Maintenance",
"status": "Out",
"start_date": "2024-03-20",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583eccfa-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Celtics",
"market": "Boston",
"sr_id": "sr:team:3422",
"reference": "1610612738",
"players": [
{
"id": "ffc5579c-783f-4d62-80ab-3c3dcb05a27d",
"full_name": "Jaylen Brown",
"first_name": "Jaylen",
"last_name": "Brown",
"position": "G-F",
"primary_position": "SF",
"jersey_number": "7",
"sr_id": "sr:player:996297",
"reference": "1627759",
"injuries": [
{
"id": "5e2501f0-22a0-42cb-8e91-99f311d99abe",
"comment": "The Celtics have listed Brown as QUESTIONABLE for Wednesday's game (Mar. 20) against the Bucks.",
"desc": "Ankle",
"status": "Day To Day",
"start_date": "2024-03-19",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583ecea6-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Heat",
"market": "Miami",
"sr_id": "sr:team:3435",
"reference": "1610612748",
"players": [
{
"id": "d31856fa-e1ff-4617-ab8b-a3ed79bfb27d",
"full_name": "Nikola Jovic",
"first_name": "Nikola",
"last_name": "Jovic",
"position": "F",
"primary_position": "PF",
"jersey_number": "5",
"sr_id": "sr:player:2088167",
"reference": "1631107",
"injuries": [
{
"id": "7ac95094-dad6-4d7b-ad46-672b852c1edb",
"comment": "The Heat have listed Jovic as QUESTIONABLE for Wednesday's game (Mar. 20) against the Cavaliers.",
"desc": "Hamstring",
"status": "Day To Day",
"start_date": "2024-03-16",
"update_date": "2024-03-20"
}
]
},
{
"id": "0e163d44-67a7-4107-9421-5333600166bb",
"full_name": "Jimmy Butler",
"first_name": "Jimmy",
"last_name": "Butler",
"position": "F",
"primary_position": "SF",
"jersey_number": "22",
"sr_id": "sr:player:607444",
"reference": "202710",
"injuries": [
{
"id": "bafd0506-ced7-481c-94f8-fb97e564f5d7",
"comment": "The Heat have listed Butler as QUESTIONABLE for Wednesday's game (Mar. 20) against the Cavaliers.",
"desc": "Foot",
"status": "Day To Day",
"start_date": "2024-03-16",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583eca88-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Grizzlies",
"market": "Memphis",
"sr_id": "sr:team:3415",
"reference": "1610612763",
"players": [
{
"id": "266cd359-f378-45c6-957e-6e21378e5219",
"full_name": "Santi Aldama",
"first_name": "Santi",
"last_name": "Aldama",
"position": "F",
"primary_position": "PF",
"jersey_number": "7",
"sr_id": "sr:player:1876228",
"reference": "1630583",
"injuries": [
{
"id": "c52d7155-d0a3-4793-b257-cd44a40d6a74",
"comment": "The Grizzlies have listed Aldama as QUESTIONABLE for Wednesday's game (Mar. 20) against the Warriors.",
"desc": "Elbow",
"status": "Day To Day",
"start_date": "2024-03-20",
"update_date": "2024-03-20"
}
]
}
]
},
{
"id": "583ec8d4-fb46-11e1-82cb-f4ce4684ea4c",
"name": "Wizards",
"market": "Washington",
"sr_id": "sr:team:3431",
"reference": "1610612764",
"players": [
{
"id": "4fae86e2-4f99-4247-af85-d917b4389d31",
"full_name": "Kyle Kuzma",
"first_name": "Kyle",
"last_name": "Kuzma",
"position": "F",
"primary_position": "PF",
"jersey_number": "33",
"sr_id": "sr:player:1142582",
"reference": "1628398",
"injuries": [
{
"id": "fb625421-5660-4a37-9d65-61e272472f2f",
"comment": "Kuzma did not play in Tuesday's (Mar. 19) game against the Rockets.",
"desc": "Shoulder",
"status": "Day To Day",
"start_date": "2024-03-17",
"update_date": "2024-03-20"
}
]
}
]
}
]
}
This JSON code sample provides detailed injury updates for NBA players on a team-by-team basis for games scheduled on March 20, 2024. It lists the injury status for players such as MarJon Beauchamp (Milwaukee Bucks), Bol Bol (Phoenix Suns), and Draymond Green (Golden State Warriors), including details about the type of injury (e.g., ankle, back), the player's current status (e.g., probable, questionable), and the latest update date. This data is essential for applications focusing on sports management, fantasy leagues, betting, or fan engagement, enabling real-time integration of player health and availability into platforms.
The following is an example of how you can visualize injury data.
Daily Change Log
The Daily Change Log endpoint provides an efficient way to monitor daily updates within the NBA API, including roster adjustments, transactions, and corrections to player injury details, without exhausting your API call quota.
The table below outlines scenarios and use cases for utilizing the Daily Change Log based on team roster and player updates.
Steps to monitor roster updates:
-
Identify Change Types: First, review the Daily Change Log to identify the types of changes reported. These could be related to games, players, or teams. Each entry in the log will list relevant IDs (game, player, or team ID), depending on the type of change.
-
Use IDs to Retrieve Specifics: IDs associated with players or teams indicate changes relevant to these entities, such as updates to team rosters.
-
Pull Detailed Data: Use the identified IDs to pull detailed information from the Team Profile feed.
-
Verify Changes: After pulling the data, compare the newly retrieved data against previously stored data to verify the changes and update your records accordingly.
Update Frequency
TTL / Cache: 300 seconds
Data Updates:
- Entries populate live for changes to teams, players, game statistics, schedules, and standings.
- Start time of the log is 05:00:00 UTC; end time is 04:59:59 UTC
For optimal results, set a regular schedule to pull every 10 minutes or less (depending on your use case) to access the feed.
Data Entry Workflow Information
For detailed information on when roster, injury, and transaction data are added to the API, refer to the NBA Data Entry workflow documentation.
Updated 2 days ago