GET
https://api.tennisdatabaseapi.com/v1/rankings/{date}Paid plansThe ranking list of the week of a date: singles, men from 1973 and women from 2003; women's doubles with list=doubles.
Free key not 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/rankings/2015-06-01?tour=men&per_page=3
1Parameters
| Name | What it is |
|---|---|
daterequired | A day, YYYY-MM-DD: the list of the week it falls in. |
tour | Men or women: men, women. |
list | Singles (default) or doubles; doubles lists are held for women: singles, doubles. |
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/rankings/2015-06-01?tour=men&per_page=3"
$ch = curl_init('https://api.tennisdatabaseapi.com/v1/rankings/2015-06-01?tour=men&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/rankings/2015-06-01?tour=men&per_page=3", headers={"Authorization": f"Bearer {os.environ['TDA_KEY']}"}, ) print(r.json()["data"])
const r = await fetch("https://api.tennisdatabaseapi.com/v1/rankings/2015-06-01?tour=men&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": [
{
"rank": 1,
"points": 13845,
"player": { "id": "pl_zw6y4xa4", "name": "Djokovic N.", "country": "Serbia" }
},
{
"rank": 2,
"points": 9235,
"player": { "id": "pl_z5vm51dn", "name": "Federer R.", "country": "Switzerland" }
},
{
"rank": 3,
"points": 7040,
"player": { "id": "pl_3tqsxp09", "name": "Murray A.", "country": "United Kingdom" }
}
],
"meta": {
"tour": "men",
"list": "singles",
"week": "2015-05-25",
"count": 3,
"next_cursor": "eyJvIjozLCJwIjozfQ",
"page": 1,
"per_page": 3,
"total": 2218,
"total_pages": 740,
"next_page": 2,
"prev_page": null
}
}{
"error": {
"code": "upgrade_required",
"message": "This endpoint is on the Live plan and above.",
"plan": "Live",
"upgrade": "https://tennisdatabaseapi.com/pricing",
"docs": "https://tennisdatabaseapi.com/documentation/errors"
}
}{
"error": {
"code": "not_found",
"message": "No ranking list is held for the week of 1950-01-02. Men are held from 1973, women from 2003.",
"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 |
|---|---|
rank, points, player | One row a place on that week's list; player.id is null for the few names not matched to a player we hold |
meta.week, meta.list | The Monday of the list answered (the latest on or before the date), and singles or doubles. Women's doubles lists come with list=doubles |
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. |
upgrade_required | The free key: this endpoint is on the Live plan and above. |
not_found | No such id. |
unknown_parameter | A parameter this endpoint does not take. |
rate_limited | Too many calls this minute, or the allowance used (quota_exceeded). |