# DunkAPI

> The basketball data API. 16 basketball data tools for AI agents. REST API + MCP server.

Full reference with response shapes: https://dunkapi.com/llms-full.txt
MCP server setup: https://dunkapi.com/llms-install.md
MCP server for AI agents (clients, prompts, every tool): https://dunkapi.com/mcp
Datasets with live coverage by season: https://dunkapi.com/docs/atlas
Tool catalogue with JSON Schema: https://mcp.dunkapi.com/v1/tools

## Quick Start

- API base URL: https://mcp.dunkapi.com
- Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`
- MCP server: `https://mcp.dunkapi.com/mcp?key=YOUR_API_KEY`
- 500 free credits on signup, no credit card required
- REST API responses include `X-Credits-Used` and `X-Credits-Remaining` headers
- Seasons: the year the season ends (2025 = 2024-25); WNBA: the calendar year. Team codes like BOS, LAL, NY (or an ESPN team id); list_teams has them. Game ids like 401705127 (an ESPN game id; find them with list_games).

## Which Tool Should I Use?

### Static reference
- Team ids, abbreviations and colours for a season -> list_teams (1 cr)
- Find players by name -> search_players (1 cr)

### Basic lookup
- Games with scores by season, date, range or team -> list_games (2 cr)
- Upcoming games with the median line across sportsbooks -> get_schedule (2 cr)
- Standings from every final game: overall, conference, home, away, last 10 -> get_standings (2 cr)
- The latest injury report: status, injury and expected return (NBA, WNBA) -> get_injuries (2 cr)
- Our team Elo ratings, ranked -> get_ratings (2 cr)

### Stats + aggregation
- One game: both box scores, every player's line, each book's line, win probability -> get_game (5 cr)
- Profile, per-season averages and shooting splits, last 10 games -> get_player (5 cr)
- A player's full game log -> get_player_games (5 cr)
- Season leaders per game, by percentage or in total -> get_leaders (5 cr)
- Pace, offensive, defensive and net rating, and the four factors -> get_team_stats (5 cr)
- Every sportsbook's moneyline, spread and total for a game (5) or a day (10), with results against the line -> get_odds (5 cr)

### Multi-table
- Play-by-play with shot locations, zones, expected points and win probability -> get_plays (10 cr)
- Shot profile by zone for a player, team or defence, with every shot's x/y -> get_shot_chart (10 cr)

### Time-series
- Daily snapshots of each sportsbook's line before tip-off -> get_line_movement (10 cr)

## Intents

- "What were last night's NBA scores?" -> list_games
- "Which games are on this week, and what are the spreads?" -> get_schedule
- "Box score and every book's line for one game" -> get_game
- "Who is out tonight?" -> get_injuries
- "What is Jayson Tatum's player id?" -> search_players
- "Tatum's averages by season" -> get_player
- "Every game Tatum played in 2023-24" -> get_player_games
- "Who led the league in true shooting?" -> get_leaders
- "Which team plays fastest, and who has the best net rating?" -> get_team_stats
- "Where does Tatum shoot from, and how well?" -> get_shot_chart
- "Every clutch shot Tatum took this season" -> get_plays
- "Who covered, and did the total go over?" -> get_odds
- "How did the line move before tip-off?" -> get_line_movement
- "Who is the best team right now?" -> get_ratings
- "The standings" -> get_standings
- "Team ids and abbreviations" -> list_teams

## Pages

- [Docs](https://dunkapi.com/docs): every endpoint, with parameters and a live example response.
- [Data changelog](https://dunkapi.com/changelog): when each dataset was last refreshed and what it runs through, read from the database.
- [Data atlas](https://dunkapi.com/docs/atlas): what exists, which endpoints expose it, and where coverage is partial.
- [Teams](https://dunkapi.com/teams): a page per club with its record, season figures and recent games.
- [Pricing](https://dunkapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://dunkapi.com/signup): 500 free credits, no card.

### Live odds

- [Upcoming NBA odds](https://dunkapi.com/odds): Spreads, totals and moneylines for the next week's NBA games from the sportsbooks ESPN reports, refreshed daily.

### Other leagues

- [The WNBA API](https://dunkapi.com/wnba): WNBA games since 2006: play-by-play with shot locations, box scores, standings, ratings and sportsbook lines. REST and MCP. MCP: https://mcp.dunkapi.com/mcp/wnba
- [The college basketball API](https://dunkapi.com/college-basketball): Every Division I men's college basketball game since 2013-14: play-by-play, box scores, ratings and a decade of sportsbook lines. REST and MCP. MCP: https://mcp.dunkapi.com/mcp/ncaam
- [The women's college basketball API](https://dunkapi.com/womens-college-basketball): Division I women's college basketball since 2014-15: box scores, standings, ratings, and play-by-play for most games since 2019-20. REST and MCP. MCP: https://mcp.dunkapi.com/mcp/ncaaw

### Datasets

- [NBA play-by-play data](https://dunkapi.com/data/nba-play-by-play): Play-by-play for 23 NBA seasons, from 2003-04: clock, score, players, shot type and location, and win probability from 2018. REST or MCP.
- [NBA shot chart data](https://dunkapi.com/data/nba-shot-chart-data): The x/y location of every NBA field goal attempt in the play-by-play since 2003-04, with distance, zone, result and expected points. REST or MCP.
- [NBA odds history](https://dunkapi.com/data/nba-odds-history): Each sportsbook's moneyline, spread and total for NBA games from 2013-14, with results against the line. Built for backtests. REST or MCP.

### Compared with the alternatives

- [DunkAPI vs BallDontLie](https://dunkapi.com/compare/balldontlie): BallDontLie is a multi-sport API with a free tier and plans per sport. DunkAPI is basketball only, with shot locations, a decade of per-book lines and our own ratings.
- [DunkAPI vs nba_api and stats.nba.com](https://dunkapi.com/compare/nba-api-stats-nba): nba_api wraps unofficial stats.nba.com endpoints that are rate limited and often block cloud IPs. DunkAPI is a documented API that runs from a server or an agent.
- [DunkAPI vs scraping Basketball Reference](https://dunkapi.com/compare/basketball-reference): Basketball Reference has no public API and its terms bar scraping. DunkAPI gives you NBA, WNBA and college data over REST and MCP, with no scraper to maintain.
- [DunkAPI vs Sportradar](https://dunkapi.com/compare/sportradar): Sportradar sells licensed, live basketball feeds via sales contracts. DunkAPI is historical data from public ESPN sources, self-serve, with 500 free credits.

### Endpoint pages

- [list_teams](https://dunkapi.com/docs/list-teams): Team ids, abbreviations and colours for a season
- [list_games](https://dunkapi.com/docs/list-games): Games with scores by season, date, range or team
- [get_schedule](https://dunkapi.com/docs/get-schedule): Upcoming games with the median line across sportsbooks
- [get_game](https://dunkapi.com/docs/get-game): One game: both box scores, every player's line, each book's line, win probability
- [get_standings](https://dunkapi.com/docs/get-standings): Standings from every final game: overall, conference, home, away, last 10
- [get_injuries](https://dunkapi.com/docs/get-injuries): The latest injury report: status, injury and expected return (NBA, WNBA)
- [search_players](https://dunkapi.com/docs/search-players): Find players by name
- [get_player](https://dunkapi.com/docs/get-player): Profile, per-season averages and shooting splits, last 10 games
- [get_player_games](https://dunkapi.com/docs/get-player-games): A player's full game log
- [get_leaders](https://dunkapi.com/docs/get-leaders): Season leaders per game, by percentage or in total
- [get_team_stats](https://dunkapi.com/docs/get-team-stats): Pace, offensive, defensive and net rating, and the four factors
- [get_plays](https://dunkapi.com/docs/get-plays): Play-by-play with shot locations, zones, expected points and win probability
- [get_shot_chart](https://dunkapi.com/docs/get-shot-chart): Shot profile by zone for a player, team or defence, with every shot's x/y
- [get_odds](https://dunkapi.com/docs/get-odds): Every sportsbook's moneyline, spread and total for a game (5) or a day (10), with results against the line
- [get_line_movement](https://dunkapi.com/docs/get-line-movement): Daily snapshots of each sportsbook's line before tip-off
- [get_ratings](https://dunkapi.com/docs/get-ratings): Our team Elo ratings, ranked

### Metric definitions

- [Effective FG%](https://dunkapi.com/glossary/effective-field-goal-percentage): Field goal percentage with a made three counted as 1.5 makes, so a team that shoots threes is not undersold.
- [True shooting %](https://dunkapi.com/glossary/true-shooting): Points scored per shooting possession, counting twos, threes and free throws in one rate.
- [Expected points per shot](https://dunkapi.com/glossary/expected-points-per-shot): The points a shot is worth on average, from where it was taken and what kind it was, fitted on league history.
- [Shot zones](https://dunkapi.com/glossary/shot-zones): Six areas of the floor, from the restricted area to the free throw line, used to summarize where a player or team shoots.
- [Possessions](https://dunkapi.com/glossary/possessions): An estimate of how many times a team had the ball, built from box score counts since the game does not log them.
- [Pace](https://dunkapi.com/glossary/pace): How many possessions a team plays per 48 minutes. It describes tempo, not quality.
- [Net rating](https://dunkapi.com/glossary/net-rating): Points scored minus points allowed per 100 possessions. The standard single number for team strength.
- [Four factors](https://dunkapi.com/glossary/four-factors): Shooting, turnovers, rebounding and free throws: the four team numbers that explain most of the difference between winning and losing.
- [Elo rating](https://dunkapi.com/glossary/elo-rating): Our team rating, updated after every game from the score and where it was played, and pulled toward average each offseason.
- [Win probability](https://dunkapi.com/glossary/win-probability): The chance a team wins, given the score, time left and who has the ball, recomputed on every play.
- [Clutch](https://dunkapi.com/glossary/clutch): The last five minutes of the fourth quarter or overtime with the score within five points.
- [Home court advantage](https://dunkapi.com/glossary/home-court-advantage): The edge a team gets at home, which both the market and our ratings price in as a fixed number of points.
- [Implied probability](https://dunkapi.com/glossary/implied-probability): The win chance a moneyline price states, once converted from American odds to a percentage.
- [Closing line](https://dunkapi.com/glossary/closing-line): A sportsbook's last posted price before tip-off, the standard yardstick for whether a bet was a good one.
- [Line movement](https://dunkapi.com/glossary/line-movement): How a sportsbook's spread, total or moneyline changed between the time it was posted and tip-off.
- [Against the spread](https://dunkapi.com/glossary/against-the-spread): Whether a team won by more than the point spread, so a loss can still be a cover and a win can still be a miss.

### By what you are building

- [Analysts and researchers](https://dunkapi.com/for/analysts): Play-by-play with x/y for every field goal attempt, expected points per shot and shot zones, joined to box scores.
- [Bettors and modelers](https://dunkapi.com/for/bettors): Moneyline, spread and total from 4 to 12 books per regular-season game for 2013-14 to 2023-24, joined to the result and our ratings.
- [Developers and AI builders](https://dunkapi.com/for/developers): REST and MCP over the NBA, WNBA and college basketball: games, players, plays, odds and ratings, with stable ids.