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.getRecentGameAwards()- Get all recent mastery, completion, and beaten awards earned 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.