Skip to content

Game Unlocks Distribution

A call to this endpoint will retrieve a dictionary of the number of players who have earned a specific number of achievements for a given game ID. This endpoint can be used to determine the total mastery count for a game, as well as how rare that overall mastery is.

On-site Representation

When browsing a game page, for example, Sonic the Hedgehog, a chart representing the achievement distribution can be seen on the page:

Achievement Distribution

HTTP Request

GET

https://retroachievements.org/API/API_GetAchievementDistribution.php?i=14402&h=1

Query Parameters

NameRequired?Description
zYesYour username.
yYesYour web API key.
iYesThe target game ID.
h1 to only query hardcore unlocks. 0 to query all unlocks. Defaults to 0.
f3 for official achievements. 5 for unofficial achievements. Defaults to 3.

Client Library

ts
import {
  buildAuthorization,
  getAchievementDistribution,
} from "@retroachievements/api";

// First, build your authorization object.
const username = "<your username on RA>";
const webApiKey = "<your web API key>";

const authorization = buildAuthorization({ username, webApiKey });

// Then, make the API call.
const achievementDistribution = await getAchievementDistribution(
  authorization,
  {
    gameId: 14402,
    hardcore: true,
  },
);
kotlin
val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetAchievementDistribution.Response, ErrorResponse> = api.getAchievementDistribution(
    gameId = 14402,
    hardcore = 1
)

if (response is NetworkResponse.Success) {
    // handle the data
    val distribution: GetAchievementDistribution.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Response

json
{
  "1": 141,
  "2": 51,
  "3": 41,
  "4": 49,
  "5": 57,
  "6": 41,
  "7": 36,
  "8": 67,
  "9": 75,
  "10": 28,
  "11": 26,
  "12": 3,
  "13": 6,
  "14": 3,
  "15": 8
}
json
{
  "1": 141,
  "2": 51,
  "3": 41,
  "4": 49,
  "5": 57,
  "6": 41,
  "7": 36,
  "8": 67,
  "9": 75,
  "10": 28,
  "11": 26,
  "12": 3,
  "13": 6,
  "14": 3,
  "15": 8
}

Source

RepoURL
RAWebhttps://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementDistribution.php
api-jshttps://github.com/RetroAchievements/api-js/blob/main/src/game/getAchievementDistribution.ts
api-kotlinhttps://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt

Released under the MIT license.