NAV Navbar
shell

Introduction

Welcome to the balldontlie API!

You can use our free API to access NBA related data. No email required. No API key required.

Here's an example of something you can build with this API: example

If your sole purpose is to scrape all the data, please reach out to instead of bombarding our servers. We'll give you the data.

Email us at hello@balldontlie.io with any comments or questions. We hope to build on top of this first iteration with community input. Please reach out if you want to help.

Also, please feel free to donate to help keep the lights on.

Getting Started

You need a computer with internet connection.

Run in Postman

Players

Get All Players

curl "https://www.balldontlie.io/api/v1/players"

The above command returns JSON structured like this:

{
  "data":[
    {
      "id":237,
      "first_name":"LeBron",
      "last_name":"James",
      "position":"F",
      "height_feet": 6,
      "height_inches": 8,
      "weight_pounds": 250,
      "team":{
        "id":14,
        "abbreviation":"LAL",
        "city":"Los Angeles",
        "conference":"West",
        "division":"Pacific",
        "full_name":"Los Angeles Lakers",
        "name":"Lakers"
      }
    }
    ...
 ],
 "meta": {
    "total_pages": 50,
    "current_page": 1,
    "next_page": 2,
    "per_page": 25,
    "total_count": 9999
  }
}

This endpoint retrieves all players from all seasons.

HTTP Request

GET https://www.balldontlie.io/api/v1/players

Query Parameters

Parameter Default Description
page 0 The page number, used for pagination.
per_page 25 The number of results returned per call, used for pagination.
search Used to filter players based on their name. For example, ?search=davis will return players that have 'davis' in their first or last name.

Get a Specific Player

curl "https://www.balldontlie.io/api/v1/players/237"

The above command returns JSON structured like this:

{
  "id":237,
  "first_name":"LeBron",
  "last_name":"James",
  "position":"F",
  "height_feet": 6,
  "height_inches": 8,
  "weight_pounds": 250,
  "team":{
    "id":14,
    "abbreviation":"LAL",
    "city":"Los Angeles",
    "conference":"West",
    "division":"Pacific",
    "full_name":"Los Angeles Lakers",
    "name":"Lakers"
  }
}

This endpoint retrieves a specific player.

HTTP Request

GET https://www.balldontlie.io/api/v1/players/<ID>

URL Parameters

Parameter Description
ID The ID of the player to retrieve

Considerations

Teams

Get All Teams

curl "https://www.balldontlie.io/api/v1/teams"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id":14,
      "abbreviation":"LAL",
      "city":"Los Angeles",
      "conference":"West",
      "division":"Pacific",
      "full_name":"Los Angeles Lakers",
      "name":"Lakers"
    },
    ...
  ],
  "meta": {
    "total_pages": 1,
    "current_page": 1,
    "next_page": null,
    "per_page": 30,
    "total_count": 30
  }
}

This endpoint retrieves all teams for the current season.

HTTP Request

GET https://www.balldontlie.io/api/v1/teams

Query Parameters

Parameter Default Description
page 0 The page number, used for pagination.
per_page 30 The number of results returned per call, used for pagination.

Get a Specific Team

curl "https://www.balldontlie.io/api/v1/teams/14"

The above command returns JSON structured like this:

{
  "id":14,
  "abbreviation":"LAL",
  "city":"Los Angeles",
  "conference":"West",
  "division":"Pacific",
  "full_name":"Los Angeles Lakers",
  "name":"Lakers"
}

This endpoint retrieves a specific team.

HTTP Request

GET https://www.balldontlie.io/api/v1/teams/<ID>

URL Parameters

Parameter Description
ID The ID of the team to retrieve

Considerations

Games

Attributes

These 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://www.balldontlie.io/api/v1/games"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id":1,
      "date":"2018-10-16T00:00:00.000Z",
      "home_team_score":105,
      "visitor_team_score":87,
      "season":2018,
      "period": 4,
      "status": "Final",
      "time": " ",
      "postseason": false,
      "home_team":{
        "id":2,
        "abbreviation":"BOS",
        "city":"Boston",
        "conference":"East",
        "division":"Atlantic",
        "full_name":"Boston Celtics",
        "name":"Celtics"
      },
      "visitor_team":{
        "id":23,
        "abbreviation":"PHI",
        "city":"Philadelphia",
        "conference":"East",
        "division":"Atlantic",
        "full_name":"Philadelphia 76ers",
        "name":"76ers"
      },
    },
    ...
  ],
  "meta": {
    "total_pages": 1877,
    "current_page": 1,
    "next_page": 2,
    "per_page": 25,
    "total_count": 46911
  }
}

This endpoint retrieves all games.

Seasons are represented by the year they began. For example, 2018 represents season 2018-2019.

HTTP Request

GET https://www.balldontlie.io/api/v1/games

Query Parameters

You can combine query parameters. For example: ?seasons[]=2018&team_ids[]=1 will return games for team_id 1 for the 2018-2019 season.

Parameter Default Description
page 0 The page number, used for pagination.
per_page 25 The number of results returned per call, used for pagination.
dates An array of dates formatted in 'YYYY-MM-DD'
seasons An array of seasons
team_ids An array of team_ids
postseason Boolean
start_date A single date in 'YYYY-MM-DD' format. This is used to select games that occur on or after this date.
end_date A single date in 'YYYY-MM-DD' format. This is used to select games that occur on or before this date.

Get a Specific Game

curl "https://www.balldontlie.io/api/v1/games/1"

The above command returns JSON structured like this:

{
  "id":1,
  "date":"2018-10-16T00:00:00.000Z",
  "home_team_score":105,
  "visitor_team_score":87,
  "season":2018,
  "period": 4,
  "status": "Final",
  "time": " ",
  "postseason": false,
  "home_team":{
    "id":2,
    "abbreviation":"BOS",
    "city":"Boston",
    "conference":"East",
    "division":"Atlantic",
    "full_name":"Boston Celtics",
    "name":"Celtics"
  },
  "visitor_team":{
    "id":23,
    "abbreviation":"PHI",
    "city":"Philadelphia",
    "conference":"East",
    "division":"Atlantic",
    "full_name":"Philadelphia 76ers",
    "name":"76ers"
  },
}

This endpoint retrieves a specific game.

HTTP Request

GET https://www.balldontlie.io/api/v1/games/<ID>

URL Parameters

Parameter Description
ID The ID of the game to retrieve

Considerations

Stats

Get All Stats

curl "https://www.balldontlie.io/api/v1/stats"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id":29,
      "ast":2,
      "blk":2,
      "dreb":8,
      "fg3_pct":0.25,
      "fg3a":4,
      "fg3m":1,
      "fg_pct":0.429,
      "fga":21,
      "fgm":9,
      "ft_pct":0.8,
      "fta":5,
      "ftm":4,
      "game":{
        "id":1,
        "date":"2018-10-16T00:00:00.000Z",
        "home_team_id":2,
        "home_team_score":105,
        "season":2018,
        "visitor_team_id":23,
        "visitor_team_score":87
      },
      "min":"36:49",
      "oreb":2,
      "pf":3,
      "player":{
        "id":145,
        "first_name":"Joel",
        "last_name":"Embiid",
        "position":"F-C",
        "team_id":23
      },
      "pts":23,
      "reb":10,
      "stl":1,
      "team":{
        "id":23,
        "abbreviation":"PHI",
        "city":"Philadelphia",
        "conference":"East",
        "division":"Atlantic",
        "full_name":"Philadelphia 76ers",
        "name":"76ers"
      },
      "turnover":5
    },
    ...
  ],
  "meta": {
    "total_pages": 2042,
    "current_page": 1,
    "next_page": 2,
    "per_page": 25,
    "total_count": 51045
  }
}

This endpoint retrieves all stats.

HTTP Request

GET https://www.balldontlie.io/api/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 Default Description
page 0 The page number, used for pagination.
per_page 25 The number of results returned per call, used for pagination.
dates An array of dates formatted in 'YYYY-MM-DD'
seasons An array of seasons
player_ids An array of player_ids
game_ids An array of game_ids
postseason Boolean
start_date A single date in 'YYYY-MM-DD' format. This is used to select games that occur on or after this date.
end_date A single date in 'YYYY-MM-DD' format. This is used to select games that occur on or before this date.

Considerations

Errors

The balldontlie API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
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 -- Stop bombarding us.
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.