diff --git a/README.md b/README.md index e64ae5f..da4e013 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,7 @@ Click the function names to open their complete docs on the docs site. - [Leaderboards (by gameID)](https://api-docs.retroachievements.org/v1/get-game-leaderboards.html) - Get a given games's list of leaderboards. - [Entries](https://api-docs.retroachievements.org/v1/get-leaderboard-entries.html) - Get a given leadboard's entries. +- [User game leaderboards](https://api-docs.retroachievements.org/v1/get-user-game-ladearboards.html) - Get a given user and game leaderboards. ### System diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index fb38f17..38595d6 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -162,6 +162,10 @@ export default defineConfig({ text: "Entries", link: "/v1/get-leaderboard-entries", }, + { + text: "User Leaderboards (by gameID)", + link: "/v1/get-user-game-leaderboards", + }, ], }, { diff --git a/docs/v1/get-user-game-leaderboards.md b/docs/v1/get-user-game-leaderboards.md new file mode 100644 index 0000000..5a9228f --- /dev/null +++ b/docs/v1/get-user-game-leaderboards.md @@ -0,0 +1,71 @@ + + +# User Game Leaderboards + +A call to this endpoint will retrieve a user's list of leaderboards for a given game, targeted by the game's ID. + +[[toc]] + +## On-site Representation + +A games's list of leaderboards can be found on on the game's page: + +![Game Leaderboards](/game-leaderboards.png) + +This endpoint will only return the leaderboards for the user given in the request. If the user has not submitted a score for a leaderboard, it will not be included in the response. + +## HTTP Request + +https://retroachievements.org/API/API_GetUserGameLeaderboards.php?i=1&u=zuliman92 + +### Query Parameters + +| Name | Required? | Description | +| :--- | :-------- | :----------------------------------------------------------- | +| `y` | Yes | Your web API key. | +| `i` | Yes | The target game ID. | +| `u` | Yes | The username of the user to retrieve leaderboards for. | +| `c` | | Count, number of records to return (default: 200, max: 500). | +| `o` | | Offset, number of entries to skip (default: 0). | + +## Client Library + +Not yet supported. + +## Response + +::: code-group + +```json [HTTP Response] +{ + "Count": 10, + "Total": 64, + "Results": [ + { + "ID": 19062, + "RankAsc": true, + "Title": "New Zealand One", + "Description": "Complete New Zealand S1 in least time", + "Format": "MILLISECS", + "UserEntry": { + "User": "zuliman92", + "Score": 12620, + "FormattedScore": "2:06.20", + "Rank": 2, + "DateUpdated": "2024-12-12T16:40:59+00:00" + } + }, + ... + ] +} +``` + +::: + +## Source + +| Repo | URL | +| :---- | :------------------------------------------------------------------------------------------------ | +| RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserGameLeaderboards.php |