API Enhancement Requests

[wescopeland]

Is the API missing data or would you like something changed/improved to better suit your needs? Place your request here so we don't lose it.

You can also find API support in our #coders channel on Discord: https://discord.com/channels/310192285306454017/645777658319208448

[ioslife]

Getting Achievement Type on would be helpful – API_GetUserRecentAchievements

I pulled down RAWeb and was gonna make a change for this, assuming it would be as simple as it was to add it to getAchievementUnlocks. Alas, it looks like this change would require a change to the DB query. It looks like it should just be adding ach.Type to getAchievementsEarnedBetween in player-history.php, but not sure if changing that has any other repercussion. So I will simply keep this as a request rather than a PR 😅

[wescopeland]

Resolved by #2089.

[Hexadigital]

One endpoint that I would love to see, for use in things like stream overlays and progress widgets, is an endpoint that takes in a game ID and username, and returns information relating to the game and user progress.
For the game: game title, game badge image URL, game console/platform name, total points earned, total points in set
For the achievements earned: achievement title, achievement point value, achievement image URL, achievement type (if possible), and achievement unlock timestamp (preferably unix time, or including timezone, if possible)

If possible, I'd like the game ID to be optional - and if omitted, it could use the latest game ID from the user's profile (either the latest rich presence game, or the first game in the activity list on the profile)

I'm currently using that information in a stream overlay like the below image, but I think it would be less intensive on the server to have a dedicated query, since otherwise I need to use multiple endpoints to fetch and discard a lot of information that isn't needed.

[LaunchBox-C-Beats]

Pretty sure you just described the getGameInfoAndUserProgress endpoint found here: https://api-docs.retroachievements.org/v1/users/get-game-info-and-user-progress.html

[Hexadigital]

Yeah, it does look like that endpoint has everything but the achievement type - at the moment I'm using that endpoint in conjunction with GetUserRecentlyPlayedGames (to figure out the latest game played) and that seems to work well.

[wescopeland]

A large portion of this is likely handled by #2122.

[Hexadigital]

I'd like to bump this as a separate request again - GetGameInfoAndUserProgress and GetUserRecentlyPlayedGames are both down/disabled at the moment, so a more reliable endpoint would be appreciated.

[ioslife]

Another endpoint that I mentioned (Wes said he would look into it already, just adding here to not lose track) is something that returns filterAndJoinGames results from https://github.com/RetroAchievements/RAWeb/blob/master/app/Platform/Services/PlayerProgressionService.php

This would allow consumers to have access to the already combined user recent progress and user site awards calls.

[wescopeland]

I believe this might pair nicely with what @Hexadigital is proposing for a new API_GetUserGameProgression (?) endpoint in #2081 (comment).

[wescopeland]

#2122

[rsubtil]

(forwarded suggestion from Discord)

One addition that I believe is really useful is an endpoint to fetch the game ID (if existing) by supplying the computed game hash (according to https://docs.retroachievements.org/Game-Identification/) instead. This would be really useful for software that's more "general" purpose, such as emulator frontends.

[wescopeland]

Will be resolved by #2090.

[rsubtil]

Since #2090 was closed in favor of using the getGameList endpoint, considering the amount of information returned, I'd like to keep my usage of this endpoint to a minimum to avoid a lot of traffic/processing on your end.

Can I reasonably assume that a game's hashes are immutable, and stay the same for a long period of time, such as a few months/years? If yes, I can keep such information cached on the client, and only make requests when there's no existing local information about a game's hash.

[wescopeland]

Yes, it is a reasonable assumption that a game's hashes tend not to change very often, often in the timespan of months or years.

However, one thing I am curious about -- how is your front-end actually hashing the games?

[rsubtil]

However, one thing I am curious about -- how is your front-end actually hashing the games?

I use the official hash module from rcheevos, which I had to port to Godot, available here: https://github.com/retrohub-org/godot-rcheevos-rhash

[wescopeland]

Awesome! Do you happen to be in the RetroAchievements Discord? If so, can you please DM me?

[LaunchBox-C-Beats]

Right now in LaunchBox there is a window that displays the Top Ten user leaderboard. We get the information from GetTopTenUsers. Right now after making that call we then have to call GetUserSummary 10x so that we can get those users profile pic to display in said leaderboard. Would save the number of API calls we'd have to make if that information was returned in the GetTopTenUsers return set.

[wescopeland]

It probably makes sense to include the user's highest award level on the game info & user progress call. Now with beaten awards introduced, this is unclear without making an additional call to get user awards.

[wescopeland]

#2122

[ioslife]

Add pagination to API_GetUserCompletedGames

Calling for a user that has a ton of records (i.e. MaxMilyin) is significantly slower (1106 ms) than a user with fewer records (i.e. Bronson15 – 263 ms)

[wescopeland]

Not sure how to do this in a way that's not a breaking change.

[ioslife]

I also didn't have an idea. Just wanted to add that it would be helpful :)

[LaunchBox-C-Beats]

This is coming from a C# dev who admittedly has little web experience, but the concept sounds doable to me. Would it be possible to add two optional parameters for page number and records per page. Page number defaults to null, records per page can default to whatever makes most sense. Then in the API logic is page number is null return the full dataset, otherwise return the number of records requested. Consumer would know to call for more pages if the number of results returned was the same as the results per page count, stop when the number of records is less than that.

[wescopeland]

#2122 will support pagination and return only 1 record per each game.

[ioslife]

Merry Christmas! Thanks for all these updates!!

[ioslife]

Add Achievement Image URL to API_GetAchievementOfTheWeek

[wescopeland]

#2121

[ioslife]

Return softcore points in API_GetAchievementUnlocks

[wescopeland]

Not sure I completely follow this request. Can you clarify? I see Points being returned, which is going to always be the same for both hardcore and softcore.

[ioslife]

Yeah, sorry. AchievementUnlocks returns

{
"user": "Podgicus0305",
"raPoints": 15544,
"dateAwarded": "2022-07-12 19:06:34",
"hardcoreMode": true
}

I believe raPoints is hardcore, but I’d like to get softcore too for those that don’t play hardcore.

[ioslife]

#2495

[ioslife]

Add endpoints for:
• GET and POST(!) Want to Play games
• GET and POST(!) Follow/Unfollow users

[wescopeland]

What response shapes would be desirable for these GET requests?

[ioslife]

Followed user would be nice to have something like this:

FollowedUser {
	username: "Bronson15",
	points: 999999,
	softcorePoints: 999999
}

GetFollowedUsers {
	[
		FollowedUser1,
		FollowedUser2,
		FollowedUser3
	]
}

WantToPlayGames would be nice to have something like this:

WantToPlayGame {
	id: 1,
	name: "Sonic the Hedgehog"",
	consoleName: "Genesis",
	imageIcon: "/url/here.png",
	maxPossible: 70,
	numAwarded: 35,
	numAwardedHardcore: 15
}

GetWantToPlayGames {
	[
		WantToPlayGame1,
		WantToPlayGame2,
		WantToPlayGame3
	]
}

[joamjoamjoam]

Plus one for this. It would nice to manage the want to play list through the API.

[ioslife]

Plus one for this. It would nice to manage the want to play list through the API.

I started working on this. For now it will only be a GET request, so managing via API will not be possible.

#2549

[Hexadigital]

I don't know how much interest there would be in it outside of my use case, but one thing that I was doing before (that I can't do now) was sending a POST request to reorderSiteAwards.php, in order to systematically sort my badges. If there was an API endpoint that took in an ordered list of game ID's (at a minimum) or a more complicated structure and updated the user's profile accordingly, that would be greatly appreciated.

[Nepiki]

Posted this on Discord as well, but it would be ideal if the getUserCompletedGames endpoint could account for progression (unfinished, beaten, mastered) so we can determine a game's state on import/daily sync.

[wescopeland]

#2122

[ioslife]

Add an endpoint to return the New Sets/Revisions list

[ioslife]

This actually is accessible via the getClaims call and sorting on UpdatedDate. getClaims seems to return all claims (when do they fall off of this call?), so it would be cool to have a way to only get the most recent X amount of days

[evanation]

Hi!
Please, add 'Release' for API_GetGameList.php
and add rom name in hash table for API_GetGameList.php too

[ccreight]

Hi! I was wondering what the best way to get the image for a certain achievement was? I'm currently calling the API to get the achievement of the week, and that works alright, but I'm only able to access the achievement's ID:

achievementOfTheWeek.achievement.id

Not the actual badge's ID, to put that into a URL like this: https://i.retroachievements.org/Badge/341926.png

is there a different way I should be getting the badge image? thank you so much!

[ccreight]

ah nevermind, I found a workaround by calling for the extended game data of the related game and then finding the specific achievement's info!

[ioslife]

If you’re specifically concerned about AotW, #2121 is adding the imageURL to the response

[Gerhard-Wonner]

Please provide a function like API_GetAchievementUnlocks that returns the latest unlocks across all achievements (maybe during the last hour or with pagination). The parameters would be the same as in API_GetAchievementUnlocks, but without the target achievement ID (a). The returned data-format would be the same as the "Unlocks"-table of the response of API_GetAchievementUnlocks, but with the achievement ID as extra column.

This would allow me to keep my unlocks-database up-to-date with a lot less traffic!
Thank you! :-)

[zeroquinc]

That would be a nice addition! Would be nice to see this integrated.

[Gerhard-Wonner]

@wescopeland Have you thought about implementing this suggestion?
It would save a lot of traffic.

[zeroquinc]

Would it be possible to have an endpoint where a user's comments are fetchable?

Usecase: I'm currently doing a Shiny only Pokemon Set and every achievement gets send to a Discord channel as embed.
I always post my SR (Soft Reset) count in the comments when I got the achievement. It would be nice to include this in the Discord message.

[ioslife]

came up with an ideal contract below #2081 (comment)

[taras240]

It would be a good idea to add an endpoint that returns a ranked list with an offset of ±N users relative to the target, as well as the top 10 users. This way, the nearest competitors would be visible.

[ioslife]

New endpoint for retrieving comments for Games and for Achievements.

Contract would be something like:

API_GetComments.php?z={{userName}}&y={{webAPIKey}}&t={{commentableType}}&i={{identifier}}

commentableType: [game, achievement, user]
identifier: [gameID, achievmentID, username, userID, userDisplayName]

return:

{
	[
		user: 'Username',
		datePosted: 'dateTime',
		commentText: 'I am a comment, you can read me in the app now!'
	]
}

[ioslife]

edited after speaking with wes about contract details

[ioslife]

#2552

[joamjoamjoam]

I’m working on a How Long To Beat (think avg time to master based on previous masters) style display to display how long it to take to beat and master a particular achievement set. I can do this with just the achievement unlock times (no PII needed) but currently I have to get all mastery info from API_GetGameRankAndScore then query each user individually to get achievement unlock times to calculate to actual time to beat/master the set.

Is it possible to add each users first unlock date for a set and the last unlock to beat so the total time to master/beat a set can be calculated without needing to check each user individually.

Ideally this would be something you guys do server side and display on the web for each set. Since you guys can look into each users unlocks for each game and filter out any long times between unlocks (user stops playing for a while) etc. maybe even have a poll for each set to vote on a difficulty rating and play through count.

End goal:

Ex.

  {
    "User": "Arekdias",
    "NumAchievements": 15,
    "TotalScore": 219,
    "FirstAward": "2023-06-01 14:43:18"
    "LastAward": "2023-06-07 14:43:18",
    "LastAwardToBeat": "2023-06-07 14:43:18",
    "LastAwardToMaster": "2023-06-07 14:43:18"
  }
  // ...
] 

[joamjoamjoam]

It should be possible to map the retro ratio to a 1/10 difficulty scale too. It might be hard to map the near exponential growth rate of the RR to a useable linear scale though. Maybe some better at math can figure that one out.

It would be nice if the API_GetGameRankAndScore returned all masteries for accurate calculations. The 10 latest masteries isn’t enough data to calculate a good average time to completion especially with some “masteries” being completed in hours or a day in games that avg much higher “time to master” times.

[thatonedood]

Its been over a year since this post, but I was just about to recommend this idea: having average time to beat/master on game pages based on previous users. Either all users can be calculated, or maybe previous 100 users.
Just replying here to hopefully bump this idea. I would love it implemented.

[joamjoamjoam]

Im just coming back to this after a break but it looks like they added the API_GetGameProgression endpoint that shows median unlock times for achievements as well as the entire game. You can see the game averages on the beta game pages (replace game w game2 in the url).

One suggestion i have is to allow sorting games (at the console games list view level) and Achievements (at the game page view level) by average time to master/beat.

[taras240]

If possible, it would be great if the endpoint 'GetGameInfoAndUserProgress' returned the last played game when the gameID parameter is empty.

[zeroquinc]

Would it be possible that the endpoint GetGame returns a PointsTotal and TrueRatioTotal for the total Points and RetroPoints for that game?

[tepiloxtl]

In effect of communication on Discord, I'm putting a request for endpoint for listing set requests made by user. :)

[drisc]

I've opened a PR for this functionality here: #2950

[christianlegge]

Would be super useful for CR purposes to have a public endpoint for downloading a set's files (gameid.json, gameid-notes.json, gameid-rich.txt) without loading the game in emu.

[Jamiras]

Public users should never need direct access to any of the implementation logic. This is a niche internal use case, and could reasonably use the internal APIs.

[christianlegge]

Wes said the same in discord. It'd still be nice if there was a more user-friendly way to get it than basically faking an emu-sourced request, but I understand that's way more work for you guys in basically creating a permissions framework for the API

[likeich]

I'm working on the next big update to Console Launcher that has ROM frontend support. Right now I'm adding the ability to view RetroAchievements. It's been fun to add them since it makes it much more like a game console!

I have already added the achievement views for each game and console. The next feature I'm adding is viewing your followed/following list of friends, if they are active, etc. With this, it would be amazing to eventually message through the RA API as well. I would love to add a basic chat client to Console Launcher to message RA users from within the app.

Platform with All Games	Super Mario World Cheevos

[EtherialNL]

I'm monitoring the New and Updated sets by calling the appropriate GetClaims endpoint.

According to the API documentation, about 1,000 records should be returned, but I received 11,270 records instead—with GameID 3 as the oldest—so it seems all records are being returned.

Would it be possible to add a parameter to define how many records should be returned?

The full response size (when using ClaimKind = 1) is around 4.3 MB, so limiting the number of records could help reduce bandwidth usage.

[biscuitcakes]

I'd love a way to query if an emulator is supported or not without having to launch a game. I may try to tackle it but wanted to post here anyway :)

[adamantike]

It would be great to have information regarding Hubs, like:

• Get Hub information by Hub ID, including Game IDs associated to that hub.
• List Hubs a game is part of (in the Game Extended Details endpoint, or a different one).

[turner485]

It would be great to get to have an endpoint related to the "Just Released" sets.
IE: https://retroachievements.org/claims/completed

[wescopeland]

This should be doable by using the k param on this endpoint: https://api-docs.retroachievements.org/v1/get-claims.html

[turner485]

Amazing thank you @wescopeland .

Is there any end point that points to this page?
https://retroachievements.org/game/33579/hashes?

[Bregann]

It'd be handy for the API_GetUserCompletionProgress endpoint if we could get the total points earned by the user for each game for softcore/hardcode