# DunkAPI

> The basketball data API. 18 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
OpenAPI 3.1 spec: https://mcp.dunkapi.com/openapi.json

## 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`
- Python client: `pip install dunkapi` (https://pypi.org/project/dunkapi/). Reads DUNKAPI_API_KEY.
- 500 free credits every month, 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 a team id); list_teams has them. Game ids like 401705127 (a game id; find them with list_games).

## Data timing and rights

- Odds and props are pre-game only. captured_at is when a line was captured (the page says exactly what it means for each kind of row); where props are held, rows also carry scheduled_start and minutes_before_scheduled_start (negative when captured after the scheduled start).
- Records are overwritten when sources correct them; no revision history is kept.
- You may store the data, train models, backtest, and build commercial products that show your users what you derive. You may not redistribute the data, or odds as a raw feed, as a dataset or API of its own. After an account closes, stored data is for internal use only.
- DunkAPI is independent, not an official league partner, and grants no league rights.
- Full answers: https://dunkapi.com/docs/timing-and-rights

## 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)
- Player prop lines by sportsbook: the closing line (one pre-game capture per line before October 2026) -> get_player_props (10 cr)
- A player's prop lines against the result, game by game -> get_prop_history (10 cr)

### Time-series
- 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 2025-26" -> 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
- "What was the closing points line for this player, and which book had the best price?" -> get_player_props
- "How often does this player go over his points line?" -> get_prop_history

## 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.
- [Status](https://dunkapi.com/status): measured uptime for the website and MCP server over 24 hours, 7 days and 90 days, probed every five minutes from outside our own infrastructure, with incidents and data freshness.
- [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.
- [Players](https://dunkapi.com/players): a page per NBA and college basketball player with prop history: the over/under record against the closing line in each market (points, rebounds, assists, threes and more) and the last games.
- [Data timing and rights](https://dunkapi.com/docs/timing-and-rights): what timestamps mean, when each dataset updates, whether lines are pre-game, and what the terms allow.
- [Pricing](https://dunkapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://dunkapi.com/signup): 500 free credits every month, no card.

### Live odds

- [Upcoming NBA odds](https://dunkapi.com/odds): Spreads, totals and moneylines for the next week's NBA games by sportsbook, captured daily and every hour for games in the next four days.
- [NBA player props today](https://dunkapi.com/props): Today's NBA player props: points, rebounds, assists, threes, blocks and steals, with the consensus line and the best over and under price across sportsbooks.
- [College basketball player props today](https://dunkapi.com/props/college-basketball): Today's men's college basketball player props: points, rebounds and assists, with the consensus line and the best over and under price across sportsbooks.

### 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 (2014-15 to 2018-19 hold about 30% of a full Division I slate; full from 2019-20): box scores, standings, ratings, play-by-play for most games since 2019-20, and sportsbook lines, with opening and closing lines from November 2024. 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.
- [NBA player props by sportsbook, from 2023](https://dunkapi.com/data/player-props): NBA player prop lines by sportsbook since May 2023: the closing line, and the opening line where held, with each player's history against his line. REST or MCP.

### Compared with the alternatives

- [The NBA API: free endpoints, nba_api and DunkAPI](https://dunkapi.com/compare/nba-api): The NBA has no documented public API. stats.nba.com, cdn.nba.com and ESPN's endpoints are free but unofficial. Where each fits, and how DunkAPI differs. (checked 2026-10-14)
- [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. (checked 2026-10-07)
- [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. (checked 2026-10-07)
- [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. (checked 2026-10-07)
- [DunkAPI vs Sportradar](https://dunkapi.com/compare/sportradar): Sportradar sells licensed, live basketball feeds via sales contracts. DunkAPI is historical data from public sources, self-serve, with 500 free credits a month. (checked 2026-10-07)
- [DunkAPI vs SportsDataIO](https://dunkapi.com/compare/sportsdataio-nba): SportsDataIO is a real-time, multi-sport vendor with enterprise plans. DunkAPI is basketball only, historical, with shot locations and self-serve pricing. (checked 2026-10-09)
- [Historical NBA player prop odds APIs, compared](https://dunkapi.com/compare/nba-player-prop-odds-api): Six APIs that serve NBA player props, by how far back the history goes, whether they return results, books, price and MCP support. Checked against each provider's site. (checked 2026-10-21)

### 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): Snapshots of each sportsbook's line before tip-off
- [get_ratings](https://dunkapi.com/docs/get-ratings): Our team Elo ratings, ranked
- [get_player_props](https://dunkapi.com/docs/get-player-props): Player prop lines by sportsbook: the closing line (one pre-game capture per line before October 2026)
- [get_prop_history](https://dunkapi.com/docs/get-prop-history): A player's prop lines against the result, game by game

### 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, with opening and closing lines from 6 to 8 books since July 2020, 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.

### Code guides

Python, JavaScript and cURL for common questions, each run against the live API (code verified 2026-10-21). Index: https://dunkapi.com/guides

- [How do I get NBA play-by-play data in Python?](https://dunkapi.com/guides/nba-play-by-play-python): One call returns a game's plays in order, with shot location, zone, expected points and win probability on each. This pulls the shots from one game into pandas. Tool: get_plays.
- [How do I build an NBA shot chart by zone in Python?](https://dunkapi.com/guides/nba-shot-chart-by-zone-python): A player's shot profile by zone, with attempts, makes and expected points per shot, for one season. Set include_shots to true to get every shot's x and y as well. Tool: get_shot_chart.
- [How do I backtest NBA closing lines in Python?](https://dunkapi.com/guides/backtest-nba-closing-lines-python): A day of games with every sportsbook's opening and closing moneyline, spread and total, next to whether the home side covered and the total went over. Tool: get_odds.
- [How do I compare NBA team pace and efficiency in pandas?](https://dunkapi.com/guides/nba-pace-and-efficiency-by-team-pandas): Pace, offensive and defensive rating, net rating and the four factors for all 30 teams in one call, ready to sort and plot. Tool: get_team_stats.
- [How do I get an NBA player's game log and a rolling average?](https://dunkapi.com/guides/nba-player-game-log-rolling-average): Every game a player appeared in, with minutes, points, shooting and plus-minus, loaded into pandas for a 10-game rolling average. Tool: get_player_games.
- [How do I compare NBA player prop lines across sportsbooks?](https://dunkapi.com/guides/nba-player-prop-lines-by-sportsbook-python): Every sportsbook's points line and over and under price for each player in a game, to find where books post different lines and who pays best on each side. Tool: get_player_props.
- [How do I get NBA line movement before tip-off in Python?](https://dunkapi.com/guides/nba-line-movement-before-tipoff-python): Snapshots of each sportsbook's moneyline, spread and total from the day before a game to tip-off, with the final score, to see when the line moved and if it was right. Tool: get_line_movement.
- [How do I get today's NBA schedule and scores in Python?](https://dunkapi.com/guides/nba-scores-and-schedule-python): Every NBA game on a date with score, venue and attendance. October 10 had seven preseason games that averaged 227.7 total points. Tool: list_games.
- [How do I get NBA standings in Python?](https://dunkapi.com/guides/nba-standings-python): NBA standings for 2025-26 computed from every final game: record, scoring margin and last 10 by conference. Oklahoma City finished 64-18. Tool: get_standings.
- [How do I get the NBA injury report in Python?](https://dunkapi.com/guides/nba-injury-report-python): The NBA injury report as of October 11: 129 listed players, 19 of them out, with injury type, status and expected return date. Tool: get_injuries.
- [How often does an NBA player go over his points line?](https://dunkapi.com/guides/nba-points-prop-history-python): One row per game with a player's closing points line, the price, what he scored and whether he went over. Shai Gilgeous-Alexander went over in 27 of 67. Tool: get_prop_history.
- [How often does an NBA shooter go over his threes line?](https://dunkapi.com/guides/nba-threes-prop-history-python): One row per game with a player's threes made line, the price, how many he hit and whether he went over. Stephen Curry went over in 17 of 42 last season. Tool: get_prop_history.
- [How often does an NBA big man go over his rebounds line?](https://dunkapi.com/guides/nba-rebounds-prop-history-python): One row per game with a player's rebounds line, the price, how many he grabbed and whether he went over. Karl-Anthony Towns went over in 40 of 73 last season. Tool: get_prop_history.
- [How often does an NBA playmaker go over his assists line?](https://dunkapi.com/guides/nba-assists-prop-history-python): One row per game with a player's assists line, the price, how many he passed for and whether he went over. Nikola Jokic went over in 40 of 64 last season. Tool: get_prop_history.
- [How often does an NBA star go over his points + rebounds + assists line?](https://dunkapi.com/guides/nba-pra-prop-history-python): One row per game with a player's points + rebounds + assists line, the price, his total and whether he went over. Luka Doncic split 32 overs and 32 unders last season. Tool: get_prop_history.
- [How often does a college basketball player go over his points line?](https://dunkapi.com/guides/college-basketball-points-prop-history-python): One row per game with a college player's points line, the price, what he scored and whether he went over. Purdue's Braden Smith went under in 22 of 35 last season. Tool: get_prop_history.
- [How often does a college basketball player go over his rebounds line?](https://dunkapi.com/guides/college-basketball-rebounds-prop-history-python): One row per game with a college player's rebounds line, the price, how many he grabbed and whether he went over. Duke's Cameron Boozer went over in 17 of 33 last season. Tool: get_prop_history.
- [How often does an NBA big man go over his blocks line?](https://dunkapi.com/guides/nba-blocks-prop-history-python): One row per game with a player's blocks line, the price, how many he blocked and whether he went over. Victor Wembanyama went over in 30 of 65. Tool: get_prop_history.
- [How often does an NBA guard go over his steals line?](https://dunkapi.com/guides/nba-steals-prop-history-python): One row per game with a player's steals line, the price, how many he took and whether he went over. Dyson Daniels went over in 37 of 74. Tool: get_prop_history.

### Claude skills

16 free Claude skills (SKILL.md files) wired to these tools: https://github.com/noahowsh/dunkapi-mcp/tree/main/skills. Overview: https://dunkapi.com/skills

- game-lookup (Data Exploration): Find games and box scores by date, team or season; tonight's schedule.
- team-analysis (Data Exploration): Standings, Elo, pace, net rating and the four factors for any team.
- player-scouting (Data Exploration): Player profiles, per-36 comparisons, shooting efficiency and leaderboards.
- odds-explorer (Data Exploration): Best price, vig and line movement across sportsbooks for any game.
- game-preview (Data Exploration): Pre-game page: Elo, efficiency, rest, injuries, market line and projection.
- shot-zone-analysis (Basketball Analytics): Shot zones and expected points: shot quality vs shot making, defence by zone.
- player-form (Basketball Analytics): Rolling game logs, minutes trends and shrunk projections for any player.
- feature-engineering (Methodology): Leak-free rolling, rest and Elo features for game and prop models.
- walk-forward-validation (Methodology): Chronological validation with market benchmarks and significance tests.
- probability-calibration (Methodology): Reliability tables, Platt scaling and margin-to-probability conversion.
- odds-analysis (Methodology): Implied probability, vig and four devigging methods with live examples.
- edge-detection (Betting): Expected value, fractional Kelly and closing line value, framed as estimates.
- backtesting (Betting): Replay a betting rule on historical closing lines with realistic settlement.
- prop-modeling (Betting): Points, rebounds and assists props: minutes, rates, distributions, history.
- dispatch (Workflow): Routes a basketball request to the right two or three skills.
- dunkapi-tool (Infrastructure): Router for all 18 DunkAPI tools: credits, REST, MCP, response envelope.