# AcesAPI

> The tennis data API. 13 tennis data tools for AI agents. REST API + MCP server.

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

## Quick Start

- API base URL: https://mcp.acesapi.com
- Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`
- MCP server: `https://mcp.acesapi.com/mcp?key=YOUR_API_KEY`
- Python client: `pip install acesapi` (https://pypi.org/project/acesapi/). Reads ACESAPI_API_KEY.
- 500 free credits every month, no credit card required
- REST API responses include `X-Credits-Used` and `X-Credits-Remaining` headers
- Seasons: 4-digit year (tournaments are grouped by calendar year). Match ids like 157774 (a match id; list a tournament's matches with get_tournament or get_matches).

## 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.
- AcesAPI is independent, not an official league partner, and grants no league rights.
- Full answers: https://acesapi.com/docs/timing-and-rights

## Which Tool Should I Use?

### Static reference
- A season's tournaments with dates, surface, status and champion -> list_tournaments (1 cr)
- Find players by name or country -> search_players (1 cr)

### Basic lookup
- A tournament's draw and results, round by round, with every set -> get_tournament (2 cr)
- Match results by day, tournament or season, with set and tiebreak scores -> get_matches (2 cr)
- Upcoming and in-progress matches for the next days -> get_schedule (2 cr)
- One match: sets, tiebreak points, seeds, ratings, what the score says and its sportsbook lines -> get_match (2 cr)
- Weekly ranking lists since 2007, or one player's ranking history -> get_rankings (2 cr)
- Our Elo ratings, overall or by surface -> get_ratings (2 cr)

### Stats + aggregation
- Profile, ranking, ratings, career record, titles and recent matches -> get_player (5 cr)
- A player's matches with scores and ratings, filtered by season, surface or opponent -> get_player_matches (5 cr)

### Multi-table
- Two players' meetings, wins by surface and in finals -> get_head_to_head (3 cr)
- A player's record by surface: sets, games, tiebreaks, deciding sets -> get_surface_splits (3 cr)
- A player's season statistics from scores, by round and opponent rank -> get_player_stats (3 cr)

## Intents

- "Which tournaments are on grass this year, and who won them?" -> list_tournaments
- "What is Jannik Sinner's player id?" -> search_players
- "Show me the Wimbledon 2025 draw with every score" -> get_tournament
- "Every final played this season" -> get_matches
- "Who plays in the next three days?" -> get_schedule
- "How did the Wimbledon final go, set by set?" -> get_match
- "Who is in the top 10 this week?" -> get_rankings
- "Who is the best clay-court player right now?" -> get_ratings
- "Sinner vs Alcaraz head to head, by surface" -> get_head_to_head
- "How does Alcaraz do on grass compared with clay?" -> get_surface_splits
- "How many tiebreaks did Sinner win in 2025?" -> get_player_stats
- "Tell me everything about Jannik Sinner" -> get_player
- "Every clay match Alcaraz has played" -> get_player_matches

## Pages

- [Docs](https://acesapi.com/docs): every endpoint, with parameters and a live example response.
- [Data changelog](https://acesapi.com/changelog): when each dataset was last refreshed and what it runs through, read from the database.
- [Status](https://acesapi.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://acesapi.com/docs/atlas): what exists, which endpoints expose it, and where coverage is partial.
- [Players](https://acesapi.com/players): a page per player with the career record, record by surface, titles, ranking, rating and recent matches.
- [Data timing and rights](https://acesapi.com/docs/timing-and-rights): what timestamps mean, when each dataset updates, whether lines are pre-game, and what the terms allow.
- [Pricing](https://acesapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://acesapi.com/signup): 500 free credits every month, no card.

### Live odds

- [Upcoming tennis odds](https://acesapi.com/odds): Moneylines for ATP and WTA singles matches with sportsbook lines in the next two days, one row per sportsbook, refreshed hourly. Lines exist only for Grand Slam, ATP Masters and WTA 1000 matches.

### Other leagues

- [The WTA tennis data API](https://acesapi.com/wta): WTA tennis data since 2007: singles matches with set and tiebreak scores, draws, players, weekly rankings, head to head and our Elo by surface. REST and MCP. MCP: https://mcp.acesapi.com/mcp/wta

### Datasets

- [Tennis results data](https://acesapi.com/data/tennis-results-api): Every ATP and WTA singles match since 2007, with every set's games and tiebreak points, seeds, rounds and draws. REST or MCP.
- [Tennis rankings history](https://acesapi.com/data/tennis-rankings-history): Weekly ATP and WTA ranking lists since 2007, top 100 to 150 a week: rank, previous rank and points, and each player's history.
- [Tennis odds history for the Grand Slams and Masters](https://acesapi.com/data/tennis-odds-history): Sportsbook moneylines for Grand Slam singles matches since mid-2020 and ATP Masters / WTA 1000 since August 2024, opening and closing, by book. REST or MCP.

### Compared with the alternatives

- [The tennis API: ATP and WTA data sources and AcesAPI](https://acesapi.com/compare/tennis-api): ESPN's tennis JSON, the Match Charting Project, ATP-site scrapers and API Tennis cover different ground. Where each fits, and how AcesAPI differs. (checked 2026-10-14)
- [tennis_atp on GitHub returns 404: where Jeff Sackmann's ATP and WTA data is now](https://acesapi.com/compare/jeff-sackmann-tennis-data): Jeff Sackmann's tennis_atp and tennis_wta repos returned 404 on 2026-10-14. Where the ATP and WTA match CSVs are now, and how AcesAPI's results compare. (checked 2026-10-14)
- [AcesAPI vs reading ESPN's tennis feed](https://acesapi.com/compare/espn-tennis-api): ESPN's tennis JSON has results but no surfaces, no ratings and no head to head. AcesAPI serves results with those added. (checked 2026-10-08)
- [AcesAPI vs API Tennis](https://acesapi.com/compare/api-tennis): API Tennis sells live scores, fixtures and odds from $40 a month. AcesAPI is historical ATP and WTA results since 2007 with surfaces and Elo by surface, and moneylines for the biggest events. (checked 2026-10-09)
- [AcesAPI vs SportsDataIO](https://acesapi.com/compare/sportsdataio-tennis): SportsDataIO sells real-time data in 75+ sports via sales. AcesAPI is historical ATP and WTA results with surfaces and ratings, self-serve, 500 free credits a month. (checked 2026-10-09)
- [AcesAPI vs Sportradar](https://acesapi.com/compare/sportradar-tennis): Sportradar sells licensed, live tennis feeds by contract. AcesAPI is historical ATP and WTA results, self-serve, 500 free credits a month. (checked 2026-10-09)

### Endpoint pages

- [list_tournaments](https://acesapi.com/docs/list-tournaments): A season's tournaments with dates, surface, status and champion
- [get_tournament](https://acesapi.com/docs/get-tournament): A tournament's draw and results, round by round, with every set
- [get_matches](https://acesapi.com/docs/get-matches): Match results by day, tournament or season, with set and tiebreak scores
- [get_schedule](https://acesapi.com/docs/get-schedule): Upcoming and in-progress matches for the next days
- [get_match](https://acesapi.com/docs/get-match): One match: sets, tiebreak points, seeds, ratings, what the score says and its sportsbook lines
- [search_players](https://acesapi.com/docs/search-players): Find players by name or country
- [get_player](https://acesapi.com/docs/get-player): Profile, ranking, ratings, career record, titles and recent matches
- [get_player_matches](https://acesapi.com/docs/get-player-matches): A player's matches with scores and ratings, filtered by season, surface or opponent
- [get_head_to_head](https://acesapi.com/docs/get-head-to-head): Two players' meetings, wins by surface and in finals
- [get_surface_splits](https://acesapi.com/docs/get-surface-splits): A player's record by surface: sets, games, tiebreaks, deciding sets
- [get_player_stats](https://acesapi.com/docs/get-player-stats): A player's season statistics from scores, by round and opponent rank
- [get_rankings](https://acesapi.com/docs/get-rankings): Weekly ranking lists since 2007, or one player's ranking history
- [get_ratings](https://acesapi.com/docs/get-ratings): Our Elo ratings, overall or by surface

### Metric definitions

- [Tiebreak](https://acesapi.com/glossary/tiebreak): The game that decides a set at six games all: first to seven points, two clear.
- [Set and game score](https://acesapi.com/glossary/set-score): A match's result written set by set, games for the winner first: 6-4 3-6 7-6(5).
- [Deciding set](https://acesapi.com/glossary/deciding-set): The last possible set of a match: the third in best of three, the fifth in best of five.
- [Share of games won](https://acesapi.com/glossary/games-won-pct): Games a player won divided by all games played in their matches: a finer measure of dominance than wins.
- [Elo rating](https://acesapi.com/glossary/elo): Our rating for every player, moved after each completed match by how surprising the result was.
- [Surface Elo](https://acesapi.com/glossary/surface-elo): The same Elo, counted only from matches on one surface: a clay rating, a grass rating and a hard-court rating per player.
- [Court surface](https://acesapi.com/glossary/surface): What a tournament is played on: hard, clay, grass or (in older years) carpet, and whether it is indoors.
- [Head to head](https://acesapi.com/glossary/head-to-head): Two players' record against each other: every meeting, who won, and on what surface.
- [Walkover and retirement](https://acesapi.com/glossary/walkover-retirement): A walkover is a match never started (one player withdrew); a retirement is a match stopped after it began.
- [Ranking](https://acesapi.com/glossary/ranking): The tours' weekly list of players by ranking points, as published: the top 100 to 150.

### By what you are building

- [Bettors and modellers](https://acesapi.com/for/bettors): Every ATP and WTA singles result since 2007 with our Elo by surface before and after each match, head to head and records by surface.
- [Analysts and researchers](https://acesapi.com/for/analysts): ATP and WTA singles since 2007: draws round by round, every set's games and tiebreak points, rankings by week, all in rows.
- [Developers and AI builders](https://acesapi.com/for/developers): REST and MCP over the same data: tournaments, draws, matches, players, rankings and ratings, with stable ids.

### Code guides

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

- [How do I get tennis Elo ratings by surface in Python?](https://acesapi.com/guides/tennis-elo-by-surface-python): Our Elo rating for every active player, overall or on one surface, with the number of matches behind each rating. Tool: get_ratings.
- [How do I compare a tennis player's results on clay, grass and hard court?](https://acesapi.com/guides/tennis-surface-splits-python): A player's career record split by surface: wins, losses, sets, games, tiebreaks and deciding sets, with the surface Elo ratings alongside. Tool: get_surface_splits.
- [How do I get a tennis head-to-head record in Python?](https://acesapi.com/guides/tennis-head-to-head-python): Every meeting between two players with the score and sets, plus wins by surface and in finals. Tool: get_head_to_head.
- [How do I get set-by-set tennis scores for a tournament in Python?](https://acesapi.com/guides/tennis-set-by-set-match-scores-python): Every match of a tournament with seeds, winner and each set's games and tiebreak, flattened into one row per set. Tool: get_matches.
- [How do I get a tennis player's ranking history in Python?](https://acesapi.com/guides/tennis-ranking-history-python): A player's weekly ranking and points, newest first, for a season or for their career. Tool: get_rankings.
- [How do I compare ATP closing odds with the result and Elo in Python?](https://acesapi.com/guides/atp-closing-odds-vs-result-and-elo-python): One call returns a match's score, both players' Elo before it and every sportsbook's open and close price. This removes the margin and sets the market beside Elo. Tool: get_match.
- [How do I get WTA odds from open to close by sportsbook in Python?](https://acesapi.com/guides/wta-odds-opening-to-closing-python): Every sportsbook's opening and closing price for a WTA match with the margin removed, to see which way the market moved and how much each book charged. Tool: get_match.
- [How do I get today's ATP tennis schedule in Python?](https://acesapi.com/guides/atp-tennis-schedule-python): ATP matches in the next days with tournament, round, court and players. The call returned 19 Rolex Shanghai Masters matches from October 11 to 13. Tool: get_schedule.
- [How do I get a tennis tournament draw and results in Python?](https://acesapi.com/guides/tennis-tournament-draw-results-python): A tournament's whole draw by round, with scores by set. The China Open had 31 main-draw matches and Novak Djokovic won the final. Tool: get_tournament.
- [How do I get a tennis player's season stats in Python?](https://acesapi.com/guides/tennis-player-season-stats-python): A player's season record counted from scores: wins, sets, tiebreaks, and results by round and opponent ranking. Jannik Sinner was 44-3 in 2026. Tool: get_player_stats.

### Claude skills

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

- match-lookup (Data Exploration): Results, draws, schedules and set scores for ATP and WTA matches.
- player-scouting (Data Exploration): Player profiles, surface fit, opposition quality and form.
- odds-explorer (Data Exploration): Moneylines by book, margins and open-to-close moves on Slams and Masters.
- match-preview (Data Exploration): One-page pre-match brief: ratings, form, head to head, route and price.
- surface-elo (Tennis Analytics): Elo by surface, win probability from rating gaps, and blending.
- head-to-head-analysis (Tennis Analytics): Rivalry records by surface and in finals, weighted for small samples.
- ranking-history (Tennis Analytics): Weekly ranking lists, points movement and rank versus Elo.
- set-score-modeling (Tennis Analytics): Set scores, total games and tiebreak rates without serve data.
- feature-engineering (Methodology): Leak-free pre-match features: Elo, form, rest, load, symmetric rows.
- walk-forward-validation (Methodology): Season-by-season validation, baselines and significance tests.
- probability-calibration (Methodology): Reliability tables, Platt scaling and calibration against the close.
- odds-analysis (Methodology): Implied probability, devigging (multiplicative, power, Shin) and fair odds.
- edge-detection (Betting): Model versus no-vig close: EV, closing line value and fractional Kelly.
- backtesting (Betting): Walk-forward tests against Slam and Masters closing lines with bootstrap.
- acesapi-tool (Infrastructure): Router for all 13 tools: credits, response envelope, REST and MCP setup.
- dispatch (Infrastructure): Routes a tennis request to the right 2 or 3 skills.