A JavaScript library that lets you get achievement, user, and game data from RetroAchievements.
✅ Modular by design and supports tree-shaking.
✅ Officially-supported, aligns 1:1 with the RAWeb API.
✅ Supports Node environments (16 and above).
✅ Ships with TypeScript support and types.
✅ Automatically maps types and properties from RAWeb PHP calls.
✅ Small, <3Kb.
Run the following command:
npm install --save @retroachievements/apiLearn how to authenticate and start pulling data from RetroAchievements on our documentation website.
- Get started
- Get a user's profile information
- Look up games a user has completed
- Get a game's metadata
To use any endpoint function in the API, you must first be authorized by RetroAchievements. Fortunately, this is a fairly straightforward process.
-
Visit your control panel on the RA website.
-
Find the "Keys" section on the page. Copy the web API key value. Do not expose your API key anywhere publicly.
-
You can now create your authorization object using your web API key.
import { buildAuthorization } from "@retroachievements/api";
const userName = "<your username on RA>";
const webApiKey = "<your web API key>";
const authorization = buildAuthorization({ userName, webApiKey });- You now have all you need to use any function in the API. Each function takes this authorization object as its first argument. Here's an example:
import { getGame } from "@retroachievements/api";
// This returns basic metadata about the game on this page:
// https://retroachievements.org/game/14402
const game = await getGame(authorization, { gameId: 14402 });Click the function names to open their complete docs on the docs site.
-
getUserProfile()- Get a user's basic profile information. -
getUserRecentAchievements()- Get a list of achievements recently earned by the user. -
getAchievementsEarnedBetween()- Get a list of achievements earned by a user between two dates. -
getAchievementsEarnedOnDay()- Get a list of achievements earned by a user on a given date. -
getGameInfoAndUserProgress()- Get metadata about a game as well as a user's progress on that game. -
getUserCompletionProgress()- Get metadata about all the user's played games and any awards associated with them. -
getUserAwards()- Get a list of a user's site awards/badges. -
getUserClaims()- Get a list of set development claims made over the lifetime of a user. -
getUserGameRankAndScore()- Get metadata about how a user has performed on a given game. -
getUserPoints()- Get a user's total hardcore and softcore points. -
getUserProgress()- Get a user's progress on a list of specified games. -
getUserRecentlyPlayedGames()- Get a list of games a user has recently played. -
getUserSummary()- Get a user's profile metadata. -
getUserCompletedGames()- Deprecated function. Get hardcore and softcore completion metadata about games a user has played.
-
getGame()- Get basic metadata about a game. -
getGameExtended()- Get extended metadata about a game. -
getAchievementCount()- Get the list of achievement IDs for a game. -
getAchievementDistribution()- Get how many players have unlocked how many achievements for a game. -
getGameRankAndScore()- Get a list of either the latest masters or highest hardcore points earners for a game.
-
getConsoleIds()- Get the complete list of console ID and name pairs on the site. -
getGameList()- Get the complete list of games for a console.
-
getAchievementUnlocks()- Get a list of users who have earned an achievement.
-
getActiveClaims()- Get all active set claims on the site. -
getClaims()- Get all claims of other kinds on the site. -
getTopTenUsers()- Get the list of top ten points earners.
-
getAchievementOfTheWeek()- Get comprehensive metadata about the current Achievement of the Week.
- Get Ticket by ID
- Get Most Ticketed Games
- Get Most Recent Tickets
- Get Game Ticket Stats
- Get Developer Ticket Stats
- Get Achievement Ticket Stats
Let us know about yours by opening an issue!
Check out CONTRIBUTING.md for how to get started.