go-retroachievements

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

Documentation: Get Started

---

Installation

Use go get to install the latest version of the library.

go get github.com/joshraphael/go-retroachievements@latest

Then include it in your application:

import "github.com/joshraphael/go-retroachievements"
import "github.com/joshraphael/go-retroachievements/models"

Usage

Construct a new Retro Achievement client using your personal web API key

client := retroachievements.NewClient("<your web API key>")

you can now use the client to call any of the available endpoints, for example:

profile, err := client.GetUserProfile(models.GetUserProfileParameters{
    Username: "jamiras",
})

Check out the examples directory for how to call each endpoint, as well as our GoDocs

API

For convenience, the API docs and examples can be found in the tables below

User

Function	Description	Links
GetUserProfile()	Get a user's basic profile information.	docs | example
GetUserRecentAchievements()	Get a list of achievements recently earned by the user.	docs | example
GetAchievementsEarnedBetween()	Get a list of achievements earned by a user between two dates.	docs | example
GetAchievementsEarnedOnDay()	Get a list of achievements earned by a user on a given date.	docs | example
GetGameInfoAndUserProgress()	Get metadata about a game as well as a user's progress on that game.	docs | example
GetUserCompletionProgress()	Get metadata about all the user's played games and any awards associated with them.	docs | example
GetUserAwards()	Get a list of a user's site awards/badges.	docs | example
GetUserClaims()	Get a list of set development claims made over the lifetime of a user.	docs | example
GetUserGameRankAndScore()	Get metadata about how a user has performed on a given game.	docs | example
GetUserPoints()	Get a user's total hardcore and softcore points.	docs | example
GetUserProgress()	Get a user's progress on a list of specified games.	docs | example
GetUserRecentlyPlayedGames()	Get a list of games a user has recently played.	docs | example
GetUserSummary()	Get a user's profile metadata.	docs | example
GetUserCompletedGames()	[Deprecated] Get hardcore and softcore completion metadata about games a user has played.	docs | example
GetUserWantToPlayList()	Get a user's "Want to Play Games" list.	docs | example

Game

Function	Description	Links
GetGame()	Get basic metadata about a game.	docs | example
GetGameExtended()	Get extended metadata about a game.	docs | example
GetGameHashes()	Get the hashes linked to a game.	docs | example
GetAchievementCount()	Get the list of achievement IDs for a game.	docs | example
GetAchievementDistribution()	Gets how many players have unlocked how many achievements for a game.	docs | example
GetGameRankAndScore()	Gets metadata about either the latest masters for a game, or the highest points earners for a game.	docs | example

Leaderboards

Function	Description	Links
GetGameLeaderboards()	Gets a given games's list of leaderboards.	docs | example
GetLeaderboardEntries()	Gets a given leadboard's entries.	docs | example

System

Function	Description	Links
GetConsoleIDs()	Gets the complete list of all system ID and name pairs on the site.	docs | example
GetGameList()	Gets the complete list of games for a specified console on the site.	docs | example

Achievement

Function	Description	Links
GetAchievementUnlocks()	Gets a list of users who have earned an achievement.	docs | example

Comment

Function	Description	Links
GetComments()	Gets comments of a specified kind: game, achievement, or user.	docs | example

Feed

Function	Description	Links
GetRecentGameAwards()	Gets all recently granted game awards across the site's userbase.	docs | example
GetActiveClaims()	Gets information about all active set claims (max: 1000).	docs | example
GetClaims()	Gets information about all achievement set development claims of a specified kind: completed, dropped, or expired (max: 1000).	docs | example
GetTopTenUsers()	Gets the current top ten users, ranked by hardcore points, on the site.	docs | example

Event

Function	Description	Links
GetAchievementOfTheWeek()	Gets comprehensive metadata about the current Achievement of the Week.	docs | example

Ticket

Function	Description	Links
GetTicketByID()	Gets ticket metadata information about a single achievement ticket, targeted by its ticket ID.	docs | example
GetMostTicketedGames()	Gets the games on the site with the highest count of opened achievement tickets.	docs | example
GetMostRecentTickets()	Gets ticket metadata information about the latest opened achievement tickets on RetroAchievements.	docs | example
GetGameTicketStats()	Gets ticket stats for a game, targeted by that game's unique ID.	docs | example
GetDeveloperTicketStats()	Gets ticket stats for a developer, targeted by that developer's site username.	docs | example
GetAchievementTicketStats()	Gets ticket stats for an achievement, targeted by that achievement's unique ID.	docs | example