tennisdatabaseAPI

Tennis API documentation

Ctrl K
DocsRankingsElo ratings
Rankings

Elo ratings

MCP tool elo_ratings
GEThttps://api.tennisdatabaseapi.com/v1/eloEvery plan

The 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

NameInTypeWhat it is
tourquerystringMen or women: men, women.
surfacequerystringAll courts, or one surface (default all): all, hard, clay, grass.
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/elo?tour=women&surface=clay&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": [
    {
      "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
  }
}

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

4Fields

FieldTypeWhat it holds
position, player, elomixedThe order by Elo, the player and the rating (1,500 is a new player)
matches, ranking, last_matchmixedMatches rated, the current ranking and the last match

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.
422unknown_parameterA parameter this endpoint does not take.
429rate_limitedToo many calls this minute, or the allowance used (quota_exceeded).