@retroachievements/api

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

Documentation: Get Started

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:

``bash
npm install --save @retroachievements/api
`

Documentation

Learn 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

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.

1. Visit your control panel on the RA website.

2. Find the "Keys" section on the page. Copy the web API key value. Do not expose your API key anywhere publicly.

3. You can now create your authorization object using your web API key.

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

const username = "";
const webApiKey = "";

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

4. 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:

`ts
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.

$3

- 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.
- getUserWantToPlayList() - Get a user's "Want to Play Games" list.
- getUsersFollowingMe() - Get the caller's "Followers" users list.
- getUsersIFollow() - Get the caller's "Following" users list.
- getUserSetRequests() - Get a given user's set requests, maximum total requests, and points until next request.

$3

- getGame() - Get basic metadata about a game.
- getGameExtended() - Get extended metadata about a game.
- getGameHashes() - Get a list of hashes linked to a game.
- getGameProgression() - Get information about the average time to unlock achievements in 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.

$3

- getLeaderboardEntries() - Get a given leaderboard's entries.
- getUserGameLeaderboards() - Get a user's list of leaderboards for a given game.

$3

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

$3

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

$3

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

$3

- getComments() - Get the comments left an achievement, game, or user wall.

$3

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

$3

- Get Ticket by ID
- Get Most Ticketed Games
- Get Most Recent Tickets
- Get Game Ticket Stats
- Get Developer Ticket Stats
- Get Achievement Ticket Stats

Projects Using @retroachievements/api

Let us know about yours by opening an issue!

How to Contribute

Check out CONTRIBUTING.md for how to get started.