/v1/players/{id}/rankings

A player's world ranking week by week, on every list they are in, newest first.

GEThttps://api.tabletennisapi.com/v1/players/{id}/rankings

Plans:LiveArchiveComplete

Parameters

Name	In	Type	Required	What it does	Example
`id`	path	id	required	The player id, as returned by any list	`pl_51t63nz3`
`discipline`	query	string	optional	MS, WS, MD, WD or XD	`MS`
`doubles`	query	string	optional	For MD, WD and XD: pair or player	`pair`
`from`	query	date	optional	Weeks published on or after this day (YYYY-MM-DD)	`2026-09-13`
`to`	query	date	optional	Weeks published on or before this day (YYYY-MM-DD)	`2026-09-13`

Run it live

GET /v1/players/{id}/rankingsA real call to the API, from your browser

id disciplinedoublesfromto

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/players/{id}/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": [
        {
            "week": "2026-43",
            "published": "2026-10-19",
            "discipline": "WD",
            "doubles": "pair",
            "list": "senior",
            "rank": 1,
            "previous_rank": 1,
            "movement": 0,
            "points": 7750,
            "partner": {
                "id": "pl_awb8xnz2",
                "name": "Hayata Hina",
                "country": "JPN"
            }
        },
        {
            "week": "2026-43",
            "published": "2026-10-19",
            "discipline": "WD",
            "doubles": "pair",
            "list": "senior",
            "rank": 51,
            "previous_rank": 48,
            "movement": -3,
            "points": 400,
            "partner": {
                "id": "pl_0e2p4z4v",
                "name": "Odo Satsuki",
                "country": "JPN"
            }
        }
    ],
    "meta": {
        "count": 2,
        "next_cursor": "eyJvIjoyLCJwIjoyfQ",
        "page": 1,
        "per_page": 2,
        "total": 27,
        "total_pages": 14,
        "next_page": 2,
        "prev_page": null
    }
}

Example

curl

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

Python

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

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