RFC: Display Matches and Tournaments fair play infringements

In the previous months we introduce the recalculation of Matches and Tournaments scores if a player account was closed because of fair play infringiments.

While the recalculation does affect the scores it doesn't affect the game result, so it might be difficult for PubAPI clients to understand the real scores of a Match Board or Tournament Group.

For this reason we are proposing to add some fields to expose the scores without touching the game results, as it happens in the Web counterpart.

Team Matches

Team Match endpoint
"https://api.chess.com/pub/match/{matchId}"

We propose to add a "fair_play_removals" field that will be displayed for each team. It will enumerate the players whose accounts were closed during the match.

Example: (only relevats parts are displayed)

{
  "name":"Test Match",
},
  "teams":{
    "team1":{
      "name":"Group A",
      "players":[
       {
         "username":"player5"
       }
      ],
      "fair_play_removals":[
        "player5"
      ]
    },

    "team2":{
      "name":"Group B",
      "players":[
       {
         "username":"player6"
       }
      ],
      "fair_play_removals":[
      ]
    }
  }
}

Team Match Board endpoint "https://api.chess-dev.com/pub/match/{matchId}/{board}"

We propose to add a "board_scores" that will show scores for the two players:

Example: (only relevats parts are displayed)

{
  "board_scores":[
   "player1": 0.5,
   "player2": 1.5
  ],
  "games":[
    // List of games
  ]
}

Tournaments

Tournament board
"https://api.chess.com/pub/tournament/{url}/{round}/{group}"

We propose to add a "fair_play_removals" field for each team, that will display the list of players whose accounts were closed in the specific tournament's group.

{
  "fair_play_closures":[
    "player4"
  ],
  "games":[
    // List of games
  ],
  "players":[
    {
      "username":"player1",
      "points":4,
      "is_advancing":true
    },
    {
      "username":"player2",
      "points":2,
      "is_advancing":false
    },
    {
      "username":"player3",
      "points":3,
      "is_advancing":false
    },
    {
      "username":"player4",
      "points":3,
      "is_advancing":false
    }
  ]
}

Please leave your comments and proposals below!

Good enhancement.

1. Is the 'board_scores' field actual result or adjusted?

2. Does this affect 'Closed:Abuse' accounts?

I like the board scores in the team match endpoint proposal. I was writing code today to translate all the different result codes and there are quite a number of them!

I trust that the order will be team1, team2 and that that may be relied upon without looking at the games or player names?

Players removed ... not as helpful as it first seems (to me): for something like TMCL or TMCL960, results are final at some date after the match has likely finished. If a player's account is closed for fair play violations after the match is finished but before that particular date, any points the player won are removed and awarded to their opponent except when the opponent timed out, in which case a game result might go from 0:1 by timeout to 0:0 by timeout and account closure for TMCL960 or 1:0 for a penalty point in TMCL matches. (TMCL share names, teams, and some but not all rules. Tricky.) I believe chess.com does not change board scores after a match is finished. (I don't suggest that you should!)

Without any timeouts if black is the player whose account is closed the result might be 2:0 for TMCL as penalty points are applied, no matter what it originally was for that game, and 4:0 in total for the board.

I give the background to show one of my uses for the team match results; there are no real suggestions there but maybe the use case will be useful. (Sorry for the pun.)

For matches in progress the removed users would be more directly useful ... but if I have to handle closures after match completion then I might not use that information anyway, but prefer to maintain a single code path.

What about account closures for abuse?

I help to run a couple of team match competitions so my main interest is in being able to process the results of quite large numbers of team matches, final team scores being adjusted with penalty points awarded for closed accounts (for fair-play violation).

I notice that the match endpoint now includes data on closed accounts (I seem to remember that it didn't at first?), so I'm not entirely clear what this new development adds? From the sample output shown above, it seems to be a list of closed accounts per team but can't that information be derived easily enough from the other data?

That said, the API data now available is a vast improvement on what we had to work with before, trying to scrape useful data from the pages themselves, so keep up the good work! 

The board results addition will help anyone who wants what they see on the website. I hadn't thought about it before, but it is the match data that changes not the game data.

Something I don't know if I've seen yet: if someone times out, then their opponent's account is closed with a fair play tag, what result does the website show for those game(s)?

That aside, Stephen I think you and I will be going through board-by-board and looking at the game results and adjusting on player status. Having the fair play closures to hand may save two per-board profile lookups, which would be nice(*).

(*) Probably deserves its own topic, but latency in delivery of responses seems to be the limiting factor for my accesses.

In TMCL I'm mostly disinterested in individual game results. As long as I can get at the status of each player in a particular team match (either match in progress or finished) then I should have all the information I need to produce adjusted (for Closed: Fair Play accounts) match scores with penalty points awarded.

At the moment the other admins in TMCL seem happy enough to collate such information manually & I'm leaving that part to them. But we come to the crunch in late August when we have to decide the outcomes of all RR matches so that we can post details of the playoffs. I think at that point it's going to be useful to have an automated method of at least double-checking the manual results (or vice-versa?).

To pick up on your suggestion, even more valuable for me would be to have a set of alternative, software generated (adjusted for penalty points) match results. It gives confidence in a set of results if they can be shown to be accurate by two different methods 

Do you think latency might be a problem? I thought the majority of API data was updated at least every 24 hours or more frequently?

In API, Team match published overall team scores are now the adjusted after closures I think. Which correlates with web page.

I'll implement a script as I want one anyway, and would like to be able to calculate in progress TMCL matches.

The latency I mentioned is time from request transmission to receiving the response. Even with a persistent connection (I suppose I have to take a network trace or at least look at in-use port numbers to check that is working) the response time feels slow. "Feels" isn't very good; I should measure. Real Soon Now, I promise.

You are interested in individual game results if you want to give only the penalty and not the game point in the case of a timeout.

As I noted, I'm not sure what the website is doing, but if I had to bet I'd bet fair play closure gives zero to the games for the closed account and one to the games of the opponent ignoring if the opponent timed out or not.

Yes, that's how I understand it as well & ideal for what I'm trying to do.

Dear all,

             thank you for your valuable feedback. 

Let's see if I'm able to explain better why we decided to add those information. We try to tailor PubAPI on your needs, so if you don't find something useful we don't need to change what we have.

Team Matches Scores:

• Games results are not recalculated, so I don't want to change the results in order to not give the wrong feeling that the game score is actually recalculated;
• For this reason it isn't possible for you to calculate the board scores, that's why we added the "board_scores" information;
• Overall scores are already re-calculated, so they are correct. 

Tournament Scores:

• Games results are not recalculated as for Team Matches,
• Group scores are already re-calculated, so they are correct.

So the "board_scores" are useful if you are interested in a specific board.

Fair play removals:

• We do not store the historic status of a Team Match/Tournament player. So the status you see is the actual status of the player. The "fair_play_removals" is aimed at answering this question "Was the player account closed when this Team Match or Tournament was ongoing?". So it isn't directly related to the peculiar Team Match/Tournament you are requesting.

So the "fair_play_removals" are useful only if you want to understand which users' profiles were closed when a Team Match/Tournament was ongoing.

Let me know if this explanation does clarify our choices and if you find these changes useful.

 

I think this is all good: we can get the same data from api.chess.com as we can from the website.

Some of the discussion of use cases involved competitions which do not use the website data but recalculate according to different rules including sometimes penalty points. For those there is sufficient information available and the changes don't make the task harder. (Or easier, but that's not chess.com's problem specifically while so many competitions use slightly different rules.)

Thanks for posting the clarification. I think it helps!

To make things more clear I've opted to display boards results with the names of the users, since it wasn't clear from my first proposal: 

"board_scores":{
"player5":1,
"player6":1
}