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

[Player1041]

Would it be possible to get an endpoint with the Achievement of the Month? Basically the Achievement of the Week endpoint, but with the monthly achievement data opposed to the weekly one.
Additionally, could you add the swaps for both weekly and monthly? :)

[wescopeland]

Unfortunately, achievement of the month is not currently persisted anywhere in the database.

[Player1041]

Ah damn. Would this be something that could be added in the future or is it somewhat out of the question?

[gilramot]

Adding a parameter of count, like in API_GetUserRecentlyPlayedGames, to API_GetUserRecentAchievements would be cool. You can also do it the other way around (get user recently played games by datetime).
I request this feature as I'm trying to make a bash script to autosave the save files to a git repo and make the commit message something meaningful.
Can't do this myself, as I don't have php knowledge and I didn't dive in to the RA databases (maybe I'll learn php and pick it up if nobody'll do it).

[Nelfe80]

Hello,

I'm working on your API with Leaderboard support.

4 endpoints:
public/API/API_GetGameInfoAndUserProgress.php : update including leaderboards
OR/AND
public/API/API_GetLeaderboardCount.php : to get leaderboards from a game

public/API/API_GetLeaderboardRanking.php : to get rank of the user in the specified leaderboard
public/API/API_GetLeaderboardUsersRanking.php : to get leaderboard scores in the specified leaderboard

Source code :
master...Nelfe80:RAWeb:master

(i'm developing a marquee system to display all these retro achievements and leaderboard stats)

Thanks

Best regards

[WedgeSparda]

Hi, could it be possible to get the icon URL for each system in All System response along the name and ID? Not sure if it could be possible to get it in other responses returning the Console Data, like Achievement of the Week.

The idea behind this request is to display the console icons in a client without keeping a local image associated to the console, which can be outdated in case a new console system is added.

Thanks

UPDATE: I manage to make the change myself and here's the PR

[zeroquinc]

Would love this API to include "CumulScore" (RetroPoints): https://api-docs.retroachievements.org/v1/get-user-recent-achievements.html
Would reduce an API call to the designated achievement to fetch the RetroPoints.

The by date and on date already support this.

[zeroquinc]

Ah I understand, well I think my question would be then: could the "TruePoints" be added to this API endpoint?

[wescopeland]

#2278

[zeroquinc]

Legend!

[zeroquinc]

Hi, I saw that it got merged. Any Idea when we can use this? Thanks!

[wescopeland]

We'll probably shoot to do a web release this Thursday.

[JeliBeanMachine]

Would very much appreciate if API_GetGameList.php could be modified so that the response includes the names of any supported game files instead of just the hashes.

For example, instead of:

"Hashes": [
  "9a4961c50952b212666859ea4f5467a2196903ef"
]

you would get:

"SupportedGameFiles": [
  {
    "name": "name.ext",
    "hash": "536516ce06aee351c643a3530ccb06864cae52ba"
  }
]

[wescopeland]

I understand. It would definitely need to be a new endpoint -- we try to avoid breaking changes at all costs.

If you don't mind me asking, could you tell me a little more about your desired use case?

[JeliBeanMachine]

I am looking to filter my library to find files compatible with retroachievements.

[wescopeland]

Got it. One thing I am curious about -- how are you getting the hashes for your library? Are you running the rcheevos hashing algorithm under the hood?

[JeliBeanMachine]

I was using md5sum to get the hashes, but some consoles use a custom hash, in which case it might be helpful to check the file name instead.

[bbtufty]

I second this, having this would be extremely useful to expose. I have the md5 hashes from various .dat files but exposing the filenames would make the comparison simpler without having to scan the files themselves, in the cases where RA uses some custom hash.

For files that require a patch, it would also be nice to return that as well (ideally with the download URL?)

[Gerhard-Wonner]

I would love to calculate the time-effort needed to unlock certain achievements. Therefore it would be great if I could access the time the player played a game until unlocking a certain achievement. It would generally be very interesting to access play-time related data. E. g. timestamps when a session started and when a session ended. Or the overall time a certain user played a certain game.

[wescopeland]

Unfortunately, similar to other services such as PSN and Xbox, I don't believe we'll be able to facilitate this request as there are certain privacy concerns associated with this data.

[Gerhard-Wonner]

OK, that sounds reasonable. Thank you for the quick reply!

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

[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?