NAV
shell

Introduction

Welcome to the BALLDONTLIE 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.

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.

Read the table below to see the breakdown.

The asterisk * indicates that only data from the current season is available.

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
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_ids[]=1&player_ids[]=2 will return regular season averages for player_ids 1 and 2 in 2018.

Parameter Required Description
season true Returns season averages for this season
player_ids true Returns season averages for these player ids. This should be an array: ?player_ids[]=1&player_ids[]=2

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

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.