# BALLDONTLIE API - Google Sheets Integration

Access sports data from the BALLDONTLIE API directly in your Google Sheets using custom functions.

## Setup

1. **Get an API Key**
   - Sign up at [app.balldontlie.io](https://app.balldontlie.io/signup)
   - Copy your API key from the dashboard

2. **Add the Script to Google Sheets**
   - Open your Google Sheet
   - Go to **Extensions > Apps Script**
   - Delete any existing code in the editor
   - Copy and paste the contents of `balldontlie.gs` into the editor
   - Click **Save** (disk icon)

3. **Set Your API Key**
   - In the Apps Script editor, select `BDL_SET_API_KEY` from the function dropdown
   - Click **Run**
   - When prompted, enter your API key
   - Alternatively, in any cell type: `=BDL_SET_API_KEY("your-api-key-here")`

4. **Start Using Functions**
   - Type any function in a cell, e.g., `=BDL_NBA_TEAMS()`
   - Data will populate automatically

## Available Functions

### NBA
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_NBA_TEAMS` | Get all NBA teams | conference, division |
| `BDL_NBA_TEAM` | Get specific team | teamId |
| `BDL_NBA_PLAYERS` | Get NBA players | search, teamId, perPage |
| `BDL_NBA_PLAYERS_ACTIVE` | Get active players only | search, teamId, perPage |
| `BDL_NBA_PLAYER` | Get specific player | playerId |
| `BDL_NBA_GAMES` | Get NBA games | date, season, teamId, perPage |
| `BDL_NBA_GAME` | Get specific game | gameId |
| `BDL_NBA_STATS` | Get player stats | playerId, gameId, season, perPage |
| `BDL_NBA_SEASON_AVERAGES` | Get season averages | playerId, season |
| `BDL_NBA_STANDINGS` | Get standings | season |
| `BDL_NBA_INJURIES` | Get injury report | teamId, perPage |
| `BDL_NBA_BOX_SCORES_LIVE` | Get live box scores | - |
| `BDL_NBA_BOX_SCORES` | Get box scores by date | date |
| `BDL_NBA_LEADERS` | Get stat leaders | statType, season, seasonType |
| `BDL_NBA_ODDS` | Get betting odds | date, gameId, perPage |
| `BDL_NBA_PLAYER_PROPS` | Get player prop odds | gameId, playerId, propType |
| `BDL_NBA_ADVANCED_STATS` | Get advanced stats | playerId, gameId, season, perPage |
| `BDL_NBA_LINEUPS` | Get game lineups | gameId |
| `BDL_NBA_PLAYS` | Get play-by-play | gameId, perPage |

### NFL
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_NFL_TEAMS` | Get all NFL teams | conference, division |
| `BDL_NFL_TEAM` | Get specific team | teamId |
| `BDL_NFL_ROSTER` | Get team roster | teamId, season |
| `BDL_NFL_PLAYERS` | Get NFL players | search, teamId, perPage |
| `BDL_NFL_PLAYERS_ACTIVE` | Get active players | search, teamId, perPage |
| `BDL_NFL_GAMES` | Get NFL games | date, season, week, perPage |
| `BDL_NFL_STATS` | Get player stats | playerId, gameId, season, perPage |
| `BDL_NFL_STANDINGS` | Get standings | season |
| `BDL_NFL_INJURIES` | Get injury report | teamId, perPage |
| `BDL_NFL_SEASON_STATS` | Get season stats | playerId, season, seasonType, perPage |
| `BDL_NFL_ODDS` | Get betting odds | date, gameId, perPage |
| `BDL_NFL_PLAYER_PROPS` | Get player prop odds | gameId, playerId, propType |
| `BDL_NFL_ADVANCED_RUSHING` | Advanced rushing stats | playerId, season, perPage |
| `BDL_NFL_ADVANCED_PASSING` | Advanced passing stats | playerId, season, perPage |
| `BDL_NFL_ADVANCED_RECEIVING` | Advanced receiving stats | playerId, season, perPage |
| `BDL_NFL_PLAYS` | Get play-by-play | gameId, perPage |

### MLB
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_MLB_TEAMS` | Get all MLB teams | league, division |
| `BDL_MLB_PLAYERS` | Get MLB players | search, teamId, perPage |
| `BDL_MLB_PLAYERS_ACTIVE` | Get active players | search, teamId, perPage |
| `BDL_MLB_GAMES` | Get MLB games | date, season, teamId, perPage |
| `BDL_MLB_STATS` | Get player stats | playerId, gameId, season, perPage |
| `BDL_MLB_STANDINGS` | Get standings | season |
| `BDL_MLB_INJURIES` | Get injury report | teamId, perPage |
| `BDL_MLB_SEASON_STATS` | Get season stats | playerId, season, statType, perPage |

### NHL
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_NHL_TEAMS` | Get all NHL teams | conference, division |
| `BDL_NHL_PLAYERS` | Get NHL players | search, teamId, perPage |
| `BDL_NHL_GAMES` | Get NHL games | date, season, teamId, perPage |
| `BDL_NHL_STANDINGS` | Get standings | season |
| `BDL_NHL_BOX_SCORES` | Get box scores | date |
| `BDL_NHL_INJURIES` | Get injury report | teamId, perPage |
| `BDL_NHL_ODDS` | Get betting odds | date, gameId, perPage |
| `BDL_NHL_PLAYER_PROPS` | Get player prop odds | gameId, playerId, propType |

### WNBA
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_WNBA_TEAMS` | Get all WNBA teams | - |
| `BDL_WNBA_PLAYERS` | Get WNBA players | search, teamId, perPage |
| `BDL_WNBA_PLAYERS_ACTIVE` | Get active players | search, teamId, perPage |
| `BDL_WNBA_GAMES` | Get WNBA games | date, season, teamId, perPage |
| `BDL_WNBA_STANDINGS` | Get standings | season |
| `BDL_WNBA_INJURIES` | Get injury report | teamId, perPage |

### College Football (NCAAF)
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_NCAAF_CONFERENCES` | Get conferences | - |
| `BDL_NCAAF_TEAMS` | Get teams | conferenceId |
| `BDL_NCAAF_PLAYERS` | Get players | search, teamId, perPage |
| `BDL_NCAAF_GAMES` | Get games | date, season, week, perPage |
| `BDL_NCAAF_STANDINGS` | Get standings | season, conferenceId |
| `BDL_NCAAF_RANKINGS` | Get rankings | season, week |
| `BDL_NCAAF_ODDS` | Get betting odds | date, gameId, perPage |

### College Basketball (NCAAB)
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_NCAAB_CONFERENCES` | Get conferences | - |
| `BDL_NCAAB_TEAMS` | Get teams | conferenceId |
| `BDL_NCAAB_PLAYERS` | Get players | search, teamId, perPage |
| `BDL_NCAAB_GAMES` | Get games | date, season, teamId, perPage |
| `BDL_NCAAB_STANDINGS` | Get standings | season, conferenceId |
| `BDL_NCAAB_RANKINGS` | Get rankings | season, week |
| `BDL_NCAAB_BRACKET` | Get March Madness bracket | season |
| `BDL_NCAAB_ODDS` | Get betting odds | date, gameId, perPage |

### Soccer - EPL
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_EPL_TEAMS` | Get EPL teams | season |
| `BDL_EPL_PLAYERS` | Get EPL players | search, teamId, perPage |
| `BDL_EPL_MATCHES` | Get EPL matches | date, season, teamId, perPage |
| `BDL_EPL_STANDINGS` | Get standings | season |
| `BDL_EPL_ODDS` | Get betting odds | date, matchId, perPage |

### Soccer - La Liga
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_LALIGA_TEAMS` | Get La Liga teams | season |
| `BDL_LALIGA_PLAYERS` | Get La Liga players | search, teamId, perPage |
| `BDL_LALIGA_MATCHES` | Get La Liga matches | date, season, teamId, perPage |
| `BDL_LALIGA_STANDINGS` | Get standings | season |
| `BDL_LALIGA_ODDS` | Get betting odds | date, matchId, perPage |

### Soccer - Serie A
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_SERIEA_TEAMS` | Get Serie A teams | season |
| `BDL_SERIEA_PLAYERS` | Get Serie A players | search, teamId, perPage |
| `BDL_SERIEA_MATCHES` | Get Serie A matches | date, season, teamId, perPage |
| `BDL_SERIEA_STANDINGS` | Get standings | season |
| `BDL_SERIEA_ODDS` | Get betting odds | date, matchId, perPage |

### Soccer - Bundesliga
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_BUNDESLIGA_TEAMS` | Get Bundesliga teams | season |
| `BDL_BUNDESLIGA_PLAYERS` | Get Bundesliga players | search, teamId, perPage |
| `BDL_BUNDESLIGA_MATCHES` | Get Bundesliga matches | date, season, teamId, perPage |
| `BDL_BUNDESLIGA_STANDINGS` | Get standings | season |
| `BDL_BUNDESLIGA_ODDS` | Get betting odds | date, matchId, perPage |

### Soccer - Ligue 1
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_LIGUE1_TEAMS` | Get Ligue 1 teams | season |
| `BDL_LIGUE1_PLAYERS` | Get Ligue 1 players | search, teamId, perPage |
| `BDL_LIGUE1_MATCHES` | Get Ligue 1 matches | date, season, teamId, perPage |
| `BDL_LIGUE1_STANDINGS` | Get standings | season |
| `BDL_LIGUE1_ODDS` | Get betting odds | date, matchId, perPage |

### Soccer - UCL
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_UCL_TEAMS` | Get UCL teams | season |
| `BDL_UCL_PLAYERS` | Get UCL players | search, teamId, perPage |
| `BDL_UCL_MATCHES` | Get UCL matches | date, season, teamId, perPage |
| `BDL_UCL_STANDINGS` | Get standings | season |
| `BDL_UCL_ODDS` | Get betting odds | date, matchId, perPage |

### Soccer - MLS
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_MLS_TEAMS` | Get MLS teams | season |
| `BDL_MLS_PLAYERS` | Get MLS players | search, teamId, perPage |
| `BDL_MLS_MATCHES` | Get MLS matches | date, season, teamId, perPage |
| `BDL_MLS_STANDINGS` | Get standings | season |
| `BDL_MLS_ODDS` | Get betting odds | date, matchId, perPage |

### MMA
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_MMA_LEAGUES` | Get MMA leagues | - |
| `BDL_MMA_EVENTS` | Get MMA events | leagueId, perPage |
| `BDL_MMA_FIGHTERS` | Get MMA fighters | search, perPage |
| `BDL_MMA_FIGHTS` | Get MMA fights | eventId, fighterId, perPage |
| `BDL_MMA_RANKINGS` | Get rankings | leagueId |
| `BDL_MMA_FIGHT_STATS` | Get fight stats | fightId, perPage |
| `BDL_MMA_ODDS` | Get betting odds | eventId, fightId, perPage |

### Formula 1
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_F1_DRIVERS` | Get F1 drivers | search, perPage |
| `BDL_F1_TEAMS` | Get F1 teams | perPage |
| `BDL_F1_CIRCUITS` | Get F1 circuits | perPage |
| `BDL_F1_SEASONS` | Get F1 seasons | - |
| `BDL_F1_EVENTS` | Get F1 events/races | season, perPage |
| `BDL_F1_SESSIONS` | Get F1 sessions | eventId, perPage |
| `BDL_F1_SESSION_RESULTS` | Get session results | sessionId, perPage |
| `BDL_F1_DRIVER_STANDINGS` | Get driver standings | season |
| `BDL_F1_TEAM_STANDINGS` | Get team standings | season |
| `BDL_F1_LAP_TIMES` | Get lap times | sessionId, driverId, perPage |
| `BDL_F1_QUALIFYING_RESULTS` | Get qualifying results | sessionId, perPage |
| `BDL_F1_PIT_STOPS` | Get pit stops | sessionId, driverId, perPage |
| `BDL_F1_ODDS_FUTURES` | Get futures odds | season |

### ATP Tennis
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_ATP_PLAYERS` | Get ATP players | search, perPage |
| `BDL_ATP_TOURNAMENTS` | Get ATP tournaments | season, perPage |
| `BDL_ATP_RANKINGS` | Get ATP rankings | season, perPage |
| `BDL_ATP_MATCHES` | Get ATP matches | date, tournamentId, playerId, perPage |
| `BDL_ATP_MATCH_STATS` | Get match stats | matchId, perPage |
| `BDL_ATP_HEAD_TO_HEAD` | Get head to head | player1Id, player2Id |
| `BDL_ATP_ODDS` | Get betting odds | date, matchId, perPage |

### WTA Tennis
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_WTA_PLAYERS` | Get WTA players | search, perPage |
| `BDL_WTA_TOURNAMENTS` | Get WTA tournaments | season, perPage |
| `BDL_WTA_RANKINGS` | Get WTA rankings | season, perPage |
| `BDL_WTA_MATCHES` | Get WTA matches | date, tournamentId, playerId, perPage |
| `BDL_WTA_HEAD_TO_HEAD` | Get head to head | player1Id, player2Id |
| `BDL_WTA_ODDS` | Get betting odds | date, matchId, perPage |

### PGA Tour
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_PGA_PLAYERS` | Get PGA players | search, perPage |
| `BDL_PGA_TOURNAMENTS` | Get PGA tournaments | season, perPage |
| `BDL_PGA_COURSES` | Get PGA courses | perPage |
| `BDL_PGA_TOURNAMENT_RESULTS` | Get tournament results | tournamentId, perPage |
| `BDL_PGA_PLAYER_ROUND_RESULTS` | Get player round results | tournamentId, playerId, perPage |
| `BDL_PGA_PLAYER_ROUND_STATS` | Get player round stats | tournamentId, playerId, perPage |
| `BDL_PGA_PLAYER_SEASON_STATS` | Get player season stats | playerId, season, perPage |
| `BDL_PGA_SCORECARDS` | Get player scorecards | tournamentId, playerId, perPage |

### CS2 (Counter-Strike 2)
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_CS2_TEAMS` | Get CS2 teams | search, perPage |
| `BDL_CS2_PLAYERS` | Get CS2 players | search, teamId, perPage |
| `BDL_CS2_TOURNAMENTS` | Get CS2 tournaments | perPage |
| `BDL_CS2_RANKINGS` | Get CS2 rankings | - |
| `BDL_CS2_MATCHES` | Get CS2 matches | date, tournamentId, teamId, perPage |

### League of Legends
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_LOL_TEAMS` | Get LoL teams | search, perPage |
| `BDL_LOL_PLAYERS` | Get LoL players | search, perPage |
| `BDL_LOL_CHAMPIONS` | Get LoL champions | - |
| `BDL_LOL_TOURNAMENTS` | Get LoL tournaments | perPage |
| `BDL_LOL_MATCHES` | Get LoL matches | tournamentId, teamId, perPage |

### Dota 2
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_DOTA_TEAMS` | Get Dota 2 teams | search, perPage |
| `BDL_DOTA_PLAYERS` | Get Dota 2 players | search, perPage |
| `BDL_DOTA_HEROES` | Get Dota 2 heroes | - |
| `BDL_DOTA_TOURNAMENTS` | Get Dota 2 tournaments | perPage |
| `BDL_DOTA_MATCHES` | Get Dota 2 matches | tournamentId, teamId, perPage |

### FIFA World Cup
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_FIFA_TEAMS` | Get FIFA World Cup teams | - |
| `BDL_FIFA_STADIUMS` | Get FIFA World Cup stadiums | - |
| `BDL_FIFA_GROUP_STANDINGS` | Get group standings | - |
| `BDL_FIFA_MATCHES` | Get FIFA World Cup matches | - |
| `BDL_FIFA_ODDS` | Get betting odds | - |
| `BDL_FIFA_ODDS_FUTURES` | Get futures odds | - |

### Generic
| Function | Description | Parameters |
|----------|-------------|------------|
| `BDL_API` | Call any endpoint | endpoint, paramsJson |

## Examples

### Get NBA Teams
```
=BDL_NBA_TEAMS()
=BDL_NBA_TEAMS("East")
=BDL_NBA_TEAMS("West", "Pacific")
```

### Search for Players
```
=BDL_NBA_PLAYERS("LeBron")
=BDL_NFL_PLAYERS("Mahomes")
=BDL_ATP_PLAYERS("Djokovic")
```

### Get Games by Date
```
=BDL_NBA_GAMES("2024-01-15")
=BDL_NFL_GAMES("2024-01-14", 2024, 18)
=BDL_EPL_MATCHES("2024-01-13")
```

### Get Season Averages
```
=BDL_NBA_SEASON_AVERAGES(237, 2024)
```

### Get Standings
```
=BDL_NBA_STANDINGS(2024)
=BDL_NFL_STANDINGS(2024)
=BDL_EPL_STANDINGS(2024)
```

### Get Betting Odds
```
=BDL_NBA_ODDS("2024-01-15")
=BDL_NFL_PLAYER_PROPS(12345)
```

### Use Generic API Function
```
=BDL_API("/nba/v1/teams")
=BDL_API("/nba/v1/players", "{""search"": ""curry""}")
```

## Tips

1. **Auto-refresh**: Google Sheets caches custom function results. To force a refresh, slightly modify a cell parameter or press Ctrl+Shift+E.

2. **Rate Limits**: If you get rate limit errors, reduce the number of cells calling API functions or add delays between requests.

3. **Pagination**: Most functions return 25 results by default. Use the `perPage` parameter to get more (max 100).

4. **Date Format**: Always use YYYY-MM-DD format for dates.

5. **IDs**: To get IDs for filtering, first call the list function (e.g., `BDL_NBA_TEAMS()`), then use those IDs in other functions.

## Support

- **Documentation**: [www.balldontlie.io/docs](https://www.balldontlie.io/docs)
- **Discord**: [discord.gg/cQJhfTPn8j](https://discord.gg/cQJhfTPn8j)
- **API Dashboard**: [app.balldontlie.io](https://app.balldontlie.io)