NBA API
Welcome to the BALLDONTLIE NBA API, the best NBA and live betting odds 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.
If you're looking for the NFL API go here.
If you're looking for the MLB API go here.
Join us on discord.
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.
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 |
Stats | No | Yes | Yes |
Active Players | No | Yes | Yes |
Player Injuries | No | Yes | Yes |
Season Averages | No | Yes | Yes |
Advanced Stats | No | No | Yes |
Box Scores | No | No | Yes |
Team Standings | No | No | Yes |
Leaders | No | No | Yes |
Betting Odds | No | No | Yes |
The feature breakdown per tier is shown in the table below.
Tier | Requests / Min | $USD / mo. |
---|---|---|
GOAT | 6000 | 39.99 |
ALL-STAR | 600 | 9.99 |
Free | 30 | 0 |
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"
Make sure to replace
YOUR_API_KEY
with 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"
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"
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"
The above command returns JSON structured like this:
{
"data": [
{
"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,
"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"
The above command returns JSON structured like this:
{
"data": {
"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,
"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. |
Get All Games
curl "https://api.balldontlie.io/v1/games" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"date": "2018-10-16",
"season": 2018,
"status": "Final",
"period": 4,
"time": " ",
"postseason": false,
"home_team_score": 105,
"visitor_team_score": 87,
"home_team": {
"id": 2,
"conference": "East",
"division": "Atlantic",
"city": "Boston",
"name": "Celtics",
"full_name": "Boston Celtics",
"abbreviation": "BOS"
},
"visitor_team": {
"id": 23,
"conference": "East",
"division": "Atlantic",
"city": "Philadelphia",
"name": "76ers",
"full_name": "Philadelphia 76ers",
"abbreviation": "PHI"
}
},
...
],
"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"
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"date": "2018-10-16",
"season": 2018,
"status": "Final",
"period": 4,
"time": " ",
"postseason": false,
"home_team_score": 105,
"visitor_team_score": 87,
"home_team": {
"id": 2,
"conference": "East",
"division": "Atlantic",
"city": "Boston",
"name": "Celtics",
"full_name": "Boston Celtics",
"abbreviation": "BOS"
},
"visitor_team": {
"id": 23,
"conference": "East",
"division": "Atlantic",
"city": "Philadelphia",
"name": "76ers",
"full_name": "Philadelphia 76ers",
"abbreviation": "PHI"
}
}
]
}
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 |
Stats
Get All Stats
curl "https://api.balldontlie.io/v1/stats"
The above command returns JSON structured like this:
{
"data": [
{
"id": 14325883,
"min": "38",
"fgm": 10,
"fga": 16,
"fg_pct": 0.625,
"fg3m": 0,
"fg3a": 1,
"fg3_pct": 0,
"ftm": 11,
"fta": 22,
"ft_pct": 0.5,
"oreb": 3,
"dreb": 7,
"reb": 10,
"ast": 9,
"stl": 2,
"blk": 1,
"turnover": 5,
"pf": 1,
"pts": 31,
"player": {
"id": 15,
"first_name": "Giannis",
"last_name": "Antetokounmpo",
"position": "F",
"height": "6-11",
"weight": "243",
"jersey_number": "34",
"college": "Filathlitikos",
"country": "Greece",
"draft_year": 2013,
"draft_round": 1,
"draft_number": 15,
"team_id": 17
},
"team": {
"id": 17,
"conference": "East",
"division": "Central",
"city": "Milwaukee",
"name": "Bucks",
"full_name": "Milwaukee Bucks",
"abbreviation": "MIL"
},
"game": {
"id": 1038184,
"date": "2024-01-20",
"season": 2023,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": false,
"home_team_score": 135,
"visitor_team_score": 141,
"home_team_id": 9,
"visitor_team_id": 17
}
},
...
],
"meta": {
"next_cursor": 14325888,
"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 |
Season Averages
Get Averages
curl "https://api.balldontlie.io/v1/season_averages"
The above command returns JSON structured like this:
{
"data": [
{
"pts": 30.978,
"ast": 6.178,
"turnover": 3.511,
"pf": 2.978,
"fga": 19.044,
"fgm": 11.556,
"fta": 11.222,
"ftm": 7.422,
"fg3a": 1.711,
"fg3m": 0.444,
"reb": 11.622,
"oreb": 2.622,
"dreb": 9,
"stl": 1.289,
"blk": 1.111,
"fg_pct": 0.607,
"fg3_pct": 0.26,
"ft_pct": 0.661,
"min": "35:09",
"games_played": 45,
"player_id": 15,
"season": 2023
}
]
}
HTTP Request
GET https://api.balldontlie.io/v1/season_averages
Query Parameters
?season=2018&player_id=1
will return regular season averages for player_id 1 in 2018.
Parameter | Required | Description |
---|---|---|
season | true | Returns season averages for this season |
player_id | true | Returns season averages for this player |
Advanced Stats
Attributes
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
curl "https://api.balldontlie.io/v1/stats/advanced"
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"pie": -0.031,
"pace": 98.08,
"assist_percentage": 0.15,
"assist_ratio": 25,
"assist_to_turnover": 0.75,
"defensive_rating": 100,
"defensive_rebound_percentage": 0.132,
"effective_field_goal_percentage": 0,
"net_rating": -20,
"offensive_rating": 80,
"offensive_rebound_percentage": 0.069,
"rebound_percentage": 0.104,
"true_shooting_percentage": 0.087,
"turnover_ratio": 33.3,
"usage_percentage": 0.127,
"player": {
"id": 2970,
"first_name": "Olden",
"last_name": "Polynice",
"position": "",
"height": "7-0",
"weight": "250",
"jersey_number": "0",
"college": "Virginia",
"country": "USA",
"draft_year": 1987,
"draft_round": 1,
"draft_number": 8,
"team_id": 26
},
"team": {
"id": 26,
"conference": "West",
"division": "Pacific",
"city": "Sacramento",
"name": "Kings",
"full_name": "Sacramento Kings",
"abbreviation": "SAC"
},
"game": {
"id": 3524,
"date": "1996-11-01",
"season": 1996,
"status": "Final",
"period": 4,
"time": " ",
"postseason": false,
"home_team_score": 96,
"visitor_team_score": 85,
"home_team_id": 11,
"visitor_team_id": 26
}
},
...
],
"meta": {
"next_cursor": 14325888,
"per_page": 25
}
}
This endpoint retrieves all advanced stats.
HTTP Request
GET https://api.balldontlie.io/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 |
Box Scores
Get Live Box Scores
curl "https://api.balldontlie.io/v1/box_scores/live"
The above command returns JSON structured like this:
{
"data": [
{
"date": "2024-02-07",
"season": 2023,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": 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,
"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,
"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"
The above command returns JSON structured like this:
{
"data": [
{
"date": "2024-02-07",
"season": 2023,
"status": "Final",
"period": 4,
"time": "Final",
"postseason": 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,
"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,
"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 |
Active Players
Get All Active Players
curl "https://api.balldontlie.io/v1/players/active" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"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,
"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"
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=2023" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 10,
"conference": "West",
"division": "Pacific",
"city": "Golden State",
"name": "Warriors",
"full_name": "Golden State Warriors",
"abbreviation": "GSW"
},
"conference_record": "10-1",
"conference_rank": 1,
"division_record": "5-0",
"division_rank": 1,
"wins": 11,
"losses": 1,
"home_record": "8-0",
"road_record": "2-1",
"season": 2023
},
...
]
}
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"
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 regular season 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 reb , dreb , tov , ast , oreb , min , pts , stl , blk . For example, ?stat_type=pts will return the current points per game leaders |
season | true | Returns leaders for the specified season |
Betting Odds
These response attributes are worth noting:
Attribute | Type | Values | Notes |
---|---|---|---|
type | string | 2way , spread , over/under |
|
live | boolean | true , false |
Live odds update in real time. |
vendor | string | WilliamHillNewJersey , MGMLiveOdds , FanDuelLive , SugarHouseNJLive , Bet365NewJersey , WilliamHillNewJerseyLiveOdds , FanDuel , SugarHouseNJ , TabSportBet , DraftKings , Betplay , MGM , PointsBet |
Get Betting Odds
curl "https://api.balldontlie.io/v1/odds?date=2024-04-01" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"type": "2way",
"vendor": "MGMLiveOdds",
"live": true,
"game_id": 1,
"odds_decimal_home": "2.45",
"odds_decimal_visitor": "1.50",
"odds_american_home": "+145",
"odds_american_visitor": "-200",
},
{
"type": "spread",
"vendor": "Betplay",
"live": true,
"game_id": 1,
"odds_decimal_home": "2.45",
"odds_decimal_visitor": "1.50",
"odds_american_home": "+145",
"odds_american_visitor": "-200",
"away_spread": "-7.5",
},
{
"type": "over/under",
"vendor": "FanDuel",
"live": false,
"game_id": 1,
"odds_decimal_home": "2.45",
"odds_decimal_visitor": "1.50",
"odds_american_home": "+145",
"odds_american_visitor": "-200",
"over_under": "110",
},
...
]
}
This endpoint retrieves betting odds.
HTTP Request
GET https://api.balldontlie.io/v1/odds
Query Parameters
Parameter | Required | Description |
---|---|---|
date | true* | Returns all odds for games on this date. |
game_id | true* | Returns all odds for this game_id. |
* Either date
or game_id
MUST be specified as a parameter.