@retroachievements/api

A JavaScript library that lets you get achievement, user, and game data from RetroAchievements.

Features

✅ 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.

Installation

Run the following command:

npm install --save @retroachievements/api

Documentation

Learn how to authenticate and start pulling data from RetroAchievements on our documentation website.

How to begin making API calls

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 });

API

Click the function names to open their complete docs on the docs site.

User

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.

Game

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.

System

getConsoleIds() - Get the complete list of console ID and name pairs on the site.
getGameList() - Get the complete list of games for a console.

Achievement

getAchievementUnlocks() - Get a list of users who have earned an achievement.

Feed

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.

Event

getAchievementOfTheWeek() - Get comprehensive metadata about the current Achievement of the Week.

falsepopsky/api-js