### GET /v1/lineups

Source: https://docs.balldontlie.io/

Retrieves starting lineups and bench players for specified NBA games.

```APIDOC
## GET https://api.balldontlie.io/v1/lineups

### Description
Retrieves starting lineups and bench players for NBA games.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/lineups

### Parameters
#### Query Parameters
- **game_ids[]** (array) - Required - The ID of the game(s) to retrieve lineups for.

### Response
#### Success Response (200)
- **data** (array) - A list of player lineup objects.
- **meta** (object) - Metadata containing pagination information.

#### Response Example
{
  "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"
      }
    }
  ],
  "meta": {
    "per_page": 25
  }
}
```

--------------------------------

### Example JSON Response for All Teams

Source: https://docs.balldontlie.io/

This is an example of the JSON structure returned when requesting all teams.

```json
{
  "data": [
    {
      "id":1,
      "conference":"East",
      "division":"Southeast",
      "city":"Atlanta",
      "name":"Hawks",
      "full_name":"Atlanta Hawks",
      "abbreviation":"ATL"
    },
    ...
  ]
}
```

--------------------------------

### Get Player Contracts with Requests (Python)

Source: https://docs.balldontlie.io/

This Python example shows how to retrieve player contracts using the requests library. It specifies the player ID and includes the necessary authorization header.

```python
import requests

response = requests.get(
    'https://api.balldontlie.io/v1/contracts/players',
    params={'player_id': 140},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())
```

--------------------------------

### Get All Teams (JavaScript SDK)

Source: https://docs.balldontlie.io/

Use the Balldontlie SDK for JavaScript to fetch all teams. Ensure you have the SDK installed and replace YOUR_API_KEY with your valid API key.

```javascript
import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const teams = await api.nba.getTeams();
```

--------------------------------

### Get General Team Season Averages (JavaScript)

Source: https://docs.balldontlie.io/

This JavaScript example demonstrates how to retrieve general team season averages using the Fetch API. Remember to substitute 'YOUR_API_KEY' with your valid API key. Error handling is included for network issues.

```javascript
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));
```

--------------------------------

### Get All Teams (Python SDK)

Source: https://docs.balldontlie.io/

Utilize the Balldontlie SDK for Python to get all teams. Replace YOUR_API_KEY with your API key.

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
teams = api.nba.teams.list()
```

--------------------------------

### Play-by-Play JSON Response Structure

Source: https://docs.balldontlie.io/

Example of the JSON structure returned by the play-by-play endpoint.

```json
{
  "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",
      "participants": [185, 22, 1603383]
    },
    {
      "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",
      "participants": [132]
    },
    ...
  ]
}
```

--------------------------------

### Retrieve Player Props

Source: https://docs.balldontlie.io/

Examples for fetching player prop data for a specific game using various HTTP clients.

```bash
curl "https://api.balldontlie.io/v2/odds/player_props?game_id=18447073" \
  -H "Authorization: YOUR_API_KEY"
```

```javascript
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);
```

```python
import requests

response = requests.get(
    'https://api.balldontlie.io/v2/odds/player_props',
    params={'game_id': 18447073},
    headers={'Authorization': 'YOUR_API_KEY'}
)
```

--------------------------------

### Player Data Structure

Source: https://docs.balldontlie.io/

This is an example of the JSON structure returned when retrieving a specific player's data.

```json
{
  "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"
    }
  }
}
```

--------------------------------

### Fetch Betting Odds with Python (Requests)

Source: https://docs.balldontlie.io/

This Python script utilizes the `requests` library to retrieve betting odds. Make sure to install the library (`pip install requests`). The `dates[]` parameter specifies the target date, and the Authorization header is required.

```python
import requests

response = requests.get(
    'https://api.balldontlie.io/v2/odds',
    params={'dates[]': '2025-01-15'},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())
```

--------------------------------

### Get Leaders (Python SDK)

Source: https://docs.balldontlie.io/

Use the balldontlie Python SDK to get statistical leaders. Specify the 'stat_type' and 'season' when calling the method.

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
leaders = api.nba.leaders.get(stat_type="pts", season=2023)
```

--------------------------------

### Fetch Betting Odds with Node.js (Axios)

Source: https://docs.balldontlie.io/

This Node.js snippet uses the Axios library to fetch betting odds. Ensure you have Axios installed (`npm install axios`). The `dates[]` parameter is used to specify the date for which odds are requested.

```javascript
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);
```

--------------------------------

### Example JSON Response

Source: https://docs.balldontlie.io/

The structure of the JSON returned by the player contract aggregate endpoint.

```json
{
  "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
    },
    ...
  ]
}
```

--------------------------------

### Retrieve Player Contract Aggregates

Source: https://docs.balldontlie.io/

Examples for fetching player contract data using cURL, Node.js, and Python.

```shell
curl "https://api.balldontlie.io/v1/contracts/players/aggregate?player_id=140" \
  -H "Authorization: YOUR_API_KEY"
```

```javascript
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);
```

```python
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())
```

--------------------------------

### GET /v1/box_scores/live

Source: https://docs.balldontlie.io/

Retrieves a list of live box scores for NBA games.

```APIDOC
## GET /v1/box_scores/live

### Description
This endpoint retrieves all live box scores for NBA games.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/box_scores/live

### Response
#### Success Response (200)
- **data** (array) - A list of game objects containing date, status, period, time, and team-specific player statistics.

#### Response Example
{
  "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": {},
      "visitor_team": {}
    }
  ]
}
```

--------------------------------

### GET /nba/v1/stats/advanced

Source: https://docs.balldontlie.io/

Retrieves a list of advanced player statistics for the NBA.

```APIDOC
## GET /nba/v1/stats/advanced

### Description
This endpoint retrieves all advanced stats for players, including metrics like Player Impact Estimate (PIE), pace, and various efficiency percentages.

### Method
GET

### Endpoint
https://api.balldontlie.io/nba/v1/stats/advanced

### Parameters
#### Query Parameters
- **season_type** (string) - Required - Available options: regular, playoffs, ist
- **type** (string) - Optional - Required for all categories except hustle.
- **season** (integer) - Required - Returns team season averages for this season
- **team_ids** (array) - Optional - Returns team season averages for these teams. Format: ?team_ids[]=1&team_ids[]=2
- **cursor** (integer) - Optional - The cursor, used for pagination
- **per_page** (integer) - Optional - The number of results per page. Defaults to 25. Max is 100

### Request Example
curl "https://api.balldontlie.io/nba/v1/stats/advanced?seasons[]=2024"

### Response
#### Success Response (200)
- **data** (array) - List of advanced stat objects
- **meta** (object) - Pagination metadata

#### Response Example
{
  "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
    }
  ],
  "meta": {
    "next_cursor": 3296931,
    "per_page": 25
  }
}
```

--------------------------------

### Query Season Averages

Source: https://docs.balldontlie.io/

Example request to retrieve shooting statistics for a specific player during the 2024 regular season.

```bash
curl "https://api.balldontlie.io/v1/season_averages/shooting?season=2024&season_type=regular&type=5ft_range&player_ids[]=246"
```

--------------------------------

### Get All Players (cURL)

Source: https://docs.balldontlie.io/

This cURL command fetches a list of all players. Include your API key in the Authorization header.

```bash
curl "https://api.balldontlie.io/v1/players" \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Retrieve Team Contracts

Source: https://docs.balldontlie.io/

Examples of how to query the team contracts endpoint using various tools and languages.

```bash
curl "https://api.balldontlie.io/v1/contracts/teams?team_id=5&season=2025" \
  -H "Authorization: YOUR_API_KEY"
```

```javascript
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);
```

```python
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())
```

--------------------------------

### GET /v1/plays

Source: https://docs.balldontlie.io/

Retrieves play-by-play data for a specific NBA game in chronological order.

```APIDOC
## GET /v1/plays

### Description
This endpoint retrieves play-by-play data for a specific NBA game. Plays are returned in chronological order.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/plays

### Parameters
#### Query Parameters
- **game_id** (integer) - Required - The ID of the game to get plays for

### Response
#### Success Response (200)
- **data** (array) - List of play objects

#### Response Example
{
  "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",
      "participants": [185, 22, 1603383]
    }
  ]
}
```

--------------------------------

### Get All Players (Python SDK)

Source: https://docs.balldontlie.io/

Fetch all players using the Balldontlie SDK for Python. Provide your API key during initialization.

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
players = api.nba.players.list(per_page=25)
```

--------------------------------

### Example JSON Response for a Specific Team

Source: https://docs.balldontlie.io/

This JSON structure illustrates the response when retrieving data for a single team.

```json
{
  "data": [
    {
      "id": 1,
      "conference": "East",
      "division": "Southeast",
      "city": "Atlanta",
      "name": "Hawks",
      "full_name": "Atlanta Hawks",
      "abbreviation": "ATL"
    }
  ]
}
```

--------------------------------

### GET /games

Source: https://docs.balldontlie.io/

Retrieves a list of NBA games with associated scores, status, and team information.

```APIDOC
## GET /games

### Description
Retrieves all games available in the system.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/games

### Response
#### Success Response (200)
- **data** (array) - A list of game objects.
- **meta** (object) - Pagination metadata including next_cursor and per_page.

#### Response Example
{
  "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,
      "home_team": {
        "id": 6,
        "full_name": "Cleveland Cavaliers"
      }
    }
  ],
  "meta": {
    "next_cursor": 25,
    "per_page": 25
  }
}
```

--------------------------------

### Initialize BalldontlieAPI SDK (JavaScript)

Source: https://docs.balldontlie.io/

Instantiate the BalldontlieAPI client in JavaScript. Ensure you replace YOUR_API_KEY with your actual API key.

```javascript
import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
```

--------------------------------

### Initialize BalldontlieAPI Client (Python)

Source: https://docs.balldontlie.io/

Initialize the BalldontlieAPI client in Python. Remember to substitute YOUR_API_KEY with your valid API key.

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
```

--------------------------------

### Retrieve Game Lineups

Source: https://docs.balldontlie.io/

Examples for fetching lineup data using various programming environments. Ensure you replace YOUR_API_KEY with your actual API credentials.

```bash
curl "https://api.balldontlie.io/v1/lineups?game_ids[]=18447170" \
  -H "Authorization: YOUR_API_KEY"
```

```javascript
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);
```

```python
import requests

response = requests.get(
    'https://api.balldontlie.io/v1/lineups',
    params={'game_ids[]': 18447170},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())
```

--------------------------------

### Example JSON Response for All Players

Source: https://docs.balldontlie.io/

This JSON structure shows the format of the response when requesting all players, including player details and metadata for pagination.

```json
{
  "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
  }
}
```

--------------------------------

### Example API Response with Pagination Meta

Source: https://docs.balldontlie.io/

This JSON structure shows the pagination metadata returned in API responses. Use 'next_cursor' to fetch subsequent pages of results.

```json
{
  "meta": {
    "next_cursor": 90,
    "per_page": 25
  }
}
```

--------------------------------

### Get Team Standings (JavaScript SDK)

Source: https://docs.balldontlie.io/

Use the balldontlie JavaScript SDK to get team standings for a given season. Pass the season year as an option.

```javascript
import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const standings = await api.nba.getStandings({ season: 2024 });
```

--------------------------------

### Get a Specific Team (Python SDK)

Source: https://docs.balldontlie.io/

Use the Balldontlie SDK for Python to get information about a specific team by its ID. Remember to use your API key.

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
teams = api.nba.teams.get(1)
```

--------------------------------

### Get All Games (cURL)

Source: https://docs.balldontlie.io/

Use this cURL command to retrieve a list of all games. Remember to replace YOUR_API_KEY with your valid API key.

```bash
curl "https://api.balldontlie.io/v1/games" \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### GET /v1/box_scores

Source: https://docs.balldontlie.io/

Retrieves all box scores for a specified date.

```APIDOC
## GET /v1/box_scores

### Description
Retrieves all box scores for a specified date.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/box_scores

### Parameters
#### Query Parameters
- **date** (string) - Required - Returns all box scores for this date. The date should be formatted in YYYY-MM-DD.

### Request Example
curl "https://api.balldontlie.io/v1/box_scores?date=2024-02-07"

### Response
#### Success Response (200)
- **data** (array) - A list of box score objects containing game details, team scores, and player statistics.

#### Response Example
{
  "data": [
    {
      "date": "2024-02-07",
      "season": 2023,
      "status": "Final",
      "home_team_score": 117,
      "visitor_team_score": 123
    }
  ]
}
```

--------------------------------

### GET /v1/contracts/teams

Source: https://docs.balldontlie.io/

Retrieves a list of player contracts for a specified team and season.

```APIDOC
## GET /v1/contracts/teams

### Description
Retrieves all player contracts for a specific team and season. If the season parameter is not provided, it defaults to the current season.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/contracts/teams

### Parameters
#### Query Parameters
- **team_id** (integer) - Required - The unique identifier for the team.
- **season** (integer) - Optional - The season year (e.g., 2025).

### Response
#### Success Response (200)
- **data** (array) - A list of contract objects containing player and team details.

#### Response Example
{
  "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"
      },
      "team": {
        "id": 5,
        "full_name": "Chicago Bulls"
      }
    }
  ]
}
```

--------------------------------

### Get All Active Players

Source: https://docs.balldontlie.io/

Retrieves a list of all currently active NBA players.

```bash
curl "https://api.balldontlie.io/v1/players/active" \
  -H "Authorization: YOUR_API_KEY"
```

```javascript
import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const players = await api.nba.getActivePlayers();
```

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
players = api.nba.players.list_active()
```

--------------------------------

### Get All Games (Python SDK)

Source: https://docs.balldontlie.io/

Retrieve all game data using the Balldontlie Python SDK. Ensure the SDK is initialized with your API key.

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
games = api.nba.games.list()
```

--------------------------------

### GET /v1/contracts/teams

Source: https://docs.balldontlie.io/

Retrieves contract information for a specific team, optionally filtered by season.

```APIDOC
## GET /v1/contracts/teams

### Description
Retrieves contract information for a specific team, optionally filtered by season.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/contracts/teams

### Parameters
#### Query Parameters
- **team_id** (integer) - Required - The team ID
- **season** (integer) - Optional - The season year (e.g., 2025). Defaults to current season if not specified.
```

--------------------------------

### Get All Games (JavaScript SDK)

Source: https://docs.balldontlie.io/

Fetch all game data using the Balldontlie JavaScript SDK. Initialize the SDK with your API key before calling this method.

```javascript
import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const games = await api.nba.getGames();
```

--------------------------------

### GET /v1/players/active

Source: https://docs.balldontlie.io/

Retrieves a list of all currently active NBA players with optional filtering.

```APIDOC
## GET /v1/players/active

### Description
This endpoint retrieves all active players.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/players/active

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - The cursor, used for pagination
- **per_page** (integer) - Optional - The number of results per page. Default to 25. Max is 100
- **search** (string) - Optional - Returns players whose first or last name matches this value
- **first_name** (string) - Optional - Returns players whose first name matches this value
- **last_name** (string) - Optional - Returns players whose last name matches this value
- **team_ids** (array) - Optional - Returns players that belong to these team ids
- **player_ids** (array) - Optional - Returns players that match these ids

### Response
#### Success Response (200)
- **data** (array) - List of player objects
- **meta** (object) - Pagination metadata

#### Response Example
{
  "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
  }
}
```

--------------------------------

### Authenticate API Requests

Source: https://docs.balldontlie.io/

Use this header format to authorize your API requests. Replace YOUR_API_KEY with your personal API key obtained from the website.

```bash
curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Get All Players (JavaScript SDK)

Source: https://docs.balldontlie.io/

Use the Balldontlie SDK for JavaScript to retrieve all players. Initialize the SDK with your API key.

```javascript
import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const players = await api.nba.getPlayers();
```

--------------------------------

### Get a Specific Team

Source: https://docs.balldontlie.io/

Retrieves details for a single NBA team based on its ID.

```APIDOC
## GET /v1/teams/<ID>

### Description
Retrieves a specific team by its ID.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/teams/<ID>

### Parameters
#### Path Parameters
- **ID** (integer) - Required - The ID of the team to retrieve.

### Response
#### Success Response (200)
- **data** (array) - An array containing a single team object.
  - **id** (integer) - The unique identifier for the team.
  - **conference** (string) - The conference the team belongs to.
  - **division** (string) - The division the team belongs to.
  - **city** (string) - The city the team is based in.
  - **name** (string) - The name of the team.
  - **full_name** (string) - The full name of the team.
  - **abbreviation** (string) - The abbreviation of the team.

### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "conference": "East",
      "division": "Southeast",
      "city": "Atlanta",
      "name": "Hawks",
      "full_name": "Atlanta Hawks",
      "abbreviation": "ATL"
    }
  ]
}
```
```

--------------------------------

### Get All Teams

Source: https://docs.balldontlie.io/

Retrieves a list of all NBA teams. You can filter the results by division or conference.

```APIDOC
## GET /v1/teams

### Description
Retrieves all teams.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/teams

### Query Parameters
- **division** (string) - Optional - Returns teams that belong to this division.
- **conference** (string) - Optional - Returns teams that belong to this conference.

### Response
#### Success Response (200)
- **data** (array) - An array of team objects.
  - **id** (integer) - The unique identifier for the team.
  - **conference** (string) - The conference the team belongs to.
  - **division** (string) - The division the team belongs to.
  - **city** (string) - The city the team is based in.
  - **name** (string) - The name of the team.
  - **full_name** (string) - The full name of the team.
  - **abbreviation** (string) - The abbreviation of the team.

### Response Example
```json
{
  "data": [
    {
      "id":1,
      "conference":"East",
      "division":"Southeast",
      "city":"Atlanta",
      "name":"Hawks",
      "full_name":"Atlanta Hawks",
      "abbreviation":"ATL"
    }
  ]
}
```
```

--------------------------------

### GET /v1/contracts/players

Source: https://docs.balldontlie.io/

Retrieves contracts for a specific player, optionally filtered by seasons. Supports pagination.

```APIDOC
## GET /v1/contracts/players

### Description
Retrieves contracts for a specific player, optionally filtered by seasons. Results are ordered by season in descending order. This endpoint supports pagination.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/contracts/players

### Parameters
#### Query Parameters
- **player_id** (integer) - Required - The player ID
- **seasons** (array) - Optional - Filter by specific seasons (e.g., ?seasons[]=2024&seasons[]=2025)
- **cursor** (string) - Optional - The cursor, used for pagination
- **per_page** (integer) - Optional - The number of results per page. Defaults to 25. Max is 100

### Response
#### Success Response (200)
- **data** (array) - List of contract objects
- **meta** (object) - Pagination metadata

#### Response Example
{
  "data": [
    {
      "id": 7391,
      "player_id": 140,
      "season": 2027,
      "team_id": 11,
      "cap_hit": 46097561
    }
  ],
  "meta": {
    "per_page": 25
  }
}
```

--------------------------------

### GET /nba/v2/stats/advanced

Source: https://docs.balldontlie.io/

Retrieves advanced statistical data for NBA players. Supports filtering by season.

```APIDOC
## GET /nba/v2/stats/advanced

### Description
Retrieves advanced statistical data for NBA players. This endpoint provides detailed metrics such as offensive/defensive ratings, usage percentages, and tracking data.

### Method
GET

### Endpoint
https://api.balldontlie.io/nba/v2/stats/advanced

### Parameters
#### Query Parameters
- **seasons[]** (array) - Optional - Filter results by specific NBA seasons (e.g., 2025).

### Request Example
curl "https://api.balldontlie.io/nba/v2/stats/advanced?seasons[]=2025" \
  -H "Authorization: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (array) - A list of advanced stat objects for players.

#### Response Example
{
  "data": [
    {
      "id": 5,
      "pace": 93.02,
      "offensive_rating": 111.1,
      "defensive_rating": 104.3,
      "player": {
        "id": 175,
        "first_name": "Shai",
        "last_name": "Gilgeous-Alexander"
      }
    }
  ]
}
```

--------------------------------

### Get All Stats using Python SDK

Source: https://docs.balldontlie.io/

Fetch all game statistics using the Balldontlie Python SDK. Ensure the SDK is initialized with your API key.

```python
from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
stats = api.nba.stats.list()
```

--------------------------------

### Get a Specific Game using cURL

Source: https://docs.balldontlie.io/

Use this cURL command to retrieve details for a specific game by its ID. Replace YOUR_API_KEY with your actual API key.

```bash
curl "https://api.balldontlie.io/v1/games/<ID>" \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### GET /v1/season_averages/{category}

Source: https://docs.balldontlie.io/

Retrieves season averages for players based on specified categories and filters.

```APIDOC
## GET /v1/season_averages/{category}

### Description
Retrieves season averages for players based on a specified category and various query filters.

### Method
GET

### Endpoint
https://api.balldontlie.io/v1/season_averages/{category}

### Parameters
#### Path Parameters
- **category** (string) - Required - The category of statistics to retrieve.

#### Query Parameters
- **season_type** (string) - Required - Available options: regular, playoffs, ist, playin.
- **type** (string) - Optional - Required for all categories except hustle. Specifies the sub-type of statistics.
- **season** (integer) - Required - The season year to retrieve averages for.
- **player_ids** (array) - Optional - List of player IDs to filter results. Format: ?player_ids[]=1&player_ids[]=2.
- **cursor** (string) - Optional - The cursor used for pagination.
- **per_page** (integer) - Optional - Number of results per page. Defaults to 25, max 100.

### Request Example
GET https://api.balldontlie.io/v1/season_averages/shooting?season=2024&season_type=regular&type=5ft_range&player_ids[]=246
```