Documentation / Rankings and breaks
Snooker API: World rankings: a season's list, position by position, with ranking points where they are known
World rankings: a season's list, position by position, with ranking points where they are known.
GEThttps://api.snookerapi.net/v1/rankings
Try it
Parameters
| Name | Type | What it is |
|---|---|---|
| season | season | Season, e.g. 2023-24. Left out: the newest season held. |
| list | string | Which list of the season, as meta.lists names them. Left out: the latest. |
| player_id | id | Only this player (pl_ id): their place in every list of the season. |
| page | integer | Page number, from 1. |
| cursor | string | The next_cursor from the previous page. |
| per_page | integer | Rows per page. |
Returns
| Field | Type | What it holds |
|---|---|---|
| season | string or null | The season, as 2025-26. |
| list | string or null | Which list of the season, as it was published. |
| position | integer | The place in the list. |
| player | object | The player: id and name. |
| points | integer or null | Ranking points, or the break's points. |
Example answer
A real answer, read from the data within the last hour: GET /v1/rankings?per_page=3
{
"data": [
{
"season": "2025-26",
"list": "revision 11",
"position": 1,
"player": {
"id": "pl_ndtp08wj",
"name": "Judd Trump"
},
"points": null
},
{
"season": "2025-26",
"list": "revision 11",
"position": 2,
"player": {
"id": "pl_7r9jtk6a",
"name": "Neil Robertson"
},
"points": null
},
{
"season": "2025-26",
"list": "revision 11",
"position": 3,
"player": {
"id": "pl_vvv0gwc6",
"name": "Zhao Xintong"
},
"points": null
}
],
"meta": {
"plan": "House key",
"count": 3,
"next_cursor": "bzMuYjc3MjM0",
"page": 1,
"per_page": 3,
"total": 129,
"total_pages": 43,
"next_page": 2,
"prev_page": null,
"season": "2025-26",
"list": "revision 11",
"lists": [
"revision 0",
"revision 1",
"revision 2",
"revision 3",
"revision 4",
"revision 5",
"revision 6",
"revision 7",
"revision 8",
"revision 9",
"revision 10",
"revision 11"
]
}
}Errors
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | No key, or a key that is not valid. Errors |
| 400 | bad_request | A parameter has the wrong shape. Errors |
| 422 | unknown_parameter | A parameter this call does not take. Errors |
| 429 | rate_limited | Too many calls this minute; wait for Retry-After. Errors |
| 403 | upgrade_required | The record is older than yesterday and the key is the free one. Errors |