NBA API
Welcome to the BALLDONTLIE NBA API, the best NBA API on the planet. The API contains data from 1946-current. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.
Download language specific libraries:
Take a look at our other APIs.
Join us on discord.
AI-Powered Integration
Using the OpenAPI Specification with AI
Our complete OpenAPI specification allows AI assistants to automatically understand and interact with our API. Simply share the spec URL with your AI assistant and describe what you want to build—the AI will handle the technical implementation.
Getting Started with AI:
- Copy this URL:
https://www.balldontlie.io/openapi.yml - Share it with your preferred AI assistant (ChatGPT, Claude, Gemini, etc.)
- Tell the AI what you want to build (e.g., "Create a dashboard showing today's NBA games")
- The AI will read the OpenAPI spec and write the code for you
Example prompts to try:
- "Using the OpenAPI spec at https://www.balldontlie.io/openapi.yml, show me how to get LeBron James' season stats"
- "Read the BALLDONTLIE OpenAPI spec and create a Python script that fetches today's NBA games"
- "Help me understand the available NBA endpoints from this OpenAPI spec: https://www.balldontlie.io/openapi.yml"
This makes it incredibly easy for non-technical users, analysts, and researchers to leverage our sports data without needing to learn programming from scratch.
Google Sheets Integration
Our Google Sheets integration lets you access all the same data available through our API using simple spreadsheet formulas. Perfect for fantasy sports tracking, betting analysis, and sports research.
Quick Start:
- Get your API key from app.balldontlie.io
- Copy our Google Sheets script
- Paste it into your Google Sheet (Extensions > Apps Script)
- Start using functions in your cells
Example functions:
=BDL_NBA_PLAYERS("LeBron")- Search for players=BDL_NBA_GAMES("2026-01-27")- Get games by date=BDL_NBA_STANDINGS(2026)- Get current standings=BDL_NBA_ODDS("2026-01-27")- Get betting odds
For full setup instructions and the complete list of 150+ functions, see our Google Sheets Integration Guide.
Account Tiers
There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.
Paid tiers do not apply across sports. The tier you purchase for NBA will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($299.99/mo) tier to get access to every endpoint for every sport.
Read the table below to see the breakdown.
| Endpoint | Free | ALL-STAR | GOAT |
|---|---|---|---|
| Teams | Yes | Yes | Yes |
| Players | Yes | Yes | Yes |
| Games | Yes | Yes | Yes |
| Game Player Stats | No | Yes | Yes |
| Active Players | No | Yes | Yes |
| Player Injuries | No | Yes | Yes |
| Season Averages | No | No | Yes |
| Team Season Averages | No | No | Yes |
| Game Advanced Stats | No | No | Yes |
| Box Scores | No | No | Yes |
| Lineups | No | No | Yes |
| Team Standings | No | No | Yes |
| Leaders | No | No | Yes |
| Betting Odds | No | No | Yes |
| Player Props | No | No | Yes |
| Team Contracts | No | No | Yes |
| Player Contracts | No | No | Yes |
| Player Contract Aggregates | No | No | Yes |
| Plays | No | No | Yes |
The feature breakdown per tier is shown in the table below.
| Tier | Requests / Min | $USD / mo. |
|---|---|---|
| GOAT | 600 | 39.99 |
| ALL-STAR | 60 | 9.99 |
| Free | 5 | 0 |
Authentication
To authorize, use this code:
curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
Make sure to replace
YOUR_API_KEYwith your API key.
BALLDONTLIE uses API keys to allow access to the API. You can obtain an API key by creating a free account at our website
We expect the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: YOUR_API_KEY
Pagination
This API uses cursor based pagination rather than limit/offset. Endpoints that support pagination will send back responses with a meta key that looks like what is displayed on the right.
{
"meta": {
"next_cursor": 90,
"per_page": 25
}
}
You can use per_page to specify the maximum number of results. It defaults to 25 and doesn't allow values larger than 100.
You can use next_cursor to get the next page of results. Specify it in the request parameters like this: ?cursor=NEXT_CURSOR.
Errors
The API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 401 | Unauthorized - You either need an API key or your account tier does not have access to the endpoint. |
| 400 | Bad Request -- The request is invalid. The request parameters are probably incorrect. |
| 404 | Not Found -- The specified resource could not be found. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 429 | Too Many Requests -- You're rate limited. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Teams
Get All Teams
curl "https://api.balldontlie.io/v1/teams" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const teams = await api.nba.getTeams();
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
teams = api.nba.teams.list()
The above command returns JSON structured like this:
{
"data": [
{
"id":1,
"conference":"East",
"division":"Southeast",
"city":"Atlanta",
"name":"Hawks",
"full_name":"Atlanta Hawks",
"abbreviation":"ATL"
},
...
]
}
This endpoint retrieves all teams.
HTTP Request
GET https://api.balldontlie.io/v1/teams
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| division | false | Returns teams that belong to this division |
| conference | false | Returns teams that belong to this conference |
Get a Specific Team
curl "https://api.balldontlie.io/v1/teams/<ID>" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const teams = await api.nba.getTeam(1);
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
teams = api.nba.teams.get(1)
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"conference": "East",
"division": "Southeast",
"city": "Atlanta",
"name": "Hawks",
"full_name": "Atlanta Hawks",
"abbreviation": "ATL"
}
]
}
This endpoint retrieves a specific team.
HTTP Request
GET https://api.balldontlie.io/v1/teams/<ID>
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| ID | true | The ID of the team to retrieve |
Players
Get All Players
curl "https://api.balldontlie.io/v1/players" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const players = await api.nba.getPlayers();
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
players = api.nba.players.list(per_page=25)
The above command returns JSON structured like this:
{
"data": [
{
"id": 115,
"first_name": "Stephen",
"last_name": "Curry",
"position": "G",
"height": "6-2",
"weight": "185",
"jersey_number": "30",
"college": "Davidson",
"country": "USA",
"draft_year": 2009,
"draft_round": 1,
"draft_number": 7,
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
},
...
],
"meta": {
"next_cursor": 25,
"per_page": 25
}
}
This endpoint retrieves all players.
HTTP Request
GET https://api.balldontlie.io/v1/players
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| search | false | Returns players whose first or last name matches this value. For example, ?search=davis will return players that have 'davis' in their first or last name. |
| first_name | false | Returns players whose first name matches this value. For example, ?search=anthony will return players that have 'anthony' in their first name. |
| last_name | false | Returns players whose last name matches this value. For example, ?search=davis will return players that have 'davis' in their last name. |
| team_ids | false | Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| player_ids | false | Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
Get a Specific Player
curl "https://api.balldontlie.io/v1/players/<ID>" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const player = await api.nba.getPlayer(115);
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
player = api.nba.players.get(115)
The above command returns JSON structured like this:
{
"data": {
"id": 115,
"first_name": "Stephen",
"last_name": "Curry",
"position": "G",
"height": "6-2",
"weight": "185",
"jersey_number": "30",
"college": "Davidson",
"country": "USA",
"draft_year": 2009,
"draft_round": 1,
"draft_number": 7,
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
}
}
This endpoint retrieves a specific player.
HTTP Request
GET https://api.balldontlie.io/v1/players/<ID>
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| ID | true | The ID of the player to retrieve |
Games
Attributes
These response attributes are worth noting:
| Attribute | Type | Values | Notes |
|---|---|---|---|
| period | integer | 0, 1, 2, 3, 4 | 0 will be returned for games that have not started. 4 will be returned when a game is either complete or in the 4th quarter. |
| status | string | {start_time}, 1st Qtr, 2nd Qtr, Halftime, 3rd Qtr, 4th Qtr, Final |
{start_time} looks something like "7:00 pm ET", which indicates that the game has not started yet. |
| time | string | {time_in_period}, " " |
${time_in_period} looks something like "3:44". " " is an empty string that is returned when game has not started or is complete. |
| postponed | boolean | true, false | Indicates whether the game has been postponed. |
| ist_stage | string | null, Championship, East Group A, East Group B, East Group C, East Quarterfinal, East Semifinal, West Group A, West Group B, West Group C, West Quarterfinal, West Semifinal | Only populated for NBA Cup games. null for regular season and playoff games. Only available starting with the 2025 season. |
Get All Games
curl "https://api.balldontlie.io/v1/games" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const games = await api.nba.getGames();
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
games = api.nba.games.list()
The above command returns JSON structured like this:
{
"data": [
"id": 15907925,
"date": "2025-01-05",
"season": 2024,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": false,
"postponed": false,
"home_team_score": 115,
"visitor_team_score": 105,
"datetime": "2025-01-05T23:00:00.000Z",
"home_q1": 29,
"home_q2": 34,
"home_q3": 28,
"home_q4": 24,
"home_ot1": null,
"home_ot2": null,
"home_ot3": null,
"home_timeouts_remaining": 2,
"home_in_bonus": true,
"visitor_q1": 23,
"visitor_q2": 25,
"visitor_q3": 30,
"visitor_q4": 27,
"visitor_ot1": null,
"visitor_ot2": null,
"visitor_ot3": null,
"visitor_timeouts_remaining": 2,
"visitor_in_bonus": false,
"ist_stage": null,
"home_team": {
"id": 6,
"conference": "East",
"division": "Central",
"city": "Cleveland",
"name": "Cavaliers",
"full_name": "Cleveland Cavaliers",
"abbreviation": "CLE"
},
"visitor_team": {
"id": 4,
"conference": "East",
"division": "Southeast",
"city": "Charlotte",
"name": "Hornets",
"full_name": "Charlotte Hornets",
"abbreviation": "CHA"
},
...
],
"meta": {
"next_cursor": 25,
"per_page": 25
}
}
This endpoint retrieves all games.
HTTP Request
GET https://api.balldontlie.io/v1/games
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| dates | false | Returns games that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-01-01&dates[]=2024-01-02 |
| seasons | false | Returns games that occurred in these seasons. This should be an array: ?seasons[]=2022&seasons[]=2023 |
| team_ids | false | Returns games for these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| posteason | false | Returns playoffs games when set to true. Returns regular season games when set to false. Returns both when not specified |
| start_date | false | Returns games that occurred on or after this date. Date should be formatted in YYYY-MM-DD |
| end_date | false | Returns games that occurred on or before this date. Date should be formatted in YYYY-MM-DD |
Get a Specific Game
curl "https://api.balldontlie.io/v1/games/<ID>" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const game = await api.nba.getGame(1);
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
game = api.nba.games.get(1)
The above command returns JSON structured like this:
{
"data": {
"id": 15907925,
"date": "2025-01-05",
"season": 2024,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": false,
"postponed": false,
"home_team_score": 115,
"visitor_team_score": 105,
"datetime": "2025-01-05T23:00:00.000Z",
"home_q1": 29,
"home_q2": 34,
"home_q3": 28,
"home_q4": 24,
"home_ot1": null,
"home_ot2": null,
"home_ot3": null,
"home_timeouts_remaining": 2,
"home_in_bonus": true,
"visitor_q1": 23,
"visitor_q2": 25,
"visitor_q3": 30,
"visitor_q4": 27,
"visitor_ot1": null,
"visitor_ot2": null,
"visitor_ot3": null,
"visitor_timeouts_remaining": 2,
"visitor_in_bonus": false,
"ist_stage": null,
"home_team": {
"id": 6,
"conference": "East",
"division": "Central",
"city": "Cleveland",
"name": "Cavaliers",
"full_name": "Cleveland Cavaliers",
"abbreviation": "CLE"
},
"visitor_team": {
"id": 4,
"conference": "East",
"division": "Southeast",
"city": "Charlotte",
"name": "Hornets",
"full_name": "Charlotte Hornets",
"abbreviation": "CHA"
}
}
}
This endpoint retrieves a specific game.
HTTP Request
GET https://api.balldontlie.io/v1/games/<ID>
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| ID | true | The ID of the game to retrieve |
Game Player Stats
Get All Stats
curl "https://api.balldontlie.io/v1/stats"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const stats = await api.nba.getStats();
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
stats = api.nba.stats.list()
The above command returns JSON structured like this:
{
"data": [
{
"id": 15531179,
"min": "30",
"fgm": 7,
"fga": 18,
"fg_pct": 0.389,
"fg3m": 5,
"fg3a": 9,
"fg3_pct": 0.556,
"ftm": 4,
"fta": 4,
"ft_pct": 1,
"oreb": 2,
"dreb": 5,
"reb": 7,
"ast": 1,
"stl": 1,
"blk": 0,
"turnover": 1,
"pf": 3,
"pts": 23,
"plus_minus": 23,
"player": {
"id": 70,
"first_name": "Jaylen",
"last_name": "Brown",
"position": "G",
"height": "6-6",
"weight": "223",
"jersey_number": "7",
"college": "California",
"country": "USA",
"draft_year": 2016,
"draft_round": 1,
"draft_number": 3,
"team_id": 2
},
"team": {
"id": 2,
"conference": "East",
"division": "Atlantic",
"city": "Boston",
"name": "Celtics",
"full_name": "Boston Celtics",
"abbreviation": "BOS"
},
"game": {
"id": 15907438,
"date": "2024-10-22",
"season": 2024,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": false,
"postponed": false,
"home_team_score": 132,
"visitor_team_score": 109,
"home_team_id": 2,
"visitor_team_id": 20,
"ist_stage": null
}
},
...
],
"meta": {
"next_cursor": 15531179,
"per_page": 25
}
}
This endpoint retrieves all stats.
HTTP Request
GET https://api.balldontlie.io/v1/stats
Query Parameters
You can combine query parameters. For example: ?seasons[]=2018&seasons[]=2015&player_ids[]=1&player_ids[]=2&postseason=true will return stats for player_ids 1 and 2 for the 2015-2016 and 2018-2019 postseason.
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The page number, used for pagination. |
| per_page | false | The number of results returned per call, used for pagination. Max 100. |
| player_ids | false | Returns stats for these player ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
| game_ids | false | Returns stat for these game ids. This should be an array: ?game_ids[]=1&game_ids[]=2 |
| dates | false | Returns stats that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-01-01&dates[]=2024-01-02 |
| seasons | false | Returns stats that occurred in these seasons. This should be an array: ?seasons[]=2022&seasons[]=2023 |
| posteason | false | Returns playoff stats when set to true. Returns regular season stats when set to false. Returns both when not specified |
| start_date | false | Returns stats that occurred on or after this date. Date should be formatted in YYYY-MM-DD |
| end_date | false | Returns stats that occurred on or before this date. Date should be formatted in YYYY-MM-DD |
| period | false | Returns stats for a specific period. 0 returns full game stats (default). 1-4 for quarters, 5+ for overtime periods. Only accepted for completed games. |
Season Averages
Get Averages
There are many types of season averages you can retrieve. You must specify a category in the route and an additional type as a query parameter (except for the hustle category which doesn't require a type parameter). For example: https://api.balldontlie.io/nba/v1/season_averages/general?season=2024&season_type=regular&type=base will return general season averages for the 2024 season. Note the category in this example is general and the type is base.
Here are the available pairing options between category and type:
| Category | Type |
|---|---|
| general | base |
| general | advanced |
| general | usage |
| general | scoring |
| general | defense |
| general | misc |
| clutch | advanced |
| clutch | base |
| clutch | misc |
| clutch | scoring |
| clutch | usage |
| defense | 2_pointers |
| defense | 3_pointers |
| defense | greater_than_15ft |
| defense | less_than_10ft |
| defense | less_than_6ft |
| defense | overall |
| shooting | 5ft_range |
| shooting | by_zone |
| playtype | cut |
| playtype | handoff |
| playtype | isolation |
| playtype | offrebound |
| playtype | offscreen |
| playtype | postup |
| playtype | prballhandler |
| playtype | prrollman |
| playtype | spotup |
| playtype | transition |
| playtype | misc |
| tracking | painttouch |
| tracking | efficiency |
| tracking | speeddistance |
| tracking | defense |
| tracking | elbowtouch |
| tracking | posttouch |
| tracking | passing |
| tracking | drives |
| tracking | rebounding |
| tracking | catchshoot |
| tracking | pullupshot |
| tracking | possessions |
| hustle | (no type required) |
| shotdashboard | overall |
| shotdashboard | pullups |
| shotdashboard | catch_and_shoot |
| shotdashboard | less_than_10_ft |
Regardless of the category + type combination, all data is returned in the same shape. The only difference is the stats property which will contain attribute names that are specific to the requested category + type.
curl "https://api.balldontlie.io/v1/season_averages/shooting?season=2024&season_type=regular&type=5ft_range&player_ids[]=246"
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 246,
"first_name": "Nikola",
"last_name": "Jokic",
"position": "C",
"height": "6-11",
"weight": "284",
"jersey_number": "15",
"college": "Mega Basket",
"country": "Serbia",
"draft_year": 2014,
"draft_round": 2,
"draft_number": 41
},
"season": 2024,
"season_type": "regular",
"stats": {
"40+_ft._fga": 0.4,
"40+_ft._fgm": 0,
"5-9_ft._fga": 5.1,
"5-9_ft._fgm": 2.9,
"10-14_ft._fga": 1.4,
"10-14_ft._fgm": 0.6,
"15-19_ft._fga": 0.8,
"15-19_ft._fgm": 0.4,
"20-24_ft._fga": 0.7,
"20-24_ft._fgm": 0.4,
"25-29_ft._fga": 3.5,
"25-29_ft._fgm": 1.7,
"30-34_ft._fga": 0.1,
"30-34_ft._fgm": 0,
"35-39_ft._fga": 0,
"35-39_ft._fgm": 0,
"40+_ft._fg_pct": 0.118,
"5-9_ft._fg_pct": 0.571,
"10-14_ft._fg_pct": 0.424,
"15-19_ft._fg_pct": 0.514,
"20-24_ft._fg_pct": 0.5,
"25-29_ft._fg_pct": 0.488,
"30-34_ft._fg_pct": 0,
"35-39_ft._fg_pct": 0,
"less_than_5_ft._fga": 7.7,
"less_than_5_ft._fgm": 5.3,
"less_than_5_ft._fg_pct": 0.684
}
}
],
"meta": {
"per_page": 25
}
}
HTTP Request
GET https://api.balldontlie.io/v1/season_averages/shooting?season=2024&season_type=regular&type=5ft_range&player_ids[]=246
Route Parameters
| Parameter | Required | Description |
|---|---|---|
| category | true | See table above for valid category options and their required type pairings |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| season_type | true | Available options: regular, playoffs, ist, playin |
| type | false | Required for all categories except hustle. See table above for valid type options per category. |
| season | true | Returns season averages for this season |
| player_ids | false | Returns season averages for these players. This should be an array: ?player_ids[]=1&player_ids[]=2 |
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Defaults to 25. Max is 100 |
Team Season Averages
Get Team Season Averages
There are many types of team season averages you can retrieve. You must specify a category in the route and an additional type as a query parameter (except for the hustle category which doesn't require a type parameter). For example: https://api.balldontlie.io/nba/v1/team_season_averages/general?season=2023&season_type=regular&type=base will return general team season averages for the 2023 regular season.
Here are the available pairing options between category and type:
| Category | Type |
|---|---|
| general | base |
| general | advanced |
| general | scoring |
| general | misc |
| general | opponent |
| general | defense |
| general | violations |
| clutch | base |
| clutch | advanced |
| clutch | misc |
| clutch | scoring |
| shooting | by_zone_base |
| shooting | by_zone_opponent |
| shooting | 5ft_range_base |
| shooting | 5ft_range_opponent |
| playtype | cut |
| playtype | handoff |
| playtype | isolation |
| playtype | offrebound |
| playtype | offscreen |
| playtype | postup |
| playtype | prballhandler |
| playtype | prrollman |
| playtype | spotup |
| playtype | transition |
| playtype | misc |
| tracking | painttouch |
| tracking | efficiency |
| tracking | speeddistance |
| tracking | defense |
| tracking | elbowtouch |
| tracking | posttouch |
| tracking | passing |
| tracking | drives |
| tracking | rebounding |
| tracking | catchshoot |
| tracking | pullupshot |
| tracking | possessions |
| hustle | (no type required) |
| shotdashboard | overall |
| shotdashboard | pullups |
| shotdashboard | catch_and_shoot |
| shotdashboard | less_than_10_ft |
Regardless of the category + type combination, all data is returned in the same shape. The only difference is the stats property which will contain attribute names that are specific to the requested category + type.
import requests
response = requests.get(
'https://api.balldontlie.io/nba/v1/team_season_averages/general',
headers={'Authorization': 'YOUR_API_KEY'},
params={
'season': 2024,
'season_type': 'regular',
'type': 'base',
'per_page': 3
}
)
data = response.json()
print(data)
fetch('https://api.balldontlie.io/nba/v1/team_season_averages/general?season=2024&season_type=regular&type=base&per_page=3', {
headers: {
'Authorization': 'YOUR_API_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
The above commands return JSON structured like this:
{
"data": [
{
"team": {
"id": 1,
"conference": "East",
"division": "Southeast",
"city": "Atlanta",
"name": "Hawks",
"full_name": "Atlanta Hawks",
"abbreviation": "ATL"
},
"season": 2024,
"season_type": "regular",
"stats": {
"l": 42,
"w": 40,
"gp": 82,
"pf": 19.1,
"ast": 29.6,
"blk": 5.1,
"fga": 91.8,
"fgm": 43.4,
"fta": 23.2,
"ftm": 18,
"min": 48.2,
"pfd": 19.1,
"pts": 118.2,
"reb": 44.5,
"stl": 9.7,
"tov": 15.5,
"blka": 4.9,
"dreb": 32.6,
"fg3a": 37.7,
"fg3m": 13.5,
"oreb": 11.9,
"w_pct": 0.488,
"fg_pct": 0.472,
"ft_pct": 0.775,
"fg3_pct": 0.358,
"plus_minus": -1.1
}
},
{
"team": {
"id": 2,
"conference": "East",
"division": "Atlantic",
"city": "Boston",
"name": "Celtics",
"full_name": "Boston Celtics",
"abbreviation": "BOS"
},
"season": 2024,
"season_type": "regular",
"stats": {
"l": 21,
"w": 61,
"gp": 82,
"pf": 15.9,
"ast": 26.1,
"blk": 5.5,
"fga": 90,
"fgm": 41.6,
"fta": 19.1,
"ftm": 15.3,
"min": 48.4,
"pfd": 17.5,
"pts": 116.3,
"reb": 45.3,
"stl": 7.2,
"tov": 11.9,
"blka": 3.6,
"dreb": 33.9,
"fg3a": 48.2,
"fg3m": 17.8,
"oreb": 11.4,
"w_pct": 0.744,
"fg_pct": 0.462,
"ft_pct": 0.799,
"fg3_pct": 0.368,
"plus_minus": 9.1
}
}
],
"meta": {
"next_cursor": 40855,
"per_page": 2
}
}
This endpoint retrieves team season averages for a specific category and type.
HTTP Request
GET https://api.balldontlie.io/nba/v1/team_season_averages/{category}
Route Parameters
| Parameter | Required | Description |
|---|---|---|
| category | true | Available options: general, clutch, shooting, playtype, tracking, hustle, shotdashboard |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| season_type | true | Available options: regular, playoffs, ist |
| type | false | Required for all categories except hustle. See table above for available options per category. |
| season | true | Returns team season averages for this season |
| team_ids | false | Returns team season averages for these teams. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Defaults to 25. Max is 100 |
Game Advanced Stats
Attributes (V1)
These response attributes are worth noting.
| Attribute | Type | Notes |
|---|---|---|
| pie | float | Player Impact Estimate (PIE) measures a player's overall statistical contribution against the total statistics in games they play in. PIE yields results which are comparable to other advanced statistics (e.g. PER) using a simple formula. |
| pace | float | The number of possessions per 48 minutes. |
| assist_percentage | float | The percentage of teammate field goals a player assisted on while they were on the floor |
| assist_ratio | float | Assist Ratio is the number of assists a player averages per 100 possessions used |
| assist_to_turnover | float | The number of assists compared to the number of turnovers they have committed |
| defensive_rating | float | The number of points per 100 possessions that the team allows while that individual player is on the court. |
| defensive_rebound_percentage | float | The percentage of available defensive rebounds a player obtains while on the floor |
| effective_field_goal_percentage | float | Measures field goal percentage adjusting for made 3-point field goals being 1.5 times more valuable than made 2-point field goals. |
| net_rating | float | The team's point differential per 100 possessions while the player is on court. |
| offensive_rating | float | Team points scored per 100 possessions while the player is on court |
| offensive_rebound_percentage | float | The percentage of available offensive rebounds a player obtains while on the floor |
| rebound_percentage | float | The percentage of available rebounds a player grabbed while on the floor |
| true_shooting_percentage | float | A shooting percentage that factors in the value of three-point field goals and free throws in addition to conventional two-point field goals |
| turnover_ratio | float | The number of turnovers a player averages per 100 possessions used |
| usage_percentage | float | The percentage of team plays used by a player when they are on the floor |
Get All Advanced Stats (V1)
curl "https://api.balldontlie.io/nba/v1/stats/advanced?seasons[]=2024"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const stats = await api.nba.getAdvancedStats({ seasons: [2024] });
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
stats = api.nba.advanced_stats.list(seasons=[2024])
The above command returns JSON structured like this:
{
"data": [
{
"id": 3296931,
"pie": 0.021,
"pace": 94.83,
"assist_percentage": 0.097,
"assist_ratio": 27.3,
"assist_to_turnover": 0,
"defensive_rating": 154.5,
"defensive_rebound_percentage": 0.156,
"effective_field_goal_percentage": 0.143,
"net_rating": -37.2,
"offensive_rating": 117.4,
"offensive_rebound_percentage": 0,
"rebound_percentage": 0.082,
"true_shooting_percentage": 0.254,
"turnover_ratio": 0,
"usage_percentage": 0.108,
"player": {
"id": 18,
"first_name": "OG",
"last_name": "Anunoby",
"position": "F",
"height": "6-7",
"weight": "240",
"jersey_number": "8",
"college": "Indiana",
"country": "United Kingdom",
"draft_year": 2017,
"draft_round": 1,
"draft_number": 23,
"team_id": 20
},
"team": {
"id": 20,
"conference": "East",
"division": "Atlantic",
"city": "New York",
"name": "Knicks",
"full_name": "New York Knicks",
"abbreviation": "NYK"
},
"game": {
"id": 15907438,
"date": "2024-10-22",
"season": 2024,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": false,
"postponed": false,
"home_team_score": 132,
"visitor_team_score": 109,
"home_team_id": 2,
"visitor_team_id": 20,
"ist_stage": null
}
},
...
],
"meta": {
"next_cursor": 3296931,
"per_page": 25
}
}
This endpoint retrieves all advanced stats.
HTTP Request
GET https://api.balldontlie.io/nba/v1/stats/advanced
Query Parameters
You can combine query parameters. For example: ?seasons[]=2018&seasons[]=2015&player_ids[]=1&player_ids[]=2&postseason=true will return advanced stats for player_ids 1 and 2 for the 2015-2016 and 2018-2019 postseason.
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The page number, used for pagination. |
| per_page | false | The number of results returned per call, used for pagination. Max 100. |
| player_ids | false | Returns stats for these player ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
| game_ids | false | Returns stat for these game ids. This should be an array: ?game_ids[]=1&game_ids[]=2 |
| dates | false | Returns stats that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-01-01&dates[]=2024-01-02 |
| seasons | false | Returns stats that occurred in these seasons. This should be an array: ?seasons[]=2022&seasons[]=2023 |
| posteason | false | Returns playoff stats when set to true. Returns regular season stats when set to false. Returns both when not specified |
| start_date | false | Returns stats that occurred on or after this date. Date should be formatted in YYYY-MM-DD |
| end_date | false | Returns stats that occurred on or before this date. Date should be formatted in YYYY-MM-DD |
Attributes (V2)
The v2 endpoint includes all v1 attributes plus many additional metrics organized by category:
Core Advanced Stats
| Attribute | Type | Notes |
|---|---|---|
| period | int | 0=full game, 1-4=quarters, 5-7=overtime periods |
| pie | float | Player Impact Estimate |
| pace | float | Possessions per 48 minutes |
| pace_per_40 | float | Possessions per 40 minutes |
| possessions | float | Total possessions |
| assist_percentage | float | Percentage of teammate FGs assisted |
| assist_ratio | float | Assists per 100 possessions |
| assist_to_turnover | float | Assist to turnover ratio |
| defensive_rating | float | Points allowed per 100 possessions |
| offensive_rating | float | Points scored per 100 possessions |
| net_rating | float | Point differential per 100 possessions |
| estimated_defensive_rating | float | Estimated defensive rating |
| estimated_offensive_rating | float | Estimated offensive rating |
| estimated_net_rating | float | Estimated net rating |
| estimated_pace | float | Estimated pace |
| estimated_usage_percentage | float | Estimated usage percentage |
| defensive_rebound_percentage | float | Percentage of defensive rebounds obtained |
| offensive_rebound_percentage | float | Percentage of offensive rebounds obtained |
| rebound_percentage | float | Total rebound percentage |
| effective_field_goal_percentage | float | eFG% (adjusts for 3PT value) |
| true_shooting_percentage | float | TS% (includes FT value) |
| turnover_ratio | float | Turnovers per 100 possessions |
| usage_percentage | float | Percentage of team plays used |
Miscellaneous Stats
| Attribute | Type | Notes |
|---|---|---|
| blocks_against | int | Shots blocked by opponents |
| fouls_drawn | int | Fouls drawn |
| points_fast_break | int | Fast break points |
| points_off_turnovers | int | Points off turnovers |
| points_paint | int | Points in the paint |
| points_second_chance | int | Second chance points |
| opp_points_fast_break | int | Opponent fast break points |
| opp_points_off_turnovers | int | Opponent points off turnovers |
| opp_points_paint | int | Opponent points in paint |
| opp_points_second_chance | int | Opponent second chance points |
Scoring Stats
| Attribute | Type | Notes |
|---|---|---|
| pct_assisted_2pt | float | % of 2PT FGs that were assisted |
| pct_assisted_3pt | float | % of 3PT FGs that were assisted |
| pct_assisted_fgm | float | % of all FGs that were assisted |
| pct_unassisted_2pt | float | % of 2PT FGs that were unassisted |
| pct_unassisted_3pt | float | % of 3PT FGs that were unassisted |
| pct_unassisted_fgm | float | % of all FGs that were unassisted |
| pct_fga_2pt | float | % of FGA that are 2PT |
| pct_fga_3pt | float | % of FGA that are 3PT |
| pct_pts_2pt | float | % of points from 2PT FGs |
| pct_pts_3pt | float | % of points from 3PT FGs |
| pct_pts_fast_break | float | % of points from fast breaks |
| pct_pts_free_throw | float | % of points from FTs |
| pct_pts_midrange_2pt | float | % of points from midrange 2PT |
| pct_pts_off_turnovers | float | % of points off turnovers |
| pct_pts_paint | float | % of points in the paint |
Four Factors Stats
| Attribute | Type | Notes |
|---|---|---|
| four_factors_efg_pct | float | Four factors eFG% |
| free_throw_attempt_rate | float | FTA per FGA |
| four_factors_oreb_pct | float | Four factors OREB% |
| team_turnover_pct | float | Team turnover percentage |
| opp_efg_pct | float | Opponent eFG% |
| opp_free_throw_attempt_rate | float | Opponent FTA per FGA |
| opp_oreb_pct | float | Opponent OREB% |
| opp_turnover_pct | float | Opponent turnover percentage |
Hustle Stats
| Attribute | Type | Notes |
|---|---|---|
| box_outs | int | Total box outs |
| box_out_player_rebounds | int | Box outs leading to player rebounds |
| box_out_player_team_rebounds | int | Box outs leading to team rebounds |
| defensive_box_outs | int | Defensive box outs |
| offensive_box_outs | int | Offensive box outs |
| charges_drawn | int | Charges drawn |
| contested_shots | int | Total contested shots |
| contested_shots_2pt | int | Contested 2PT shots |
| contested_shots_3pt | int | Contested 3PT shots |
| deflections | int | Deflections |
| loose_balls_recovered_def | int | Defensive loose balls recovered |
| loose_balls_recovered_off | int | Offensive loose balls recovered |
| loose_balls_recovered_total | int | Total loose balls recovered |
| screen_assists | int | Screen assists |
| screen_assist_points | int | Points from screen assists |
Defensive Stats
| Attribute | Type | Notes |
|---|---|---|
| matchup_minutes | string | Minutes guarding primary matchup |
| matchup_fg_pct | float | Opponent FG% when guarded |
| matchup_fga | int | Opponent FGA when guarded |
| matchup_fgm | int | Opponent FGM when guarded |
| matchup_3pt_pct | float | Opponent 3PT% when guarded |
| matchup_3pa | int | Opponent 3PA when guarded |
| matchup_3pm | int | Opponent 3PM when guarded |
| matchup_assists | int | Opponent assists when guarded |
| matchup_turnovers | int | Opponent turnovers when guarded |
| partial_possessions | float | Partial possessions defended |
| matchup_player_points | int | Points allowed to matchup |
| switches_on | int | Switches onto player |
Tracking Stats
| Attribute | Type | Notes |
|---|---|---|
| speed | float | Average speed (mph) |
| distance | float | Distance traveled (miles) |
| touches | int | Total touches |
| passes | int | Total passes |
| secondary_assists | int | Secondary assists |
| free_throw_assists | int | Assists leading to FTs |
| contested_fga | int | Contested FGA |
| contested_fgm | int | Contested FGM |
| contested_fg_pct | float | Contested FG% |
| uncontested_fga | int | Uncontested FGA |
| uncontested_fgm | int | Uncontested FGM |
| uncontested_fg_pct | float | Uncontested FG% |
| defended_at_rim_fga | int | FGA defended at rim |
| defended_at_rim_fgm | int | FGM defended at rim |
| defended_at_rim_fg_pct | float | FG% defended at rim |
| rebound_chances_def | int | Defensive rebound chances |
| rebound_chances_off | int | Offensive rebound chances |
| rebound_chances_total | int | Total rebound chances |
Usage Stats
| Attribute | Type | Notes |
|---|---|---|
| pct_blocks | float | % of team blocks |
| pct_blocks_allowed | float | % of team blocks allowed |
| pct_fga | float | % of team FGA |
| pct_fgm | float | % of team FGM |
| pct_fta | float | % of team FTA |
| pct_ftm | float | % of team FTM |
| pct_personal_fouls | float | % of team personal fouls |
| pct_personal_fouls_drawn | float | % of team fouls drawn |
| pct_points | float | % of team points |
| pct_rebounds_def | float | % of team defensive rebounds |
| pct_rebounds_off | float | % of team offensive rebounds |
| pct_rebounds_total | float | % of team total rebounds |
| pct_steals | float | % of team steals |
| pct_3pa | float | % of team 3PA |
| pct_3pm | float | % of team 3PM |
| pct_turnovers | float | % of team turnovers |
Get All Advanced Stats (V2)
curl "https://api.balldontlie.io/nba/v2/stats/advanced?seasons[]=2025" \
-H "Authorization: YOUR_API_KEY"
const response = await fetch(
"https://api.balldontlie.io/nba/v2/stats/advanced?seasons[]=2025",
{ headers: { "Authorization": "YOUR_API_KEY" } }
);
const data = await response.json();
import requests
response = requests.get(
"https://api.balldontlie.io/nba/v2/stats/advanced",
headers={"Authorization": "YOUR_API_KEY"},
params={"seasons[]": 2025}
)
data = response.json()
The above command returns JSON structured like this:
{
"data": [
{
"id": 5,
"period": 0,
"pie": 0.182,
"pace": 93.02,
"pace_per_40": 77.52,
"possessions": 90,
"assist_percentage": 0.208,
"assist_ratio": 12.2,
"assist_to_turnover": 1.67,
"defensive_rating": 104.3,
"offensive_rating": 111.1,
"net_rating": 6.8,
"estimated_defensive_rating": 104.3,
"estimated_offensive_rating": 111.1,
"estimated_net_rating": 6.8,
"estimated_pace": 93.02,
"estimated_usage_percentage": 0.34,
"defensive_rebound_percentage": 0.109,
"offensive_rebound_percentage": 0,
"rebound_percentage": 0.051,
"effective_field_goal_percentage": 0.481,
"true_shooting_percentage": 0.544,
"turnover_ratio": 7.3,
"usage_percentage": 0.34,
"blocks_against": 2,
"fouls_drawn": 10,
"points_fast_break": 0,
"points_off_turnovers": 6,
"points_paint": 14,
"points_second_chance": 0,
"opp_points_fast_break": 2,
"opp_points_off_turnovers": 6,
"opp_points_paint": 44,
"opp_points_second_chance": 19,
"pct_assisted_2pt": 0.273,
"pct_assisted_3pt": 0,
"pct_assisted_fgm": 0.25,
"pct_fga_2pt": 0.654,
"pct_fga_3pt": 0.346,
"pct_pts_2pt": 0.629,
"pct_pts_3pt": 0.086,
"pct_pts_fast_break": 0,
"pct_pts_free_throw": 0.286,
"pct_pts_midrange_2pt": 0.229,
"pct_pts_off_turnovers": 0.171,
"pct_pts_paint": 0.4,
"pct_unassisted_2pt": 0.727,
"pct_unassisted_3pt": 1,
"pct_unassisted_fgm": 0.75,
"four_factors_efg_pct": 0.483,
"free_throw_attempt_rate": 0.256,
"four_factors_oreb_pct": 0,
"team_turnover_pct": 0.095,
"opp_efg_pct": 0.475,
"opp_free_throw_attempt_rate": 0.329,
"opp_oreb_pct": 0.4,
"opp_turnover_pct": 0.207,
"box_outs": 1,
"box_out_player_rebounds": 1,
"box_out_player_team_rebounds": 1,
"defensive_box_outs": 1,
"offensive_box_outs": 0,
"charges_drawn": 0,
"contested_shots": 12,
"contested_shots_2pt": 8,
"contested_shots_3pt": 4,
"deflections": 5,
"loose_balls_recovered_def": 0,
"loose_balls_recovered_off": 0,
"loose_balls_recovered_total": 0,
"screen_assists": 1,
"screen_assist_points": 3,
"matchup_minutes": "20:58",
"matchup_fg_pct": 0.333,
"matchup_fga": 15,
"matchup_fgm": 5,
"matchup_3pt_pct": 0.286,
"matchup_3pa": 7,
"matchup_3pm": 2,
"matchup_assists": 1,
"matchup_turnovers": 5,
"partial_possessions": 88.1,
"matchup_player_points": 14,
"switches_on": 0,
"speed": 3.75,
"distance": 2.89,
"touches": 104,
"passes": 63,
"secondary_assists": 0,
"free_throw_assists": 0,
"contested_fga": 4,
"contested_fgm": 2,
"contested_fg_pct": 0.5,
"uncontested_fga": 22,
"uncontested_fgm": 10,
"uncontested_fg_pct": 0.455,
"defended_at_rim_fga": 5,
"defended_at_rim_fgm": 3,
"defended_at_rim_fg_pct": 0.6,
"rebound_chances_def": 6,
"rebound_chances_off": 4,
"rebound_chances_total": 9,
"pct_blocks": 0.667,
"pct_blocks_allowed": 0.5,
"pct_fga": 0.302,
"pct_fgm": 0.333,
"pct_fta": 0.636,
"pct_ftm": 0.588,
"pct_personal_fouls": 0.083,
"pct_personal_fouls_drawn": 0.476,
"pct_points": 0.35,
"pct_rebounds_def": 0.238,
"pct_rebounds_off": 0,
"pct_rebounds_total": 0.161,
"pct_steals": 0.2,
"pct_3pa": 0.196,
"pct_3pm": 0.091,
"pct_turnovers": 0.333,
"player": {
"id": 175,
"first_name": "Shai",
"last_name": "Gilgeous-Alexander",
"position": "G",
"height": "6-6",
"weight": "195",
"jersey_number": "2",
"college": "Kentucky",
"country": "Canada",
"draft_year": 2018,
"draft_round": 1,
"draft_number": 11,
"team_id": 21
},
"team": {
"id": 21,
"conference": "West",
"division": "Northwest",
"city": "Oklahoma City",
"name": "Thunder",
"full_name": "Oklahoma City Thunder",
"abbreviation": "OKC"
},
"game": {
"id": 18446819,
"date": "2025-10-21",
"season": 2025,
"status": "Final",
"period": 6,
"time": "Final",
"postseason": false,
"postponed": false,
"home_team_score": 125,
"visitor_team_score": 124,
"datetime": "2025-10-21T23:30:00.000Z",
"home_q1": 27,
"home_q2": 24,
"home_q3": 24,
"home_q4": 29,
"home_ot1": 11,
"home_ot2": 10,
"home_ot3": null,
"home_timeouts_remaining": 1,
"home_in_bonus": true,
"visitor_q1": 30,
"visitor_q2": 27,
"visitor_q3": 22,
"visitor_q4": 25,
"visitor_ot1": 11,
"visitor_ot2": 9,
"visitor_ot3": null,
"visitor_timeouts_remaining": 0,
"visitor_in_bonus": false,
"ist_stage": null,
"home_team_id": 21,
"visitor_team_id": 11
}
},
...
],
"meta": {
"next_cursor": 5,
"per_page": 25
}
}
This endpoint retrieves comprehensive advanced stats including hustle stats, tracking data, and per-period breakdowns.
HTTP Request
GET https://api.balldontlie.io/nba/v2/stats/advanced
Query Parameters
You can combine query parameters. For example: ?seasons[]=2025&player_ids[]=175&period=0 will return full-game advanced stats for Shai Gilgeous-Alexander for the 2025-2026 season.
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination. |
| per_page | false | The number of results returned per call, used for pagination. Max 100. |
| player_ids | false | Returns stats for these player ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
| game_ids | false | Returns stats for these game ids. This should be an array: ?game_ids[]=1&game_ids[]=2 |
| dates | false | Returns stats that match these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2024-01-01&dates[]=2024-01-02 |
| seasons | false | Returns stats that occurred in these seasons. This should be an array: ?seasons[]=2024&seasons[]=2025 |
| postseason | false | Returns playoff stats when set to true. Returns regular season stats when set to false. Returns both when not specified |
| start_date | false | Returns stats that occurred on or after this date. Date should be formatted in YYYY-MM-DD |
| end_date | false | Returns stats that occurred on or before this date. Date should be formatted in YYYY-MM-DD |
| period | false | Filter by period: 0=full game, 1-4=quarters, 5-7=overtime periods. Note: Hustle, defensive, and tracking stats are only available for full game (period=0) |
Box Scores
Get Live Box Scores
curl "https://api.balldontlie.io/v1/box_scores/live"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const boxScores = await api.nba.getLiveBoxScores();
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
box_scores = api.nba.box_scores.get_live()
The above command returns JSON structured like this:
{
"data": [
{
"date": "2024-02-07",
"season": 2023,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": false,
"postponed": false,
"home_team_score": 117,
"visitor_team_score": 123,
"home_team": {
"id": 4,
"conference": "East",
"division": "Southeast",
"city": "Charlotte",
"name": "Hornets",
"full_name": "Charlotte Hornets",
"abbreviation": "CHA",
"players": [
{
"min": "23",
"fgm": 1,
"fga": 2,
"fg_pct": 0.5,
"fg3m": 0,
"fg3a": 1,
"fg3_pct": 0,
"ftm": 1,
"fta": 2,
"ft_pct": 0.5,
"oreb": 0,
"dreb": 3,
"reb": 3,
"ast": 3,
"stl": 0,
"blk": 1,
"turnover": 1,
"pf": 1,
"pts": 3,
"plus_minus": 5,
"player": {
"id": 56677866,
"first_name": "Leaky",
"last_name": "Black",
"position": "F",
"height": "6-6",
"weight": "209",
"jersey_number": "12",
"college": "North Carolina",
"country": "USA",
"draft_year": null,
"draft_round": null,
"draft_number": null
}
},
...
]
},
"visitor_team": {
"id": 28,
"conference": "East",
"division": "Atlantic",
"city": "Toronto",
"name": "Raptors",
"full_name": "Toronto Raptors",
"abbreviation": "TOR",
"players": [
{
"min": "15",
"fgm": 2,
"fga": 3,
"fg_pct": 0.6666667,
"fg3m": 0,
"fg3a": 0,
"fg3_pct": 0,
"ftm": 0,
"fta": 0,
"ft_pct": 0,
"oreb": 3,
"dreb": 5,
"reb": 8,
"ast": 2,
"stl": 1,
"blk": 0,
"turnover": 1,
"pf": 2,
"pts": 4,
"plus_minus": -3,
"player": {
"id": 489,
"first_name": "Thaddeus",
"last_name": "Young",
"position": "F",
"height": "6-8",
"weight": "225",
"jersey_number": "21",
"college": "Georgia Tech",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 12
}
},
...
]
}
},
...
]
}
This endpoint retrieves all live box scores.
HTTP Request
GET https://api.balldontlie.io/v1/box_scores/live
Get Box Scores
curl "https://api.balldontlie.io/v1/box_scores"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const scores = await api.nba.getBoxScores("2024-02-07");
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
scores = api.nba.box_scores.get_by_date(date="2024-02-07")
The above command returns JSON structured like this:
{
"data": [
{
"date": "2024-02-07",
"season": 2023,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": false,
"postponed": false,
"home_team_score": 117,
"visitor_team_score": 123,
"home_team": {
"id": 4,
"conference": "East",
"division": "Southeast",
"city": "Charlotte",
"name": "Hornets",
"full_name": "Charlotte Hornets",
"abbreviation": "CHA",
"players": [
{
"min": "23",
"fgm": 1,
"fga": 2,
"fg_pct": 0.5,
"fg3m": 0,
"fg3a": 1,
"fg3_pct": 0,
"ftm": 1,
"fta": 2,
"ft_pct": 0.5,
"oreb": 0,
"dreb": 3,
"reb": 3,
"ast": 3,
"stl": 0,
"blk": 1,
"turnover": 1,
"pf": 1,
"pts": 3,
"plus_minus": 5,
"player": {
"id": 56677866,
"first_name": "Leaky",
"last_name": "Black",
"position": "F",
"height": "6-6",
"weight": "209",
"jersey_number": "12",
"college": "North Carolina",
"country": "USA",
"draft_year": null,
"draft_round": null,
"draft_number": null
}
},
...
]
},
"visitor_team": {
"id": 28,
"conference": "East",
"division": "Atlantic",
"city": "Toronto",
"name": "Raptors",
"full_name": "Toronto Raptors",
"abbreviation": "TOR",
"players": [
{
"min": "15",
"fgm": 2,
"fga": 3,
"fg_pct": 0.6666667,
"fg3m": 0,
"fg3a": 0,
"fg3_pct": 0,
"ftm": 0,
"fta": 0,
"ft_pct": 0,
"oreb": 3,
"dreb": 5,
"reb": 8,
"ast": 2,
"stl": 1,
"blk": 0,
"turnover": 1,
"pf": 2,
"pts": 4,
"plus_minus": -3,
"player": {
"id": 489,
"first_name": "Thaddeus",
"last_name": "Young",
"position": "F",
"height": "6-8",
"weight": "225",
"jersey_number": "21",
"college": "Georgia Tech",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 12
}
},
...
]
}
},
...
]
}
This endpoint retrieves all box scores.
HTTP Request
GET https://api.balldontlie.io/v1/box_scores
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| date | true | Returns all box scores for this date. The date should be formatted in YYYY-MM-DD |
Lineups
Get Game Lineups
curl "https://api.balldontlie.io/v1/lineups?game_ids[]=18447170" \
-H "Authorization: YOUR_API_KEY"
const axios = require("axios");
const response = await axios.get("https://api.balldontlie.io/v1/lineups", {
params: {
"game_ids[]": 18447170,
},
headers: {
Authorization: "YOUR_API_KEY",
},
});
console.log(response.data);
import requests
response = requests.get(
'https://api.balldontlie.io/v1/lineups',
params={'game_ids[]': 18447170},
headers={'Authorization': 'YOUR_API_KEY'}
)
print(response.json())
The above command returns JSON structured like this:
{
"data": [
{
"id": 9832,
"game_id": 18447170,
"starter": true,
"position": "F",
"player": {
"id": 79,
"first_name": "Jimmy",
"last_name": "Butler",
"position": "G-F",
"height": "6-6",
"weight": "230",
"jersey_number": "10",
"college": "Marquette",
"country": "USA",
"draft_year": 2011,
"draft_round": 1,
"draft_number": 30,
"team_id": 10
},
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
},
{
"id": 9833,
"game_id": 18447170,
"starter": true,
"position": "C",
"player": {
"id": 1028047928,
"first_name": "Quinten",
"last_name": "Post",
"position": "C",
"height": "7-0",
"weight": "238",
"jersey_number": "21",
"college": "Boston College",
"country": "Netherlands",
"draft_year": 2024,
"draft_round": 2,
"draft_number": 52,
"team_id": 10
},
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
},
{
"id": 9834,
"game_id": 18447170,
"starter": true,
"position": "G",
"player": {
"id": 210,
"first_name": "Buddy",
"last_name": "Hield",
"position": "G",
"height": "6-4",
"weight": "220",
"jersey_number": "7",
"college": "Oklahoma",
"country": "Bahamas",
"draft_year": 2016,
"draft_round": 1,
"draft_number": 6,
"team_id": 10
},
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
},
{
"id": 9835,
"game_id": 18447170,
"starter": true,
"position": "G",
"player": {
"id": 795959473,
"first_name": "Pat",
"last_name": "Spencer",
"position": "G",
"height": "6-2",
"weight": "205",
"jersey_number": "61",
"college": "Northwestern",
"country": "USA",
"draft_year": null,
"draft_round": null,
"draft_number": null,
"team_id": 10
},
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
},
{
"id": 9836,
"game_id": 18447170,
"starter": true,
"position": "G",
"player": {
"id": 1057395872,
"first_name": "Will",
"last_name": "Richard",
"position": "G",
"height": "6-3",
"weight": "206",
"jersey_number": "3",
"college": "Florida",
"country": "USA",
"draft_year": 2025,
"draft_round": 2,
"draft_number": 56,
"team_id": 10
},
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
},
{
"id": 9837,
"game_id": 18447170,
"starter": false,
"position": "F",
"player": {
"id": 56677799,
"first_name": "Trayce",
"last_name": "Jackson-Davis",
"position": "F",
"height": "6-9",
"weight": "245",
"jersey_number": "32",
"college": "Indiana",
"country": "USA",
"draft_year": 2023,
"draft_round": 2,
"draft_number": 57,
"team_id": 10
}
},
...
],
"meta": {
"per_page": 25
}
}
This endpoint retrieves starting lineups and bench players for NBA games.
HTTP Request
GET https://api.balldontlie.io/v1/lineups
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| game_ids | true | Returns lineups for these game ids. This should be an array: ?game_ids[]=1&game_ids[]=2 |
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
Plays
Get Play-by-Play Data
curl "https://api.balldontlie.io/v1/plays?game_id=18446820" \
-H "Authorization: YOUR_API_KEY"
const axios = require("axios");
const response = await axios.get("https://api.balldontlie.io/v1/plays", {
params: {
game_id: 18446820,
},
headers: {
Authorization: "YOUR_API_KEY",
},
});
console.log(response.data);
import requests
response = requests.get(
'https://api.balldontlie.io/v1/plays',
params={'game_id': 18446820},
headers={'Authorization': 'YOUR_API_KEY'}
)
print(response.json())
The above command returns JSON structured like this:
{
"data": [
{
"game_id": 18446820,
"order": 1,
"type": "Jumpball",
"text": "Draymond Green vs. Deandre Ayton (Gabe Vincent gains possession)",
"home_score": 0,
"away_score": 0,
"period": 1,
"period_display": "1st Quarter",
"clock": "12:00",
"scoring_play": false,
"shooting_play": false,
"score_value": null,
"team": {
"id": 14,
"conference": "West",
"division": "Pacific",
"city": "Los Angeles",
"name": "Lakers",
"full_name": "Los Angeles Lakers",
"abbreviation": "LAL"
},
"coordinate_x": null,
"coordinate_y": null,
"wallclock": "2025-10-22T02:17:43.000Z"
},
{
"game_id": 18446820,
"order": 2,
"type": "Fade Away Jump Shot",
"text": "Luka Doncic makes 13-foot two point shot",
"home_score": 0,
"away_score": 2,
"period": 1,
"period_display": "1st Quarter",
"clock": "11:39",
"scoring_play": true,
"shooting_play": true,
"score_value": 2,
"team": {
"id": 14,
"conference": "West",
"division": "Pacific",
"city": "Los Angeles",
"name": "Lakers",
"full_name": "Los Angeles Lakers",
"abbreviation": "LAL"
},
"coordinate_x": 19,
"coordinate_y": 13,
"wallclock": "2025-10-22T02:18:01.000Z"
},
...
]
}
This endpoint retrieves play-by-play data for a specific NBA game. Plays are returned in chronological order.
HTTP Request
GET https://api.balldontlie.io/v1/plays
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| game_id | true | The ID of the game to get plays for |
Active Players
Get All Active Players
curl "https://api.balldontlie.io/v1/players/active" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const players = await api.nba.getActivePlayers();
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
players = api.nba.players.list_active()
The above command returns JSON structured like this:
{
"data": [
{
"id": 115,
"first_name": "Stephen",
"last_name": "Curry",
"position": "G",
"height": "6-2",
"weight": "185",
"jersey_number": "30",
"college": "Davidson",
"country": "USA",
"draft_year": 2009,
"draft_round": 1,
"draft_number": 7,
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
}
},
...
],
"meta": {
"next_cursor": 25,
"per_page": 25
}
}
This endpoint retrieves all active players.
HTTP Request
GET https://api.balldontlie.io/v1/players/active
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| search | false | Returns players whose first or last name matches this value. For example, ?search=davis will return players that have 'davis' in their first or last name. |
| first_name | false | Returns players whose first name matches this value. For example, ?search=anthony will return players that have 'anthony' in their first name. |
| last_name | false | Returns players whose last name matches this value. For example, ?search=davis will return players that have 'davis' in their last name. |
| team_ids | false | Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| player_ids | false | Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
Player Injuries
Get All Player Injuries
curl "https://api.balldontlie.io/v1/player_injuries" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const injuries = await api.nba.getPlayerInjuries();
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
injuries = api.nba.injuries.list()
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 56677838,
"first_name": "Kobe",
"last_name": "Bufkin",
"position": "G",
"height": "6-4",
"weight": "195",
"jersey_number": "4",
"college": "Michigan",
"country": "USA",
"draft_year": 2023,
"draft_round": 1,
"draft_number": 15,
"team_id": 1
},
"return_date": "Nov 17",
"description": "Nov 16: Bufkin (shoulder) is listed as doubtful for Sunday's game against the Trail Blazers.",
"status": "Out"
}
],
"meta": { "next_cursor": 62089, "per_page": 25 }
}
This endpoint retrieves all player injuries.
HTTP Request
GET https://api.balldontlie.io/v1/player_injuries
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| team_ids | false | Returns players that belong to these team ids. This should be an array: ?team_ids[]=1&team_ids[]=2 |
| player_ids | false | Returns players that match these ids. This should be an array: ?player_ids[]=1&player_ids[]=2 |
Team Standings
Get Team Standings
curl "https://api.balldontlie.io/v1/standings?season=2024" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const standings = await api.nba.getStandings({ season: 2024 });
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
standings = api.nba.standings.get(season=2024)
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 6,
"conference": "East",
"division": "Central",
"city": "Cleveland",
"name": "Cavaliers",
"full_name": "Cleveland Cavaliers",
"abbreviation": "CLE"
},
"conference_record": "41-11",
"conference_rank": 1,
"division_record": "12-4",
"division_rank": 1,
"wins": 64,
"losses": 18,
"home_record": "34-7",
"road_record": "30-11",
"season": 2024
},
{
"team": {
"id": 21,
"conference": "West",
"division": "Northwest",
"city": "Oklahoma City",
"name": "Thunder",
"full_name": "Oklahoma City Thunder",
"abbreviation": "OKC"
},
"conference_record": "39-13",
"conference_rank": 1,
"division_record": "12-4",
"division_rank": 1,
"wins": 68,
"losses": 14,
"home_record": "35-6",
"road_record": "32-8",
"season": 2024
},
...
]
}
This endpoint retrieves regular season team standings.
HTTP Request
GET https://api.balldontlie.io/v1/standings
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| season | true | Returns regular season standings for the specified season. For example, ?season=2023 will return the team standings for the 2023-24 season. |
Leaders
Get Leaders
curl "https://api.balldontlie.io/v1/leaders?season=2023&stat_type=pts" \
-H "Authorization: YOUR_API_KEY"
import { BalldontlieAPI } from "@balldontlie/sdk";
const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const leaders = await api.nba.getLeaders({
stat_type: "pts",
season: 2023,
});
from balldontlie import BalldontlieAPI
api = BalldontlieAPI(api_key="YOUR_API_KEY")
leaders = api.nba.leaders.get(stat_type="pts", season=2023)
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 19,
"first_name": "Stephen",
"last_name": "Curry",
"position": "G",
"height": "6-2",
"weight": "185",
"jersey_number": "30",
"college": "Davidson",
"country": "USA",
"draft_year": 2009,
"draft_round": 1,
"draft_number": 7,
"team_id": 10,
},
"value": 32.3,
"stat_type": "pts",
"rank": 1,
"season": 2023,
"games_played": 34
},
...
]
}
This endpoint retrieves per game leaders for specific stat categories.
HTTP Request
GET https://api.balldontlie.io/v1/leaders
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| stat_type | true | Returns leaders for the specified stat_type. Valid stat_types are ast, blk, dreb, eff, fg3a, fg3m, fg3_pct, fga, fgm, fg_pct, fta, ftm, ft_pct, min, oreb, pts, reb, stl, tov. For example, ?stat_type=pts will return the current points per game leaders |
| season | true | Returns leaders for the specified season |
| season_type | false | Returns leaders for the specified season type. Valid values are regular (default) and playoffs |
Betting Odds
Get Betting Odds
curl "https://api.balldontlie.io/v2/odds?dates[]=2025-01-15" \
-H "Authorization: YOUR_API_KEY"
const axios = require("axios");
const response = await axios.get("https://api.balldontlie.io/v2/odds", {
params: {
"dates[]": "2025-01-15",
},
headers: {
Authorization: "YOUR_API_KEY",
},
});
console.log(response.data);
import requests
response = requests.get(
'https://api.balldontlie.io/v2/odds',
params={'dates[]': '2025-01-15'},
headers={'Authorization': 'YOUR_API_KEY'}
)
print(response.json())
The above command returns JSON structured like this:
{
"data": [
{
"id": 1105,
"game_id": 18446819,
"vendor": "draftkings",
"spread_home_value": "-7.5",
"spread_home_odds": -120,
"spread_away_value": "7.5",
"spread_away_odds": -110,
"moneyline_home_odds": -330,
"moneyline_away_odds": 240,
"total_value": "228.5",
"total_over_odds": -115,
"total_under_odds": -115,
"updated_at": "2025-10-21T23:46:11.875Z"
},
{
"id": 1106,
"game_id": 18446820,
"vendor": "draftkings",
"spread_home_value": "2.5",
"spread_home_odds": -112,
"spread_away_value": "-2.5",
"spread_away_odds": -108,
"moneyline_home_odds": 120,
"moneyline_away_odds": -142,
"total_value": "227.5",
"total_over_odds": -108,
"total_under_odds": -112,
"updated_at": "2025-10-21T23:46:11.875Z"
},
{
"id": 1051,
"game_id": 18446819,
"vendor": "caesars",
"spread_home_value": "-7.5",
"spread_home_odds": -105,
"spread_away_value": "7.5",
"spread_away_odds": -125,
"moneyline_home_odds": -320,
"moneyline_away_odds": 240,
"total_value": "228.5",
"total_over_odds": -115,
"total_under_odds": -115,
"updated_at": "2025-10-21T23:45:55.739Z"
},
{
"id": 1052,
"game_id": 18446820,
"vendor": "caesars",
"spread_home_value": "2.5",
"spread_home_odds": -105,
"spread_away_value": "-2.5",
"spread_away_odds": -115,
"moneyline_home_odds": 122,
"moneyline_away_odds": -145,
"total_value": "227",
"total_over_odds": -105,
"total_under_odds": -115,
"updated_at": "2025-10-21T23:45:55.739Z"
},
{
"id": 1414,
"game_id": 18446820,
"vendor": "fanduel",
"spread_home_value": "2.5",
"spread_home_odds": -108,
"spread_away_value": "-2.5",
"spread_away_odds": -112,
"moneyline_home_odds": 120,
"moneyline_away_odds": -142,
"total_value": "226.5",
"total_over_odds": -112,
"total_under_odds": -108,
"updated_at": "2025-10-21T23:45:41.957Z"
},
{
"id": 153881,
"game_id": 18446819,
"vendor": "bet365",
"spread_home_value": "-6.5",
"spread_home_odds": -110,
"spread_away_value": "6.5",
"spread_away_odds": -110,
"moneyline_home_odds": -260,
"moneyline_away_odds": 210,
"total_value": "227.5",
"total_over_odds": -110,
"total_under_odds": -110,
"updated_at": "2025-10-21T23:45:39.624Z"
},
{
"id": 157016,
"game_id": 18446820,
"vendor": "bet365",
"spread_home_value": "2.5",
"spread_home_odds": -110,
"spread_away_value": "-2.5",
"spread_away_odds": -110,
"moneyline_home_odds": 120,
"moneyline_away_odds": -140,
"total_value": "226.5",
"total_over_odds": -110,
"total_under_odds": -110,
"updated_at": "2025-10-21T23:45:39.624Z"
},
{
"id": 1067,
"game_id": 18446819,
"vendor": "betmgm",
"spread_home_value": "-6.5",
"spread_home_odds": -125,
"spread_away_value": "6.5",
"spread_away_odds": -105,
"moneyline_home_odds": -285,
"moneyline_away_odds": 210,
"total_value": "227.5",
"total_over_odds": -110,
"total_under_odds": -115,
"updated_at": "2025-10-21T23:45:18.356Z"
},
{
"id": 1068,
"game_id": 18446820,
"vendor": "betmgm",
"spread_home_value": "2.5",
"spread_home_odds": -115,
"spread_away_value": "-2.5",
"spread_away_odds": -105,
"moneyline_home_odds": 115,
"moneyline_away_odds": -140,
"total_value": "227.5",
"total_over_odds": -110,
"total_under_odds": -110,
"updated_at": "2025-10-21T23:45:18.356Z"
},
{
"id": 1413,
"game_id": 18446819,
"vendor": "fanduel",
"spread_home_value": "-6.5",
"spread_home_odds": -108,
"spread_away_value": "6.5",
"spread_away_odds": -112,
"moneyline_home_odds": -250,
"moneyline_away_odds": 205,
"total_value": "225.5",
"total_over_odds": -108,
"total_under_odds": -112,
"updated_at": "2025-10-21T23:42:41.908Z"
}
],
"meta": {
"per_page": 25
}
}
This endpoint retrieves betting odds for NBA games. At least one of dates or game_ids must be provided.
Available Vendors:
- betmgm
- fanduel
- draftkings
- bet365
- caesars
- ballybet
- betway
- betparx
- betrivers
- rebet
- polymarket
- kalshi
HTTP Request
GET https://api.balldontlie.io/v2/odds
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Default to 25. Max is 100 |
| dates | false | Returns odds for games on these dates. Dates should be formatted in YYYY-MM-DD. This should be an array: ?dates[]=2025-01-15&dates[]=2025-01-16 |
| game_ids | false | Returns odds for these game ids. This should be an array: ?game_ids[]=15907925&game_ids[]=15907926 |
Player Props
Get Player Props
curl "https://api.balldontlie.io/v2/odds/player_props?game_id=18447073" \
-H "Authorization: YOUR_API_KEY"
const axios = require("axios");
const response = await axios.get(
"https://api.balldontlie.io/v2/odds/player_props",
{
params: {
game_id: 18447073,
},
headers: {
Authorization: "YOUR_API_KEY",
},
}
);
console.log(response.data);
import requests
response = requests.get(
'https://api.balldontlie.io/v2/odds/player_props',
params={'game_id': 18447073},
headers={'Authorization': 'YOUR_API_KEY'}
)
print(response.json())
The above command returns JSON structured like this:
{
"data": [
{
"id": 15777190,
"game_id": 18447073,
"player_id": 246,
"vendor": "draftkings",
"prop_type": "points",
"line_value": "18",
"market": {
"type": "milestone",
"odds": -1960
},
"updated_at": "2025-11-24T23:46:46.653Z"
},
{
"id": 15777199,
"game_id": 18447073,
"player_id": 246,
"vendor": "draftkings",
"prop_type": "points",
"line_value": "30.5",
"market": {
"type": "over_under",
"over_odds": -111,
"under_odds": -115
},
"updated_at": "2025-11-24T23:46:46.653Z"
},
{
"id": 15777202,
"game_id": 18447073,
"player_id": 246,
"vendor": "draftkings",
"prop_type": "points_first3min",
"line_value": "3",
"market": {
"type": "milestone",
"odds": 139
},
"updated_at": "2025-11-24T23:46:46.653Z"
}
],
"meta": {
"per_page": 3
}
}
This endpoint retrieves live player prop betting data for a specific NBA game. Player props include predictions for individual player performance like points, rebounds, assists, and more.
The API supports two market types:
- over_under: Traditional over/under markets where users can bet on whether a player will go over or under a specific line value
- milestone: Milestone markets where users bet on whether a player will reach a specific achievement (e.g., scoring exactly 30+ points)
Available Vendors:
- draftkings
- betway
- betrivers
- ballybet
- betparx
- caesars
- fanduel
- rebet
HTTP Request
GET https://api.balldontlie.io/v2/odds/player_props
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| game_id | true | The game ID to retrieve player props for |
| player_id | false | Filter props for a specific player |
| prop_type | false | Filter by prop type. See supported prop types below. |
| vendors | false | Filter by specific vendors. This should be an array: ?vendors[]=draftkings&vendors[]=betway |
Supported Prop Types
The following prop_type values are supported:
| Prop Type | Description |
|---|---|
| assists | Total assists |
| assists_1q | Assists in first quarter |
| assists_first3min | Assists in first 3 minutes |
| blocks | Total blocks |
| double_double | Double-double achievement |
| points | Total points |
| points_1q | Points in first quarter |
| points_assists | Points + assists |
| points_first3min | Points in first 3 minutes |
| points_rebounds | Points + rebounds |
| points_rebounds_assists | Points + rebounds + assists |
| rebounds | Total rebounds |
| rebounds_1q | Rebounds in first quarter |
| rebounds_assists | Rebounds + assists |
| rebounds_first3min | Rebounds in first 3 minutes |
| steals | Total steals |
| threes | Three-pointers made |
| triple_double | Triple-double achievement |
Response Attributes
| Attribute | Type | Description |
|---|---|---|
| id | integer | Unique identifier for the prop |
| game_id | integer | The game this prop belongs to |
| player_id | integer | The player this prop is for |
| vendor | string | The sportsbook offering this prop |
| prop_type | string | The type of prop (e.g., "points", "rebounds", "assists", "threes") |
| line_value | string | The line value for the prop |
| market | object | Market information - either over_under or milestone type |
| updated_at | string | ISO 8601 timestamp of when this prop was last updated |
Contracts
Get Team Contracts
curl "https://api.balldontlie.io/v1/contracts/teams?team_id=5&season=2025" \
-H "Authorization: YOUR_API_KEY"
const axios = require("axios");
const response = await axios.get(
"https://api.balldontlie.io/v1/contracts/teams",
{
params: {
team_id: 5,
season: 2025,
},
headers: {
Authorization: "YOUR_API_KEY",
},
}
);
console.log(response.data);
import requests
response = requests.get(
'https://api.balldontlie.io/v1/contracts/teams',
params={'team_id': 5, 'season': 2025},
headers={'Authorization': 'YOUR_API_KEY'}
)
print(response.json())
The above command returns JSON structured like this:
{
"data": [
{
"id": 6251,
"player_id": 17896065,
"season": 2025,
"team_id": 5,
"cap_hit": 25000000,
"total_cash": 25000000,
"base_salary": 25000000,
"rank": 0,
"player": {
"id": 17896065,
"first_name": "Josh",
"last_name": "Giddey",
"position": "G",
"height": "6-7",
"weight": "216",
"jersey_number": "3",
"college": "NBA Global Academy",
"country": "Australia",
"draft_year": 2021,
"draft_round": 1,
"draft_number": 6,
"team_id": 5
},
"team": {
"id": 5,
"conference": "East",
"division": "Central",
"city": "Chicago",
"name": "Bulls",
"full_name": "Chicago Bulls",
"abbreviation": "CHI"
}
},
{
"id": 6263,
"player_id": 460,
"season": 2025,
"team_id": 5,
"cap_hit": 21481481,
"total_cash": 21481481,
"base_salary": 21481481,
"rank": 85,
"player": {
"id": 460,
"first_name": "Nikola",
"last_name": "Vucevic",
"position": "C",
"height": "6-9",
"weight": "260",
"jersey_number": "9",
"college": "Southern California",
"country": "Montenegro",
"draft_year": 2011,
"draft_round": 1,
"draft_number": 16,
"team_id": 5
},
"team": {
"id": 5,
"conference": "East",
"division": "Central",
"city": "Chicago",
"name": "Bulls",
"full_name": "Chicago Bulls",
"abbreviation": "CHI"
}
},
{
"id": 6280,
"player_id": 102,
"season": 2025,
"team_id": 5,
"cap_hit": 18080496,
"total_cash": 18080496,
"base_salary": 18080496,
"rank": 102,
"player": {
"id": 102,
"first_name": "Zach",
"last_name": "Collins",
"position": "F-C",
"height": "6-9",
"weight": "250",
"jersey_number": "12",
"college": "Gonzaga",
"country": "USA",
"draft_year": 2017,
"draft_round": 1,
"draft_number": 10,
"team_id": 5
},
"team": {
"id": 5,
"conference": "East",
"division": "Central",
"city": "Chicago",
"name": "Bulls",
"full_name": "Chicago Bulls",
"abbreviation": "CHI"
}
},
{
"id": 6281,
"player_id": 3547248,
"season": 2025,
"team_id": 5,
"cap_hit": 18000000,
"total_cash": 18000000,
"base_salary": 18000000,
"rank": 103,
"player": {
"id": 3547248,
"first_name": "Patrick",
"last_name": "Williams",
"position": "F",
"height": "6-6",
"weight": "215",
"jersey_number": "44",
"college": "Florida State",
"country": "USA",
"draft_year": 2020,
"draft_round": 1,
"draft_number": 4,
"team_id": 5
},
"team": {
"id": 5,
"conference": "East",
"division": "Central",
"city": "Chicago",
"name": "Bulls",
"full_name": "Chicago Bulls",
"abbreviation": "CHI"
}
},
{
"id": 6282,
"player_id": 221,
"season": 2025,
"team_id": 5,
"cap_hit": 17991071,
"total_cash": 17991071,
"base_salary": 17991071,
"rank": 104,
"player": {
"id": 221,
"first_name": "Kevin",
"last_name": "Huerter",
"position": "G",
"height": "6-6",
"weight": "198",
"jersey_number": "13",
"college": "Maryland",
"country": "USA",
"draft_year": 2018,
"draft_round": 1,
"draft_number": 19,
"team_id": 5
},
"team": {
"id": 5,
"conference": "East",
"division": "Central",
"city": "Chicago",
"name": "Bulls",
"full_name": "Chicago Bulls",
"abbreviation": "CHI"
}
},
...
]
}
This endpoint retrieves all player contracts for a specific team and season. If the season parameter is not provided, it defaults to the current season.
HTTP Request
GET https://api.balldontlie.io/v1/contracts/teams
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| team_id | true | The team ID |
| season | false | The season year (e.g., 2025). Defaults to current season if not specified. |
Get Player Contracts
curl "https://api.balldontlie.io/v1/contracts/players?player_id=140" \
-H "Authorization: YOUR_API_KEY"
const axios = require("axios");
const response = await axios.get(
"https://api.balldontlie.io/v1/contracts/players",
{
params: {
player_id: 140,
},
headers: {
Authorization: "YOUR_API_KEY",
},
}
);
console.log(response.data);
import requests
response = requests.get(
'https://api.balldontlie.io/v1/contracts/players',
params={'player_id': 140},
headers={'Authorization': 'YOUR_API_KEY'}
)
print(response.json())
The above command returns JSON structured like this:
{
"data": [
{
"id": 7391,
"player_id": 140,
"season": 2027,
"team_id": 11,
"cap_hit": 46097561,
"total_cash": 46097561,
"base_salary": 46097561,
"rank": 24,
"player": {
"id": 140,
"first_name": "Kevin",
"last_name": "Durant",
"position": "F",
"height": "6-11",
"weight": "240",
"jersey_number": "7",
"college": "Texas",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 2,
"team_id": 11
},
"team": {
"id": 11,
"conference": "West",
"division": "Southwest",
"city": "Houston",
"name": "Rockets",
"full_name": "Houston Rockets",
"abbreviation": "HOU"
}
},
{
"id": 7076,
"player_id": 140,
"season": 2026,
"team_id": 11,
"cap_hit": 43902439,
"total_cash": 43902439,
"base_salary": 43902439,
"rank": 28,
"player": {
"id": 140,
"first_name": "Kevin",
"last_name": "Durant",
"position": "F",
"height": "6-11",
"weight": "240",
"jersey_number": "7",
"college": "Texas",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 2,
"team_id": 11
},
"team": {
"id": 11,
"conference": "West",
"division": "Southwest",
"city": "Houston",
"name": "Rockets",
"full_name": "Houston Rockets",
"abbreviation": "HOU"
}
},
{
"id": 6182,
"player_id": 140,
"season": 2025,
"team_id": 11,
"cap_hit": 54708609,
"total_cash": 53282608,
"base_salary": 53282608,
"rank": 4,
"player": {
"id": 140,
"first_name": "Kevin",
"last_name": "Durant",
"position": "F",
"height": "6-11",
"weight": "240",
"jersey_number": "7",
"college": "Texas",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 2,
"team_id": 11
},
"team": {
"id": 11,
"conference": "West",
"division": "Southwest",
"city": "Houston",
"name": "Rockets",
"full_name": "Houston Rockets",
"abbreviation": "HOU"
}
},
{
"id": 5734,
"player_id": 140,
"season": 2024,
"team_id": 24,
"cap_hit": 51179021,
"total_cash": 49856021,
"base_salary": 49856021,
"rank": 4,
"player": {
"id": 140,
"first_name": "Kevin",
"last_name": "Durant",
"position": "F",
"height": "6-11",
"weight": "240",
"jersey_number": "7",
"college": "Texas",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 2,
"team_id": 11
},
"team": {
"id": 24,
"conference": "West",
"division": "Pacific",
"city": "Phoenix",
"name": "Suns",
"full_name": "Phoenix Suns",
"abbreviation": "PHX"
}
},
...
],
"meta": {
"per_page": 25
}
}
This endpoint retrieves contracts for a specific player, optionally filtered by seasons. Results are ordered by season in descending order. This endpoint supports pagination.
HTTP Request
GET https://api.balldontlie.io/v1/contracts/players
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| player_id | true | The player ID |
| seasons | false | Filter by specific seasons. This should be an array: ?seasons[]=2024&seasons[]=2025 |
| cursor | false | The cursor, used for pagination |
| per_page | false | The number of results per page. Defaults to 25. Max is 100 |
Get Player Contract Aggregates
curl "https://api.balldontlie.io/v1/contracts/players/aggregate?player_id=140" \
-H "Authorization: YOUR_API_KEY"
const axios = require("axios");
const response = await axios.get(
"https://api.balldontlie.io/v1/contracts/players/aggregate",
{
params: {
player_id: 140,
},
headers: {
Authorization: "YOUR_API_KEY",
},
}
);
console.log(response.data);
import requests
response = requests.get(
'https://api.balldontlie.io/v1/contracts/players/aggregate',
params={'player_id': 140},
headers={'Authorization': 'YOUR_API_KEY'}
)
print(response.json())
The above command returns JSON structured like this:
{
"data": [
{
"id": 4231,
"player_id": 140,
"start_year": 2026,
"end_year": 2027,
"contract_type": "Veteran Extension",
"contract_status": "UPCOMING EXTENSION",
"contract_years": 2,
"total_value": 90000000,
"average_salary": 45000000,
"guaranteed_at_signing": 90000000,
"total_guaranteed": 90000000,
"signed_using": null,
"free_agent_year": 2028,
"free_agent_status": "UFA",
"contract_notes": ["2027-28: Player Option (deadline 6/29/27)"],
"team_id": 11,
"player": {
"id": 140,
"first_name": "Kevin",
"last_name": "Durant",
"position": "F",
"height": "6-11",
"weight": "240",
"jersey_number": "7",
"college": "Texas",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 2,
"team_id": 11
},
"team": {
"id": 11,
"conference": "West",
"division": "Southwest",
"city": "Houston",
"name": "Rockets",
"full_name": "Houston Rockets",
"abbreviation": "HOU"
}
},
{
"id": 4238,
"player_id": 140,
"start_year": 2007,
"end_year": 2010,
"contract_type": "Rookie",
"contract_status": "expired",
"contract_years": 4,
"total_value": 19505783,
"average_salary": 4876446,
"guaranteed_at_signing": null,
"total_guaranteed": 19505783,
"signed_using": "rookie-scale-exception",
"free_agent_year": null,
"free_agent_status": null,
"contract_notes": null,
"team_id": null,
"player": {
"id": 140,
"first_name": "Kevin",
"last_name": "Durant",
"position": "F",
"height": "6-11",
"weight": "240",
"jersey_number": "7",
"college": "Texas",
"country": "USA",
"draft_year": 2007,
"draft_round": 1,
"draft_number": 2,
"team_id": 11
},
"team": null
},
...
]
}
This endpoint retrieves aggregated multi-year contract data for a specific player, including total contract value, guaranteed amounts, free agency information, and contract metadata. Results are ordered by start_year in descending order.
HTTP Request
GET https://api.balldontlie.io/v1/contracts/players/aggregate
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| player_id | true | The player ID |