Skip to content

The official JavaScript library for getting achievement, user, and game data from RetroAchievements.

License

Notifications You must be signed in to change notification settings

RetroAchievements/api-js

Repository files navigation

RetroAchievements Logo

@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:

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.

  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.

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

const username = "<your username on RA>";
const webApiKey = "<your web API key>";

const authorization = buildAuthorization({ username, webApiKey });
  1. 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

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

Feed

Event

Ticket

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.