player_id, club_id, and new endpoints please

This follows from discussion in notes, transferring here @bcurtis' request.

1. Having player_id and group_id be guaranteed to be continued to be provided(*) would be of benefit as account names may both be changed and reused, and prior to club_id appearing (perhaps it was always there, and I missed it?) there was no way to track group name changes.

Club name changes are critically important for the many team-based competitions on chess.com, such as TMCL (Team Match Championship League) that @stephen_33 helps run.

(club_id 35246). (OK, https://api.chess.com/pub/club/team-match-championship-league)

Group name changes are not uncommon: France/Deutschland Group changed to France-Deutschland Group to make something easier (I don't recall the details) and Great Viking Warriors changed name temporarily to Asger's Great Viking Warriors and then decided to make the change permanent. A number of Australian city/state teams regularised their names. (To a format I don't like, but hey, wasn't my decision.)

User name changes are not uncommon either, and it is useful to have an unchanging reference when tracking members (who has played in what matches?) if any cached data is involved (and long-lasting groups play a lot of matches).

A consistent player_id is also useful when tracking potential trolls, abusive members and cheats

2. An endpoint to find a member by player_id saves having to stumble across them, or else try to track every active chess.com member and their current profile

3. An endpoint to find a club by club_id would ease running competitions via tools using api.chess.com, as the club_id can be recorded as the competition entrant and competition administrators don't even need to be told of club name changes; they will be obvious.

From the current documentation:

(*)Note: the "player_id" is provided as a convenience to determine when a username has been changed. If you retrieve a Player Profile by the username-based URL linked from a Game or other object, and this new Player Profile has a "player_id" that matches a Profile you previously downloaded, then you can safely assume that this new Profile replaces the old, and all URLs with the previous username will now be found under the new username. This should be an extremely rare occurrence. This "player_id" will never change for a given account, however the future availability of this ID is not guaranteed.

Thanks Giles, that puts the case very well. An endpoint accessed by club_id would be immensely useful & overcome all the problems we experience when admins change the names of their clubs without warning. As we've been told club names being mutable are identifiers that we shouldn't rely on anyway.

So that points to the need for an alternative, in other words the club_id.

At the moment, the only reliable way I know of to track a renamed member is to get a link to one of their games.  This isn't hard if you know of one of their opponents, or if you can find them in a team match or tournament, and occasionally the internet archive can bail you out.

If you can't get a game link, though, you have to try to find them in forums, clubs, etc.

I have a similar solution in mind for tracking clubs even after a name change - use one of their matches to access the team match endpoint which always displays the correct, current club name.

But a club_id endpoint is what's really needed I think.

To formalise the workarounds, can anyone pick a hole in this?

1. For a player, record one game URL and whether they played white or black. You can confirm you have the original player with player_id

2. For a team, record one match URL and either:

    a) Whether they were "team1" or "team2" (I think this is sufficient; it's been stated but I don't think documented that "team1" is the left hand side team in the match display. (Makes sense, but if it's not documented, it's subject to change )

    b) Without documentation that (a) can be relied upon, look up "team1" and "team2". One should match or something's awry.

That we have workarounds isn't as nice as being able to get club information via club_id and player information via player_id.

A solution to the uncertainty of whether a player was W or B, or a team was team1 or team2, is to always pick a game in which they played W or a match in which the team was team1?

At least that's my plan if a club_id isn't available.

I'm really not comfortable that "team1" is always the left hand side and "team2" the right hand side. I'm told "that's how it works" but it's not documented. If "how it works" (how it's implemented) changes, will that unwritten guarantee hold?

I am nit-picking and probably worrying unduly. As one who has had a, ah, "number" of difficult discussions with customers whose applications relied on undocumented behaviour that we changed and really, really, really did not want to change back (too expensive, would require customisation of code from an upstream supplier or something) I get (overly ) nervous when something is not documented.

I would vastly have preferred "team_left" and "team_right" to "team1" and "team2".

End (intended to be friendly) rant.

Fair point in my books & that's something for the developers to confirm?

Perhaps I should note that I was working on a Unix-derived operating system, and yes, some of the code did date back 30 years. I have seen "This may be removed after MM/YY/DDDD" ... where that date was 20 years in the past.

I've seen an absolutely essential change (for standards conformance) go in and break traditional undocumented behaviour.

I also sometimes fought the good fight (and sometimes won!) to say, "No, don't change that. It's worked that way for 20 years, and documented or not, we'll break all sorts of things if you change it. Probably including quite old applications customers are using but have no way to maintain easily if at all, so ... don't." (Of course, using an application you can't maintain is a disaster waiting to happen, but now I'm rambling. Must be too late in my day, even if it's not yet 7:30pm.)

Cheers!

Andrea or @bcurtis did say that the match data is left-to-right, but it's not (to my recollection) in the API documentation.

We've shown we can handle breaking changes; documenting something doesn't make it immutable, just harder if it must be changed some time.

That being the case, using a player's game_id (one selected from their games archive) as an immutable reference is perfectly reliable because their colour of play doesn't change. Pick one in which they played as White & it will always be so.

The same isn't true of a team in a given match however. Other than the team designation (team1/team2), I can't think of any data item within the endpoint that fixes either team name for all time.

Majority of players won't change names, but what a kludge that would be. Better to document that "team1" is always "team1" and preferably that it is also always the challenging team, not the challenged team.

The website shows for some matches which admins arranged the match. If that becomes consistent (I believe we're all on V3 now) that would be a tag: remember the player_id for each team, look up the two and match player_id to your records.

But this is all workarounds. Doable but not IMHO desirable.

"But this is all workarounds. Doable but not IMHO desirable" - I agree & hopefully the developers will provide a much more satisfactory solution.

We have a discord server where everyone must use their chess.com name as nick name, so it is easy to find each other and issue challenges.
I am looking for a solution to track users by player_id in case they change their name, so their nick name would be updated automatically, but I cannot find a way to get the players by ID.

"Majority of players won't change names"
Well, I had 4 changing names in 1 month, so I am not sure if that is still the case.

I see the convoluted workarounds above, but I wonder if there is any new API endpoint that I missed.
This conversation was almost 5 years ago after all...

You can get the player ID in this end point, however C.C have placed a disclaimer that they may move to a different format in the future although no time scales given.

https://api.chess.com/pub/player/{username} 

 "player_id": 41, // the non-changing Chess.com ID of this player

Yes, I know, but I want it the other way around. I want to use the player_ID to find a user. (and that is what this forum topic is about)

As I wrote, if the name changes then I cannot find them otherwise.

Sorry. Not available. You have to keep a record of the ID's and then x-check for a name change.

Great, I have the ID and then the user changes the name. So I know their old name and their ID.

Now, what? I cannot grab the whole chess.com user database to check the ID against all of the users... (and the club in question has almost 4000 members)

Can you grab a game link and get the player names from that?  The game link doesn't change when player names do.

Yes, that is one of the convoluted solutions I read above. To get a game where the user played white and store that instead of the player_ID.

That would mean two things.
One, I cannot do anything if the player has not played any games yet. Lets say only participates in vote chess, or a new member. (this is rare, but still happens).
Two the whole player_ID is useless and chess.com does not have a proper unique key for users (they have but hiding it).

I have checked and even the club member endpoint does not have the player_ID, just the name and when the user joined. If that would have it, it would be a bit easier to solve my problem.
Now I would need to query every user one by one by name to find out if that is the new one. (I am not sure if the chess.com server would be happy for that )

Although I would need to do it only once and just query the new ones after that. Maybe an idea... I just need to build my own database, that I do not realy want to do and could be avoided by a simple get member by player_ID endpoint.