GET
https://api.tennisdatabaseapi.com/v1/eloEvery planThe players our Elo rates highest, overall or on one surface, among those with a match in the last year.
Free key includedLive includedArchive includedComplete included
Try itRuns against the live API with your key. Your key stays in this browser.API
GEThttps://api.tennisdatabaseapi.com/v1/elo?tour=women&surface=clay&per_page=3
1Parameters
| Name | What it is |
|---|---|
tour | Men or women: men, women. |
surface | All courts, or one surface (default all): all, hard, clay, grass. |
page, per_page | Paging: 50 a page unless you ask, at most 50. See Paging. |
cursor | The meta.next_cursor of the page before, to walk a long list. |
Anything else in the address answers 422 unknown_parameter, with the list of parameters this endpoint takes.
2Request
curl -H "Authorization: Bearer $TDA_KEY" \ "https://api.tennisdatabaseapi.com/v1/elo?tour=women&surface=clay&per_page=3"
$ch = curl_init('https://api.tennisdatabaseapi.com/v1/elo?tour=women&surface=clay&per_page=3'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TDA_KEY')], CURLOPT_RETURNTRANSFER => true, ]); $answer = json_decode(curl_exec($ch), true); print_r($answer['data']);
import os, requests r = requests.get( "https://api.tennisdatabaseapi.com/v1/elo?tour=women&surface=clay&per_page=3", headers={"Authorization": f"Bearer {os.environ['TDA_KEY']}"}, ) print(r.json()["data"])
const r = await fetch("https://api.tennisdatabaseapi.com/v1/elo?tour=women&surface=clay&per_page=3", { headers: { Authorization: `Bearer ${process.env.TDA_KEY}` }, }); const { data } = await r.json(); console.log(data);
The code follows the form in Try it, with your key in it once you have entered one. Without a key it reads $TDA_KEY.
3Answer
{
"data": [
{
"position": 1,
"player": { "id": "pl_578mjw2r", "name": "Swiatek I.", "country": "Poland" },
"elo": 2624,
"matches": 199,
"ranking": 8,
"last_match": "2026-05-31"
},
{
"position": 2,
"player": { "id": "pl_tebd2n9w", "name": "Andreeva M.", "country": "World" },
"elo": 2605,
"matches": 110,
"ranking": 3,
"last_match": "2026-06-06"
},
{
"position": 3,
"player": { "id": "pl_qfz5j4g1", "name": "Sabalenka A.", "country": "World" },
"elo": 2604,
"matches": 159,
"ranking": 2,
"last_match": "2026-06-03"
}
],
"meta": {
"tour": "women",
"surface": "clay",
"active_since": "2025-11-18",
"count": 3,
"next_cursor": "eyJvIjozLCJwIjozfQ",
"page": 1,
"per_page": 3,
"total": 3307,
"total_pages": 1103,
"next_page": 2,
"prev_page": null
}
}{
"data": [
{
"position": 1,
"player": { "id": "pl_578mjw2r", "name": "Swiatek I.", "country": "Poland" },
"elo": 2624,
"matches": 199,
"ranking": 8,
"last_match": "2026-05-31"
},
{
"position": 2,
"player": { "id": "pl_tebd2n9w", "name": "Andreeva M.", "country": "World" },
"elo": 2605,
"matches": 110,
"ranking": 3,
"last_match": "2026-06-06"
},
{
"position": 3,
"player": { "id": "pl_qfz5j4g1", "name": "Sabalenka A.", "country": "World" },
"elo": 2604,
"matches": 159,
"ranking": 2,
"last_match": "2026-06-03"
}
],
"meta": {
"tour": "women",
"surface": "clay",
"active_since": "2025-11-18",
"count": 3,
"next_cursor": "eyJvIjozLCJwIjozfQ",
"page": 1,
"per_page": 3,
"total": 3307,
"total_pages": 1103,
"next_page": 2,
"prev_page": null
}
}{
"error": {
"code": "bad_request",
"message": "per_page is 1 to 50.",
"docs": "https://tennisdatabaseapi.com/documentation/errors"
}
}Real answers from the API, made 2026-11-18. Long lists are cut to three items here.
4Fields
| Field | What it holds |
|---|---|
position, player, elo | The order by Elo, the player and the rating (1,500 is a new player) |
matches, ranking, last_match | Matches rated, the current ranking and the last match |
5Errors
bad_request | A value out of range, such as a date or a tier that is not one of the list. |
unauthorized | No key, or a key that is unknown or revoked. |
unknown_parameter | A parameter this endpoint does not take. |
rate_limited | Too many calls this minute, or the allowance used (quota_exceeded). |