I Made a Rating Comparer With the Chess.com API

Recently I wanted to compare more than two chess.com players accounts and wondered if there was a way to do this with some visual representation like a stacked bar chart (there already exists a comparing page for just two accounts, although I have sometimes struggled to find accounts: https://www.chess.com/stats/compare/PetasnyM). To my surprise, as far as I could find, no resource like this existed. I, being a computer science student, didn't really stop there, though, and instead started experimenting with the chess.com API to create something that could do this.

What I ended up with, I think, is a pretty nifty little tool that uses just JavaScript, HTML, and CSS to compile and illustrate chess.com user ratings, which I'll explain in this short article along with some information on how the chess.com API works and how to tinker with my program.

I will admit that my creation is a little half-baked and was very much an experiment on my end, but maybe some of you fellow web developers and intrigued chess players out there might find some of the more technical aspects kind of interesting or might just like the tool for your own uses. I think that it creates a really nice set of data for groups of chess players. Here's me graphing the chess.com data of some of the current best players in the world:

How to Use My Program

My program is really simple and easy to use. Just find some chess.com players that you want to compare ratings between, insert their usernames one by one into the input area, and click "Add Player."

To change my color thresholds, just use the "Color Thresholds" button, which will open up a color-coded group of inputs for whatever thresholds you think will be best for displaying your data.

When you enter a username, what's generated is a row on a table with their username, date joined, time since last online, bullet rating, blitz rating, rapid rating, and average chess.com rating. There is also a graph graphing their bullet, blitz, and rapid ratings. When you hover over the graphed data, you can also find more particulars, like their best rating in that time format on the platform.

If you want to skip past all of the technical stuff and just use my tool, it's code is linked at the bottom of the article. You can just download the folder and open "compare.html" locally.

Code Stuff for Nerds

In JavaScript, connecting to and using the chess.com API was really straightforward. The chess.com API can find some player information using links like "https://api.chess.com/pub/player/username" ("username" of course being a placeholder for an actual username). To find statistics on that player (which is what I was looking for), you can use "https://api.chess.com/pub/player/username/stats". When you just open those links online, you can see the JSON object that you would be accessing through the link (if you don't know what a JSON object is, the super-short explanation is that it is a way of storing information in a tidy format). I don't want to drone on too long about the chess.com API but if you want to learn more, chess.com has published documentation that's very useful (https://www.chess.com/news/view/published-data-api).

To actually gather this response into a useful variable, you need to do three things:

1. Call on the API using the JavaScript fetch() function, which can take a link and return the response.
2. Receive the response as JSON.
3. Set a variable equal to the JSON object (which isn't always necessary depending on what you are doing).

My code, following this three-step process, was the following:

   var userData;

   await fetch('https://api.chess.com/pub/player/' + username)

      .then(response => response.json()) // receiving the response as JSON

      .then(data => {userData = data}) // setting a temp. var to the JSON object

Something incredibly similar was used to access the "/stats" object. You might notice the await statement in there and wonder what that's for. This is because JavaScript doesn't necessarily run in the order of the writing of your program, and you need to prevent other code that relies on a variable being set here from running while this API call is still processing. Calling on an API will often take longer than your local code, and you need to put in special safeguards to prevent your local script from trying to run code it can't yet.

The proper term for the idea I described above is asynchronous code, and here is this really nice article better going over all of the details to properly navigate this in JavaScript: https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Async_JS/Introducing. If you like video tutorials, @dseanhd on YouTube has created this specifically for playing with the chess.com API with JS: https://www.youtube.com/watch?v=a_8gON3DK8A&t=674s.

I used the above ideas in a function that I could call for this data, which I called setChessData(). I also slimmed down what is returned to what I used in the program by defining a return object with only some of the data. To just get a link to their profile picture, for example, I had to set a section of that return variable to userData.avatar. To get your own data by only lightly modifying my code, you can read up on what you can access on the chess.com API and use paths like .avatar or (for my stats variable) .chess_rapid.last.rating.

Finally, I used that data to generate HTML for my actual webpage and actually put what I created on the webpage using the simple old-school method:

document.getElementByID("example_element").innerHTML = "example generated HTML";

This is also stuff that you would need to edit to get new data to be visible on the page. There were some CSS tricks too to get the graph working, which may have been simpler if I had just created it from one of the many libraries for graphs out there. However, because I set up with just divs and an HTML grid, I was able to add a hover effect allowing you to see some more detailed information on a specific bar in the graph:

To be honest, there is a lot of technical stuff regarding the program itself that I just don't think that I can really get into in this article. Hopefully, I covered enough and in simple enough language that the people who were interested (and maybe those who weren't) might have a good start on understanding what I created and how to make their own JavaScript projects using chess.com's really nice API. It is one of those tools that I feel just kind of goes underused considering how useful it is and how much potential there is for creating programs around it.

Conclusion

I hope that this tool might be useful to someone and/or inspire people to create their own programs. I know there are so many better developers than me out there that could really create something that would make this pale by comparison. Honestly, I didn't put that much work into my little rating-comparing tool and was impressed by how straightforward and easy everything was.

If you want to see more articles on chess-related programming, follow me below. I have other project ideas that I think could be a lot of fun. If you have something to add, be sure to add a comment below.

Till next time, Devin Knecht

Link to Code for my Rating Comparison Tool: https://github.com/hiddenInt2/chess.com_ratings_compare.git