/v1/rankings

World rankings: the top 100 of a list for a week, with points and movement. The latest week unless you ask for one.

GEThttps://api.tabletennisapi.com/v1/rankings

Plans:Free keyLiveArchiveComplete

Parameters

Name	In	Type	Required	What it does	Example
`discipline`	query	string	optional	MS, WS, MD, WD or XD	`MS`
`doubles`	query	string	optional	For MD, WD and XD: pair (pairs ranked together) or player (each player ranked on their own doubles results)	`pair`
`list`	query	string	optional	senior or youth	`senior`
`week`	query	string	optional	A past week, such as 2026-41 (year and week). Weeks are held from the first week we read on	`2026-41`
`country`	query	string	optional	Only players from this country (three letters); keeps their world rank	`CHN`

Run it live

GET /v1/rankingsA real call to the API, from your browser

disciplinedoubleslistweekcountry

Your key stays in this page: it is sent only to api.tabletennisapi.com and never stored. Left empty, the call runs on a free key with its dates and fields, 20 calls a minute.

GEThttps://api.tabletennisapi.com/v1/rankings

Not run yet

Press Run it to see the answer here.

Response

A real answer from the data, two rows shown. Every field is described in the manual.

200 OKapplication/json

{
    "data": [
        {
            "rank": 1,
            "previous_rank": 1,
            "movement": 0,
            "points": 8550,
            "player": {
                "id": "pl_5p9a00yg",
                "name": "Matsushima Sora",
                "country": "JPN"
            },
            "partner": null,
            "age_group": "U19"
        },
        {
            "rank": 2,
            "previous_rank": 2,
            "movement": 0,
            "points": 6859,
            "player": {
                "id": "pl_3cg5pd0f",
                "name": "Lebrun Felix",
                "country": "FRA"
            },
            "partner": null,
            "age_group": null
        }
    ],
    "meta": {
        "week": "2026-43",
        "published": "2026-10-19",
        "discipline": "MS",
        "doubles": null,
        "list": "senior",
        "count": 100
    }
}

Example

curl

curl https://api.tabletennisapi.com/v1/rankings \
  -H "Authorization: Bearer $TT_KEY"

Python

import os, requests
res = requests.get("https://api.tabletennisapi.com/v1/rankings",
    headers={"Authorization": "Bearer " + os.environ["TT_KEY"]}).json()

Answers come back as data and meta; errors as error. See Errors and Pagination.