# Tennis Database API: manual

Generated from the API's own endpoint list and counted from the database on 2026-11-18 UTC. Base address: https://api.tennisdatabaseapi.com/v1

## 1. Facts

- 2,344,876 tennis matches, men and women, from 1877 to 2026-11-18.
- 103,673 players and 16,440 tournaments, from Grand Slams and tour events down to challengers, ITF and other professional events.
- 939,102 matches with closing prices; 461,180 with games and sets lines, handicaps and correct score prices; 61,320,228 price moves recorded.
- 291,742 matches with full match statistics (serve, return, points, by set).
- JSON over HTTPS, GET only. Every id is our own and stable. Times are UTC.

## 2. Before anything else

- The API holds facts only: results, scores, prices as offered, statistics. It makes no predictions and gives no tips.
- Not included: player biographies and photographs.
- Many lower-level men's ITF matches are recorded without their event. They keep their date, players, score, season and, where known, round and surface, and sit under one tournament per season named "Men's ITF, event not recorded" with `event_known: false`. Every other match carries its real event.
- Prices are decimal odds. In a match, prices and statistics are turned to the winner and the loser, not to a home and away side.
- Send your key in the `Authorization: Bearer <key>` header or in `X-API-Key`. A key in the address is refused.
- Every answer has the same envelope: `{"data": ..., "meta": {...}}` on success, `{"error": {"code", "message", "docs"}}` on failure.
- A field a plan does not include is still present, as null, so code written on one plan keeps working after an upgrade. The answer says what was held back in `meta.held_back`.

## 3. Plans

| Plan | Per minute | Per day | Per month | Match dates | Prices and markets | Statistics |
|---|---|---|---|---|---|---|
| Free key | 10 | 50 | no limit | yesterday to today and the next 2 days | yes on matches already played | yes on matches already played |
| Live | 120 | no limit | 300,000 | 45 days ago to today and the next 2 days | yes | yes |
| Archive | 120 | no limit | 300,000 | the first season held to yesterday | yes | yes |
| Complete | 300 | no limit | 1,000,000 | the first season held to today and the next 2 days | yes | yes |

`GET /v1/usage` tells a key its plan, calls used and limits, and does not count as a call. Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-Quota-Remaining`.

## 4. Coverage, counted from the data

| Season | Men's matches | with prices | with markets | with statistics | Women's matches | with prices | with markets | with statistics |
|---|---|---|---|---|---|---|---|---|
| 2026 | 64,458 | 44,924 | 29,632 | 28,431 | 46,105 | 34,022 | 20,496 | 22,944 |
| 2025 | 70,676 | 46,955 | 30,081 | 29,386 | 52,961 | 36,303 | 21,919 | 25,194 |
| 2024 | 59,948 | 39,966 | 30,481 | 21,617 | 45,209 | 32,775 | 22,796 | 16,807 |
| 2023 | 60,332 | 44,245 | 28,816 | 7,393 | 45,195 | 35,438 | 21,163 | 4,142 |
| 2022 | 55,845 | 41,772 | 26,840 | 6,745 | 41,433 | 33,082 | 19,637 | 3,814 |
| 2021 | 44,338 | 31,993 | 20,775 | 5,215 | 31,851 | 24,518 | 15,055 | 3,628 |
| 2020 | 21,899 | 16,289 | 11,753 | 1,351 | 15,652 | 12,231 | 7,887 | 1,046 |
| 2019 | 42,999 | 30,279 | 13,790 | 2,665 | 33,146 | 25,567 | 6,627 | 2,303 |
| 2018 | 56,078 | 32,341 | 10,100 | 2,675 | 36,634 | 24,664 | 5,766 | 2,410 |
| 2017 | 59,284 | 33,650 | 9,518 | 4,433 | 37,019 | 25,172 | 4,815 | 3,899 |
| 2016 | 61,504 | 34,138 | 10,255 | 3,978 | 37,048 | 25,448 | 5,052 | 506 |
| 2015 | 61,832 | 35,731 | 10,800 | 4,450 | 36,634 | 26,429 | 5,130 | 419 |
| 2014 | 60,650 | 28,562 | 10,916 | 4,253 | 35,535 | 23,005 | 5,567 | 277 |
| 2013 | 58,049 | 14,172 | 11,224 | 4,548 | 34,998 | 10,660 | 6,847 | 961 |
| 2012 | 55,374 | 11,278 | 10,541 | 4,604 | 32,984 | 7,189 | 6,490 | 728 |
| 2011 | 52,013 | 8,623 | 7,217 | 4,497 | 33,916 | 4,324 | 3,687 | 4 |
| 2010 | 49,359 | 8,359 | 4,248 | 4,500 | 31,502 | 3,656 | 2,576 | 0 |
| 2009 | 50,675 | 7,987 | 1,495 | 4,476 | 31,159 | 3,069 | 1,188 | 1 |
| 2008 | 53,447 | 8,229 | 0 | 4,162 | 30,634 | 2,940 | 0 | 0 |
| 2007 | 51,950 | 6,107 | 0 | 3,751 | 30,393 | 2,855 | 0 | 9 |
| 2006 | 48,986 | 3,426 | 0 | 2,950 | 29,483 | 2,488 | 0 | 13 |
| 2005 | 44,454 | 2,896 | 0 | 2,935 | 26,739 | 534 | 0 | 9 |
| 2004 | 40,359 | 2,806 | 0 | 2,906 | 24,959 | 0 | 0 | 10 |
| 2003 | 37,942 | 2,757 | 0 | 2,829 | 23,173 | 0 | 0 | 11 |
| 2002 | 34,388 | 2,714 | 0 | 2,859 | 23,656 | 0 | 0 | 0 |
| 2001 | 8,200 | 2,534 | 0 | 2,969 | 3,479 | 0 | 0 | 12 |
| 2000 | 7,452 | 0 | 0 | 2,914 | 4,132 | 0 | 0 | 0 |
| 1999 | 7,200 | 0 | 0 | 2,911 | 3,582 | 0 | 0 | 0 |
| 1998 | 7,208 | 0 | 0 | 3,185 | 3,424 | 0 | 0 | 0 |
| 1997 | 6,820 | 0 | 0 | 3,153 | 2,511 | 0 | 0 | 0 |
| 1996 | 3,550 | 0 | 0 | 3,315 | 2,169 | 0 | 0 | 0 |
| 1995 | 3,661 | 0 | 0 | 3,311 | 2,055 | 0 | 0 | 0 |
| 1994 | 3,735 | 0 | 0 | 3,369 | 2,205 | 0 | 0 | 0 |
| 1993 | 3,724 | 0 | 0 | 3,407 | 2,583 | 0 | 0 | 0 |
| 1992 | 3,552 | 0 | 0 | 3,238 | 2,327 | 0 | 0 | 0 |
| 1991 | 3,503 | 0 | 0 | 3,183 | 2,489 | 0 | 0 | 0 |
| 1990 | 3,533 | 0 | 0 | 31 | 2,558 | 0 | 0 | 0 |
| 1989 | 3,262 | 0 | 0 | 0 | 2,120 | 0 | 0 | 0 |
| 1988 | 3,359 | 0 | 0 | 0 | 2,187 | 0 | 0 | 0 |
| 1987 | 3,276 | 0 | 0 | 0 | 1,331 | 0 | 0 | 0 |
| 1986 | 3,001 | 0 | 0 | 0 | 639 | 0 | 0 | 0 |
| 1985 | 3,123 | 0 | 0 | 0 | 756 | 0 | 0 | 0 |
| 1984 | 2,950 | 0 | 0 | 0 | 875 | 0 | 0 | 0 |
| 1983 | 3,302 | 0 | 0 | 0 | 1,478 | 0 | 0 | 0 |
| 1982 | 3,831 | 0 | 0 | 0 | 608 | 0 | 0 | 0 |
| 1981 | 3,641 | 0 | 0 | 0 | 598 | 0 | 0 | 0 |
| 1980 | 3,840 | 0 | 0 | 0 | 368 | 0 | 0 | 0 |
| 1979 | 3,760 | 0 | 0 | 0 | 331 | 0 | 0 | 0 |
| 1978 | 3,635 | 0 | 0 | 0 | 425 | 0 | 0 | 0 |
| 1977 | 3,907 | 0 | 0 | 0 | 422 | 0 | 0 | 0 |
| 1976 | 3,585 | 0 | 0 | 0 | 253 | 0 | 0 | 0 |
| 1975 | 3,825 | 0 | 0 | 0 | 299 | 0 | 0 | 0 |
| 1974 | 3,696 | 0 | 0 | 0 | 382 | 0 | 0 | 0 |
| 1973 | 3,645 | 0 | 0 | 0 | 283 | 0 | 0 | 0 |
| 1972 | 2,835 | 0 | 0 | 0 | 305 | 0 | 0 | 0 |
| 1971 | 2,566 | 0 | 0 | 0 | 367 | 0 | 0 | 0 |
| 1970 | 2,429 | 0 | 0 | 0 | 263 | 0 | 0 | 0 |
| 1969 | 1,383 | 0 | 0 | 0 | 252 | 0 | 0 | 0 |
| 1968 | 778 | 0 | 0 | 0 | 314 | 0 | 0 | 0 |
| 1967 | 435 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1966 | 436 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1965 | 428 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1964 | 400 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1963 | 398 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1962 | 414 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1961 | 369 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1960 | 369 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1959 | 375 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1958 | 364 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1957 | 363 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1956 | 398 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1955 | 401 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1954 | 400 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1953 | 384 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1952 | 403 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1951 | 355 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1950 | 335 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1949 | 311 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1948 | 347 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1947 | 341 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1946 | 321 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1945 | 47 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1944 | 31 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1943 | 31 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1942 | 63 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1941 | 63 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1940 | 108 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1939 | 299 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1938 | 345 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1937 | 345 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1936 | 321 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1935 | 343 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1934 | 334 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1933 | 336 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1932 | 346 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1931 | 329 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1930 | 332 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1929 | 329 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1928 | 298 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1927 | 303 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1926 | 305 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1925 | 308 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1924 | 247 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1923 | 208 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1922 | 281 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1921 | 256 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1920 | 318 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1919 | 255 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1918 | 86 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1917 | 63 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1916 | 127 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1915 | 142 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1914 | 255 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1913 | 251 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1912 | 219 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1911 | 321 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1910 | 288 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1909 | 259 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1908 | 228 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1907 | 218 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1906 | 195 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1905 | 192 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1904 | 145 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1903 | 119 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1902 | 125 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1901 | 68 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1900 | 65 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1899 | 69 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1898 | 69 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1897 | 63 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1896 | 63 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1895 | 82 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1894 | 55 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1893 | 91 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1892 | 91 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1891 | 86 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1890 | 62 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1889 | 56 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1888 | 56 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1887 | 32 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1886 | 55 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1885 | 49 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1884 | 64 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1883 | 49 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1882 | 66 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1881 | 72 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1880 | 60 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1879 | 45 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1878 | 32 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 1877 | 21 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |

## 5. Endpoints

### Matches on a day: GET /v1/matches

Matches on a day, with scores and closing prices.

- Plans: every plan.
- `date`: YYYY-MM-DD, today or yesterday (default today)
- `tour`: men or women (men, women)
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)
- `tournament`: a tournament id
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/matches"
```

### Yesterday's results: GET /v1/results/yesterday

Yesterday's results.

- Plans: every plan.
- `tour`: men or women (men, women)
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/results/yesterday"
```

### 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.

- Plans: every plan.
- `tour`: men or women (men, women)
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)
- `tournament`: a tournament id
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/fixtures"
```

### Live scores: GET /v1/live

The singles matches in play now, read every 15 seconds: sets, games, the game in progress with who serves and its points, how long ago each was read, and those finished in the last 15 minutes.

- Plans: Live, Complete.
- `tour`: men or women (men, women)
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)
- `tournament`: a tournament id
- `status`: in play, or finished in the last 15 minutes (live, finished)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/live"
```

### Live match: GET /v1/live/{id}

One match in play: the live score and every game so far, point by point, with who served, breaks, break points and set points. After it leaves Live, its last score stays here 7 days (meta.in_live false).

- Plans: Live, Complete.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/live/{id}"
```

### 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.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/matches/{id}"
```

### 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.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/matches/{id}/statistics"
```

### 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.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/matches/{id}/points"
```

### 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.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/matches/{id}/odds"
```

### Price moves: GET /v1/matches/{id}/moves

Each change of each bookmaker's match price before the start, timed.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/matches/{id}/moves"
```

### Find players: GET /v1/players

Find players by name.

- Plans: every plan.
- `search` (required): at least 3 letters of a name
- `tour`: men or women (men, women)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players?search=sinner"
```

### Player profile: GET /v1/players/{id}

A player, with their win and loss record by surface.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players/{id}"
```

### Player matches: GET /v1/players/{id}/matches

A player's matches, newest first.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer
- `season`: one season, such as 2024
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players/{id}/matches"
```

### Player seasons: GET /v1/players/{id}/seasons

A player's won and lost by season, and by surface within each season.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players/{id}/seasons"
```

### 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.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer
- `season`: one season, such as 2024
- `surface`: one surface (hard takes indoor hard in) (hard, clay, grass, carpet)

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players/{id}/statistics"
```

### Player titles: GET /v1/players/{id}/titles

Every final a player won and lost, by level.

- Plans: every plan.
- `id` (in the path): an id from another answer
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players/{id}/titles"
```

### Ranking history: GET /v1/players/{id}/rankings

A player's singles ranking and points, week by week, newest first.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer
- `from`: the first week, YYYY-MM-DD
- `to`: the last week, YYYY-MM-DD
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players/{id}/rankings"
```

### 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.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/players/{id}/elo"
```

### Head to head: GET /v1/h2h/{a}/{b}

Head to head between two players.

- Plans: Live, Archive, Complete.
- `a` (in the path): an id from another answer
- `b` (in the path): an id from another answer
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/h2h/{a}/{b}"
```

### Rankings: GET /v1/rankings

The current singles rankings, with each player's highest ranking and Elo.

- Plans: every plan.
- `tour`: men or women (men, women)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/rankings"
```

### 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.

- Plans: Live, Archive, Complete.
- `date` (in the path): an id from another answer
- `tour`: men or women (men, women)
- `list`: singles (default) or doubles; doubles lists are held for women (singles, doubles)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/rankings/{date}"
```

### 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.

- Plans: every plan.
- `tour`: men or women (men, women)
- `surface`: all courts, or one surface (default all) (all, hard, clay, grass)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/elo"
```

### Find tournaments: GET /v1/tournaments

Tournaments, by name, tour or tier.

- Plans: every plan.
- `search`: part of the name
- `tour`: men or women (men, women)
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/tournaments?search=sinner"
```

### Tournament: GET /v1/tournaments/{id}

A tournament and every season held.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/tournaments/{id}"
```

### Champions: GET /v1/tournaments/{id}/champions

The champion and runner-up of every season of a tournament, and who has won it most.

- Plans: every plan.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/tournaments/{id}/champions"
```

### Tournament season: GET /v1/tournaments/{id}/{season}

Every match of one season of a tournament.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer
- `season` (in the path): a season, such as 2024
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/tournaments/{id}/{season}"
```

### 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.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer
- `season` (in the path): a season, such as 2024

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/tournaments/{id}/{season}/draw"
```

### 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.

- Plans: every plan.
- `date`: YYYY-MM-DD, a day in the week (default today)
- `tour`: men or women (men, women)
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/calendar"
```

### Doubles on a day: GET /v1/doubles

Every doubles match of one day, with both pairs, seeds, the score and closing prices.

- Plans: Live, Archive, Complete.
- `date`: YYYY-MM-DD (default yesterday)
- `tour`: men or women (men, women)
- `tier`: the level of the event (slam, tour, challenger, itf, utr, team, other)
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/doubles"
```

### Doubles statistics: GET /v1/doubles/matches/{id}/statistics

A doubles match's serve and return figures for each pair, for the match and each set, where the match has them (tour-level doubles from 13 November 2026).

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/doubles/matches/{id}/statistics"
```

### Doubles point by point: GET /v1/doubles/matches/{id}/points

Every game and point of a doubles match: which pair served, who won it, breaks and break points.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/doubles/matches/{id}/points"
```

### Doubles pair: GET /v1/doubles/pairs/{id}

A doubles pair, their record together and every match they played, newest first.

- Plans: Live, Archive, Complete.
- `id` (in the path): an id from another answer
- Paged: `page` and `per_page` (or `limit`, the same; default 50, at most 50, more is read as 50), or `cursor` from `meta.next_cursor`.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/doubles/pairs/{id}"
```

### Market accuracy: GET /v1/markets/accuracy

How often the closing favourite won: by price, level, surface and season, and over the last 30 days.

- Plans: every plan.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/markets/accuracy"
```

### Biggest upsets: GET /v1/markets/upsets

The longest closing prices that won at Grand Slam and tour level.

- Plans: every plan.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/markets/upsets"
```

### Bookmaker margins: GET /v1/markets/margins

Each bookmaker's average margin on its closing prices since the start of last year.

- Plans: Live, Archive, Complete.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/markets/margins"
```

### All-time leaders: GET /v1/records

The most matches won and the most titles, all time.

- Plans: every plan.
- `tour`: men or women (men, women)

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/records"
```

### Season leaders: GET /v1/records/{season}

The most matches won and the most titles in one season.

- Plans: every plan.
- `season` (in the path): a season, such as 2024
- `tour`: men or women (men, women)

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/records/{season}"
```

### Search: GET /v1/search

Players and tournaments together, by name.

- Plans: every plan.
- `q` (required): at least 2 letters of a name

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/search"
```

### Coverage: GET /v1/meta/coverage

What the database holds, season by season, counted from the data.

- Plans: every plan.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/meta/coverage"
```

### 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.

- Plans: Complete.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/exports"
```

### Bulk file: GET /v1/exports/{season}/{dataset}

One season's file of one dataset (matches, prices, moves, statistics or points), gzip-compressed CSV.

- Plans: Complete.
- `season` (in the path): a season, such as 2024
- `dataset` (in the path): matches, prices, moves, statistics or points

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/exports/{season}/{dataset}"
```

### Freshness: GET /v1/freshness

How current each dataset is: the newest day held for results, prices, price moves, statistics and point by point, the share of yesterday's and the last 7 days' matches with each, and when the database was last updated (does not count).

- Plans: every plan; does not count against the allowance.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/freshness"
```

### Usage: GET /v1/usage

Your plan, calls used and limits (does not count).

- Plans: every plan; does not count against the allowance.

```
curl -H "Authorization: Bearer $KEY" "https://api.tennisdatabaseapi.com/v1/usage"
```

## 6. A match

- `id`, `date`, `tour` (men or women), `tournament` (id, name, tier, season, surface, `event_known`), `round`.
- `start_time`: when play began (or is set to begin) on the match's date, UTC, as listed for that day; for a match finished on a later day than it began, the time it resumed on the day it is dated; `null` where not known.
- `winner` and `loser` (id, name, country), `score` from the winner's side, `sets`, `status`, `best_of`, `ranks` and `ranking_points` (each player's ranking points on the day, where known).
- `odds.closing`: the market's closing prices for the winner and the loser.
- One match (`/v1/matches/{id}`) adds:
  - `odds.bookmakers`: each bookmaker's price, with `opened` where the opening price is known;
  - `odds.markets`: `total_games` and `total_sets` (line, over, under), `handicap_games` and `handicap_sets` (the winner's line, winner, loser), `correct_score` (the set score from the winner's side, price);
  - `odds.movement`: every recorded change of each bookmaker's match price, oldest first, as `[time, price]`;
  - `point_by_point`: every game in order (who served, who won it, whether serve was broken, the games after it, every point with the winner's score first, which points were break points and which the server's set or match points), with a summary per side: service games, held, broken, break points faced and deuce games;
  - `duration_minutes`, `set_minutes`, `umpire` and `court` (venue, city, `indoor` true or false, and the `coordinates`, latitude and longitude, with `of` saying whether they are the venue's or the city's) where known;
  - `draw`: in a knockout main draw, `next_match` (the match the winner went on to) and `from_matches` (the matches whose winners met here), so the whole bracket can be walked; `null` for qualifying, round robins and team events;
  - `weather` on outdoor matches: `temperature_c`, `humidity_pct`, `wind_kmh`, `wind_from_deg`, `precipitation_mm_h` and `cloud_cover_pct` from a weather model's analysis at the court's coordinates, the analysis nearest the start time (`at`; `timed` is false where the start time is not known and the afternoon is taken), from mid-2020 on;
  - `stats`: by period (`match`, `set_1`, ...), each figure for the winner and the loser, such as aces, double faults, first serve in, break points won.

- A player: `id`, `name`, `full_name`, `country`, `tour`, `born` (date of birth), `height_cm`, `weight_kg`, `plays` (right or left), `ranking` (current and highest singles ranking, and the day it was read), `first_match`, `last_match`; one player (`/v1/players/{id}`) adds the win and loss record, overall and by surface.

- A live match (`/v1/live`, on the Live and Complete plans): `id` (`lv_` and 10 characters), `status` (`live`, or `finished` for 15 minutes after the end), `start_time`, `tournament`, `round`, `player_1` and `player_2` in the order of play, `score` (`sets`, the `games` of each set, and `current_game` with `server` and `points`, player_1 first), `read_at` and `age_seconds` (read every 15 seconds while in play) and `score_changed_at`; one live match (`/v1/live/{id}`) adds `point_by_point`, every game so far.

## 7. MCP server

- Address: https://api.tennisdatabaseapi.com/mcp (Streamable HTTP, JSON-RPC over POST). Send the same key as a Bearer token.
- A tool call counts like the matching API call and follows the same plan rules.
- 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_statistics`, `doubles_points`, `doubles_pair`, `market_accuracy`, `biggest_upsets`, `bookmaker_margins`, `all_time_leaders`, `season_leaders`, `search`.

## 8. Errors

| HTTP | Code | Meaning |
|---|---|---|
| 400 | `bad_request` | A parameter is missing or out of range, or the key was sent in the address. |
| 401 | `unauthorized` | No key, or a key that is unknown or revoked. |
| 403 | `upgrade_required` | The plan does not include this endpoint or these dates; the error names the plan that does. |
| 404 | `not_found` | No such endpoint, or no such id. |
| 422 | `unknown_parameter` | A parameter this endpoint does not take; the message lists the ones it does. |
| 429 | `rate_limited` | Too many calls this minute; wait for Retry-After. |
| 429 | `quota_exceeded` | The day's or month's allowance is used; the message says when it resets. |
| 500 | `server_error` | Something went wrong on our side; it has been logged. |
| 503 | `server_error` | A part of the service is unavailable for a moment. |

## 9. About

- Tennis Database API is operated by DeveloperData.net, Bangkok, Thailand.
- Website: https://tennisdatabaseapi.com. Status: https://tennisdatabaseapi.com/status.json. OpenAPI: https://api.tennisdatabaseapi.com/openapi.json.
- Support, billing included: https://tennisdatabaseapi.com/support
