tennisdatabaseAPI

Tennis API documentation

Ctrl K
DocsRankingsRankings on a date
Rankings

Rankings on a date

MCP tool rankings_on_date
GEThttps://api.tennisdatabaseapi.com/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.

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

NameInTypeWhat it is
daterequiredpathdateA day, YYYY-MM-DD: the list of the week it falls in.
tourquerystringMen or women: men, women.
listquerystringSingles (default) or doubles; doubles lists are held for women: singles, doubles.
page, per_pagequeryintegerPaging: 50 a page unless you ask, at most 50. See Paging.
cursorquerystringThe 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"

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
  }
}

Real answers from the API, made 2026-11-18. Long lists are cut to three items here.

4Fields

FieldTypeWhat it holds
rank, points, playermixedOne 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.listmixedThe 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

400bad_requestA value out of range, such as a date or a tier that is not one of the list.
401unauthorizedNo key, or a key that is unknown or revoked.
403upgrade_requiredThe free key: this endpoint is on the Live plan and above.
404not_foundNo such id.
422unknown_parameterA parameter this endpoint does not take.
429rate_limitedToo many calls this minute, or the allowance used (quota_exceeded).