---
name: tennisdatabaseapi
description: Tennis results, scores, rounds, surfaces, bookmaker prices, games and sets lines, price movement, match statistics and point by point for every professional singles match, men and women, from the Tennis Database API. Use when a question needs tennis match facts, a player's record, a head to head, a tournament's results or historical tennis odds.
---

# Tennis Database API

Every professional singles match, men from 1877 and women from 1968 (2,335,214 matches), with scores, closing prices, lines, statistics and point by point. JSON over HTTPS, GET only, operated by DeveloperData.net.

## When to use it

- Results and scores on a day, a player's matches and record by surface, a head to head, every match of a tournament season.
- Historical prices: closing odds, each bookmaker's price, games and sets lines, correct score prices and price movement.
- Match statistics (serve, return, points, by set) and point by point.
- Not for: predictions or tips (it holds facts only), doubles, live point-by-point scores, player photographs.

## Access

- A free key: sign in at https://tennisdatabaseapi.com/login (Google). It reads matches from yesterday to two days ahead, 50 calls a day, with prices, statistics and point by point on the matches already played.
- Paid plans (Live, Archive, Complete) add prices, statistics and history: https://tennisdatabaseapi.com/pricing
- Send the key as `Authorization: Bearer <key>` or `X-API-Key: <key>`. A key in the address is refused.
- Base address: https://api.tennisdatabaseapi.com/v1. Every id is our own and stable (`mt_`, `pl_`, `tn_` and 8 characters). Times are UTC. Prices are decimal, turned to the winner and the loser.

## The calls

- Matches on a day, `GET /v1/matches`: Matches on a day, with scores and closing prices. Every plan. Takes `date`, `tour`, `tier`, `tournament`, `page`, `per_page` (up to 200), `cursor`.
- Yesterday's results, `GET /v1/results/yesterday`: Yesterday's results. Every plan. Takes `tour`, `tier`, `page`, `per_page` (up to 200), `cursor`.
- Fixtures, `GET /v1/fixtures`: The matches set to be played, from those under way to two days ahead: start time, round, both players with ranking and Elo, the chance Elo gives each, and the price before play where the market has one. Every plan. Takes `tour`, `tier`, `tournament`, `page`, `per_page` (up to 200), `cursor`.
- Match, `GET /v1/matches/{id}`: One match: score, every bookmaker's price with its opening price, the games and sets lines, correct score prices, price movement and the full statistics. Every plan.
- Match statistics, `GET /v1/matches/{id}/statistics`: Serve and return figures for each player, for the match and each set, with the service games held and broken. Every plan.
- Point by point, `GET /v1/matches/{id}/points`: Every game and point of a match: who served, who won it, breaks, break points and set points. Every plan.
- Match prices, `GET /v1/matches/{id}/odds`: Every bookmaker's closing and opening price for a match, and every market: games, sets, handicaps and correct score. Every plan.
- Price moves, `GET /v1/matches/{id}/moves`: Each change of each bookmaker's match price before the start, timed. Every plan.
- Find players, `GET /v1/players`: Find players by name. Every plan. Takes `search` (required), `tour`, `page`, `per_page` (up to 200), `cursor`.
- Player profile, `GET /v1/players/{id}`: A player, with their win and loss record by surface. Every plan.
- Player matches, `GET /v1/players/{id}/matches`: A player's matches, newest first. Paid plans. Takes `season`, `page`, `per_page` (up to 200), `cursor`.
- Player seasons, `GET /v1/players/{id}/seasons`: A player's won and lost by season, and by surface within each season. Every plan.
- Player statistics, `GET /v1/players/{id}/statistics`: A player's serve and return figures over every match held with statistics, and their opponents' against them. Paid plans. Takes `season`, `surface`.
- Player titles, `GET /v1/players/{id}/titles`: Every final a player won and lost, by level. Every plan. Takes `tier`.
- Ranking history, `GET /v1/players/{id}/rankings`: A player's singles ranking and points, week by week, newest first. Paid plans. Takes `from`, `to`, `page`, `per_page` (up to 200), `cursor`.
- Elo history, `GET /v1/players/{id}/elo`: A player's Elo rating now, and before every match, overall and on the match's surface, with the chance it gave them. Paid plans. Takes `page`, `per_page` (up to 200), `cursor`.
- Head to head, `GET /v1/h2h/{a}/{b}`: Head to head between two players. Paid plans. Takes `page`, `per_page` (up to 200), `cursor`.
- Rankings, `GET /v1/rankings`: The current singles rankings, with each player's highest ranking and Elo. Every plan. Takes `tour`, `page`, `per_page` (up to 200), `cursor`.
- Rankings on a date, `GET /v1/rankings/{date}`: The ranking list of the week of a date: singles, men from 1973 and women from 2003; women's doubles with list=doubles. Paid plans. Takes `tour`, `list`, `page`, `per_page` (up to 200), `cursor`.
- Elo ratings, `GET /v1/elo`: The players our Elo rates highest, overall or on one surface, among those with a match in the last year. Every plan. Takes `tour`, `surface`, `page`, `per_page` (up to 200), `cursor`.
- Find tournaments, `GET /v1/tournaments`: Tournaments, by name, tour or tier. Every plan. Takes `search`, `tour`, `tier`, `page`, `per_page` (up to 200), `cursor`.
- Tournament, `GET /v1/tournaments/{id}`: A tournament and every season held. Every plan.
- Champions, `GET /v1/tournaments/{id}/champions`: The champion and runner-up of every season of a tournament, and who has won it most. Every plan.
- Tournament season, `GET /v1/tournaments/{id}/{season}`: Every match of one season of a tournament. Paid plans. Takes `page`, `per_page` (up to 200), `cursor`.
- Season draw, `GET /v1/tournaments/{id}/{season}/draw`: One season of a tournament round by round, from qualifying to the final, with seeds and entry. Paid plans.
- This week, `GET /v1/calendar`: The events being played in the week of a date, every level, with surface, city and matches held so far. Every plan. Takes `date`, `tour`, `tier`, `page`, `per_page` (up to 200), `cursor`.
- Doubles on a day, `GET /v1/doubles`: Every doubles match of one day, with both pairs, seeds, the score and closing prices. Paid plans. Takes `date`, `tour`, `tier`, `page`, `per_page` (up to 200), `cursor`.
- Doubles pair, `GET /v1/doubles/pairs/{id}`: A doubles pair, their record together and every match they played, newest first. Paid plans. Takes `page`, `per_page` (up to 200), `cursor`.
- Market accuracy, `GET /v1/markets/accuracy`: How often the closing favourite won: by price, level, surface and season, and over the last 30 days. Every plan.
- Biggest upsets, `GET /v1/markets/upsets`: The longest closing prices that won at Grand Slam and tour level. Every plan.
- Bookmaker margins, `GET /v1/markets/margins`: Each bookmaker's average margin on its closing prices since the start of last year. Paid plans.
- All-time leaders, `GET /v1/records`: The most matches won and the most titles, all time. Every plan. Takes `tour`.
- Season leaders, `GET /v1/records/{season}`: The most matches won and the most titles in one season. Every plan. Takes `tour`.
- Search, `GET /v1/search`: Players and tournaments together, by name. Every plan. Takes `q` (required).
- Coverage, `GET /v1/meta/coverage`: What the database holds, season by season, counted from the data. Every plan.
- Bulk files, `GET /v1/exports`: Every season as compressed CSV files: matches, prices, price moves, statistics and point by point, with rows, size and checksum, rebuilt nightly. Paid plans.
- Bulk file, `GET /v1/exports/{season}/{dataset}`: One season's file of one dataset (matches, prices, moves, statistics or points), gzip-compressed CSV. Paid plans.
- Usage, `GET /v1/usage`: Your plan, calls used and limits (does not count). Every plan.

### Examples

```
curl -H "Authorization: Bearer $TDA_KEY" "https://api.tennisdatabaseapi.com/v1/results/yesterday?tour=men&tier=tour"
curl -H "Authorization: Bearer $TDA_KEY" "https://api.tennisdatabaseapi.com/v1/players?search=alcaraz"
curl -H "Authorization: Bearer $TDA_KEY" "https://api.tennisdatabaseapi.com/v1/matches/{id}"
```

The first player it finds (trimmed):

```json
{
    "data": {
        "id": "pl_k4tz1p7a",
        "name": "Lopez Alcaraz E.",
        "full_name": "Lopez Alcaraz Esther",
        "country": "Spain",
        "tour": "women",
        "ranking": {
            "current": 1033,
            "highest": 1023,
            "as_of": "2026-10-01"
        }
    }
}
```

A match (trimmed; the full answer adds `odds`, `stats`, `point_by_point` and more):

```json
{
    "data": {
        "id": "mt_qbktcd7n",
        "date": "2025-09-07",
        "tournament": {
            "id": "tn_1d50xrzv",
            "name": "US Open",
            "event_known": true,
            "tier": "slam",
            "season": 2025,
            "surface": "hard"
        },
        "round": "final",
        "winner": {
            "id": "pl_s0fxc3xg",
            "name": "Alcaraz C.",
            "country": "Spain"
        },
        "loser": {
            "id": "pl_vsvgrrag",
            "name": "Sinner J.",
            "country": "Italy"
        },
        "score": "6-2 3-6 6-1 6-4",
        "status": "completed"
    }
}
```

Every answer is `{"data": ..., "meta": {...}}`. A field the plan does not include is `null`, and `meta.held_back` names it.

## MCP server

- Address: https://api.tennisdatabaseapi.com/mcp (Streamable HTTP). Send the key as a Bearer token. A tool call counts like the API call it matches.
- Tools: `matches_on_day`, `results_yesterday`, `fixtures`, `match_detail`, `match_statistics`, `match_points`, `match_prices`, `price_moves`, `find_player`, `player_profile`, `player_matches`, `player_seasons`, `player_statistics`, `player_titles`, `ranking_history`, `elo_history`, `head_to_head`, `rankings`, `rankings_on_date`, `elo_ratings`, `find_tournament`, `tournament_seasons`, `tournament_champions`, `tournament_results`, `season_draw`, `events_this_week`, `doubles_on_day`, `doubles_pair`, `market_accuracy`, `biggest_upsets`, `bookmaker_margins`, `all_time_leaders`, `season_leaders`, `search`.

## Limits

- Free key: 10 calls a minute, 50 a day, no limit a month; matches from yesterday to two days ahead; prices and statistics on matches already played (held back before play).
- Live: 120 calls a minute, no limit a day, 300,000 a month; matches from the last 45 days to two days ahead; prices and statistics included.
- Archive: 120 calls a minute, no limit a day, 300,000 a month; matches from every season to yesterday; prices and statistics included.
- Complete: 300 calls a minute, no limit a day, 1,000,000 a month; matches from every season to two days ahead; prices and statistics included.
- Lists are paged: 50 a page by default, at most 200.
- `GET /v1/usage` gives the plan, calls used and limits, and never counts.

## Errors

`{"error": {"code", "message", "docs"}}`, with `plan` and `upgrade` on a 403.

- 400 `bad_request`, 401 `unauthorized`, 403 `upgrade_required`, 404 `not_found`, 422 `unknown_parameter`, 429 `rate_limited` or `quota_exceeded` (wait for `Retry-After`), 500 `server_error`.

## A typical workflow

1. Find the player or tournament first: `GET /v1/players?search=` or `GET /v1/tournaments?search=`, and keep its id.
2. List matches: `GET /v1/players/{id}/matches?season=`, `GET /v1/h2h/{a}/{b}` or `GET /v1/tournaments/{id}/{season}`; for a day, `GET /v1/matches?date=`.
3. Open one match with `GET /v1/matches/{id}` for prices, lines, movement, statistics and point by point.
4. For one part of a match only, ask for it: `/statistics`, `/points`, `/odds` or `/moves` after `GET /v1/matches/{id}`.
5. For a player over time: `GET /v1/players/{id}/seasons`, `/titles`, `/rankings` and `/elo`; for the list on any week, `GET /v1/rankings/{date}`.
6. On a 403, tell the user which plan reads it (the error names it). On a 429, wait for `Retry-After`.

Docs: https://tennisdatabaseapi.com/documentation. Manual for agents: https://tennisdatabaseapi.com/documentation/manual.md. Support: https://tennisdatabaseapi.com/support
