Documentation / Players
Snooker API: One player: nationality, birth date and place, the year they turned professional, their ranking, minor-ranking and world titles, the first season they were ranked, their highest world ranking, matches played and won, titles, and the seasons they span
One player: nationality, birth date and place, the year they turned professional, their ranking, minor-ranking and world titles, the first season they were ranked, their highest world ranking, matches played and won, titles, and the seasons they span.
GEThttps://api.snookerapi.net/v1/players/{player_id}
Try it
Parameters
| Name | Type | What it is |
|---|---|---|
| player_id | id, required, in the path | The player, as a pl_ id from GET /v1/players. |
Returns
| Field | Type | What it holds |
|---|---|---|
| id | string | The record's own id: stable, and the same in every call. |
| name | string | The name, as we hold it. |
| country | string or null | The country. |
| born | date or null | The date of birth, where it is known. |
| birth_place | string or null | Where the player was born, as their Wikipedia article gives it. |
| nickname | string or null | The player's nickname, as Wikidata records it. |
| turned_pro | integer or null | The year the player turned professional; null where it is not recorded. |
| first_ranked_season | string or null | The first season the player appears in a world ranking list, e.g. 2013-14; null where never ranked. |
| highest_ranking | object or null | The best world ranking position: position, season (the first season it was reached) and from (ranking_lists, our own lists; or player_record, with no season, where our lists do not reach). Null where neither has it. |
| ranking_titles | integer or null | Ranking titles won in the player's career, as their Wikipedia article counts them. |
| minor_ranking_titles | integer or null | Minor-ranking titles won, as their Wikipedia article counts them. |
| world_titles | integer or null | World Championship titles won, as their Wikipedia article lists them; 0 where it lists none. |
| form | string or null | The last ten decided matches, newest first: W won, L lost. |
| latest_season | object or null | The latest season the player played: season, played, won, lost, frames_won, frames_lost, titles. |
| matches | integer | How many matches are held. |
| wins | integer | Matches won. |
| titles | integer | Events won. |
| first_season | string or null | The first season played. |
| last_season | string or null | The latest season played. |
| century_breaks | integer | Centuries made in the events we hold. |
| maximum_breaks | integer | Officially recognised 147s. |
Example answer
A real answer, read from the data within the last hour: GET /v1/players/pl_ra6m6b4g
{
"data": {
"id": "pl_ra6m6b4g",
"name": "Wu Yize",
"country": "People's Republic of China",
"born": "2003-10-14",
"birth_place": "Lanzhou, Gansu, China",
"nickname": null,
"turned_pro": 2021,
"first_ranked_season": "2021-22",
"highest_ranking": {
"position": 4,
"season": "2025-26",
"from": "ranking_lists"
},
"ranking_titles": 3,
"minor_ranking_titles": null,
"world_titles": 1,
"form": "WWWWWLWWLW",
"latest_season": {
"season": "2026-27",
"played": 20,
"won": 12,
"lost": 5,
"frames_won": 80,
"frames_lost": 67,
"titles": 1
},
"matches": 257,
"wins": 151,
"titles": 3,
"first_season": "2017-18",
"last_season": "2026-27",
"century_breaks": 166,
"maximum_breaks": 1
},
"meta": {
"plan": "House key"
}
}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 |
| 404 | not_found | No record has that id. Errors |