# 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

## 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`
- 500 free credits on signup, 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). Fight ids like 157774 (an ESPN match id; list a tournament's matches with get_tournament).

## 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 and what the score says -> 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.
- [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.
- [Pricing](https://acesapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://acesapi.com/signup): 500 free credits, no card.

### 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 ESPN lists 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): ESPN's weekly ATP and WTA ranking lists since 2007, top 100 to 150 a week: rank, previous rank and points, and each player's history.

### Compared with the alternatives

- [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 the same results checked, with those added.

### 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 and what the score says
- [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 ESPN publishes it: 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 ESPN ids.