Working Code

It takes a lot of effort to provide a viable API, and we're only getting started. We are very excited to help you build tools, services, and systems that help the Chess.com world-wide community of chess lovers enjoy and learn more about their favorite game. With your help, the Chess.com community can have all the niche specialty tools and daring massive data-crunchers they could hope for.

Like any business, we need to know that our developers' time is making the biggest impact for our players. If you appreciate this API and would like us to continue active development and support, help us see the impact — tell us what you've built!

This "Working Code" forum is all about things that actually exist and use the API for something useful — these things could be large and complex, or goofy little one-liners from the command line. Let us know how you are using it, and tell us about the players enjoying it. Share URLs or how-tos. Depending on the response, we may also decide to promote the most interesting and useful apps in news articles and app listings.

If you have plans and either the API doesn't provide the data you need or (like all of us) you haven't found the time yet, post a description of your goal in the What Will You Build forum.

Nothing yet -- not even a coherent enough idea to post in "What Will You Build" but when I get started (Real Soon Now, ASAP, ...) some examples would be great to see. Hence this post: please support this thread! I will, as able.

As you are aware I am working on club manager. Till now I was using screenscraping only for myself. With API I will try to maybe give it to friends and maybe later public. But as I am not professional developer, I am a bit worried to put it fully public ... but I will see once more critical APIs are ready and I have more time to build some viable product. 

You can see beta version at http://cm.tode.cz ... if there is some big interest I can create account to somebody who is interested (but as said - at this moment I will really limit it)

@Dale00007, working code always beats an idea in someone's head. One of the guiding principles of open source (if you intend to make your code available) is that it shows something working. If someone is a more proficient programmer than you are and is able to improve it in some way and contribute changes, that's a big "Thanks!" to you and a compliment, not a criticism of your code.

If you want an example of code to be embarrassed about ... well, I know many, but let's say a skunkworks part-time project was chosen by a Fortune 100 company over the "official" solution produced by a team of programmers using man-years of effort should have embarrassed the official project. I doubt it did.

When your customers call and ask for access to "the system you use, not the one that is on the web" because they know the people they call or email can give them immediate, complete answers instead of them working the website for 20 minutes to get out of date information, then you have a problem ...

No code is pretty in all places. Sometimes code made freely available is terrible. But if it shows that something can be done, that might be enough for someone else to go, "Ah! That's how to do it!" and produce an improved replacement.

One of the Berkeley Unix developers at the University of California told the story of one of his contributors: "Well, Robert went away and coded the feature, and said it was 90% done. That only left us the other 90% to do ourselves."

Programmers are like writers; hesitant to show what they've done for fear of criticism. Mostly, people say things like, "Wow, I hadn't thought of that!", "Hey, can I get a copy?" and of course the depressing "Huh? What?" when they're not interested. (I don't breed racehorses, or play golf. Your new golf clubs? Um, yeah ...)

All of us have prototype code. I've worked professionally fixing some of that code that nobody got to rewrite until it was in the hands of tens or hundreds of thousands of customers and the odd problem appeared. Or even several problems.

Basically ... share your code. Anyone who can judge it knows how hard it is to produce good code and will make allowances for knowledge, part time programmers with real jobs to do that they get paid for and such.

It's like writing: beginning novelists are scared to show their writing to anyone. Yet, most of their friends would be saying, "You wrote a novel? Wow! How long did that take you? Can I see it?" We lose focus and worry about what's not perfect and could be better. There's always version 1.1 and sometimes 2.0 to deal with that.

But I'm rambling, it's nearly morning local time, so I should go to sleep.

Don't be shy, now, OK?

Nice story :-) ... I will think about that later on. But first I would really like to get to some version ie 0.99 :-)

Start with 0.50. That's what Dan Bernstein, one of the most accurate programmers I've ever heard of does. More room before 1.0 if you want it.

Here's an example of a perl script that pulls down a member's list of clubs, picks out the human readable name and sorts in "dictionary" order. Probably English "dictionary" order but if someone has a different locale with a different sorting order, please do let me know if it works or not!

Edit:

Much more sensible to store code outside the forum. This script (and other examples) may now be found on github:

https://github.com/cc-skelos/chess-com-perl

https://github.com/cc-skelos/chess-com-perl/releases

OK, figured out how to set up enough git and an account on github to get my perl examples up there. I wouldn't mind at all if a nice SA chose to delete my "Example code moved ..." posts. Regular users can delete the contents of a post, but not remove one in its entirety.

This is my weekend project http://vitomd.com/vue-chess-guardian/  . Answer positional questions from your games or specific users from chess.com. It uses the chess.com API to get the games from the selected user and then ask you 10 questions. I made it in vue.js

@e4Guardian Brilliant! We will play with it for sure!

This is my stats site. https://www.chessalytics.com . Enjoy!

I built a browser extension (works in both Firefox and Chrome) which notifies you when there is a daily game waiting for you, see https://www.chess.com/forum/view/community/chess-notifier-get-chess-com-browser-notifications-on-your-desktop.

Quick list of things I have built. None are polished enough to publish and I make no promises that I will publish them, but in the "Well, I've been using this for weeks or a  couple of months, I guess it works" here goes.

• A script to download a player's archive of games, splitting out rated from unrated (further selection based on rating, rating difference, type of event, specific event, time control and/or chess variant I do later)
• A script to look at the balance of a match, and (for TMCL) note players eligible to be removed due to too high a timeout percentage (and I do wish the timeout percentage were provided to the same precision as the website which I requested elsewhere, but what is there is correct)
• A script to look for team members not signed up for a match who are eligible (e.g. not a member of the other team, and for 960 daily matches that they have a daily 960 rating) [This one I manually massage; it's definitely rough right now. But it works.]
• Find players for recruitment to Team Australia and our city/state teams. I'll post about this one in a separate post; it's probably the most interesting (and is only gradually having the manual steps removed!)

Other things I use less often:

• Find players who are members of two or more specific clubs
• Go through a list of players and report those who are missing (name change, e.g. by support when a name is obscene, or by a player who choses to rename himself/herself) and those whose account is now closed. In both cases I delete them from my records.

The recruitment project for Team Australia and our city/state teams is the most interesting. (I'd prefer, by the way, that I be consulted before this is used in any detail as news or such. That Team Australia (and others like Team Argentina) are using api.chess.com without details, be my guest.)

Recruiting for Team Australia itself is quite simple: the country players endpoint:

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-country-players

is the starting place, giving ~24 hours worth of logins.

Knowing the existing members of Team Australia from the club members endpoint:

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-club-members

lets me figure out who is not a member and might be invited. Naturally I keep a record of whose name I've put forward for invitation so that they are not inundated with invitations.

At this point there are some minor points worth noting:

• Some players think it amusing to choose offensive usernames. I report the ones I consider obscene (lewd typically, religiously offensive once) to support as "abuse" and some are closed and some are forced to change their account name, I am told
• It is sometimes obvious by similarity of names that someone has opened duplicate accounts. I report those too, and believe that typically the user is required to close all but one of the accounts
• Some "entrepreneur" in Australia is, I think, selling "Internet advertising" which includes setting up a free account on chess.com with a company's advertisement in the profile. I report these too. When I notice them.

The real challenge for Team Australia is not the main team, but the city/state teams. For each candidate I therefore look up their profile:

https://www.chess.com/news/view/published-data-api#pubapi-endpoint-player

to get any location information and try to map that to a city or state.

This mapping is manual for each new location I find, and I find several types of "location" information:

• Trivial: "Melbourne, Australia" maps to Team Australia - Melbourne VIC (VIC is the abbreviation for the state of Victoria)
• Simple: "Kew, Australia" maps to the same team, as Kew is a suburb of Melbourne
• Simple: "Parkes" maps to Team Australia - Sydney NSW as Parkes is a town in New South Wales
• Simple but useless: "Your mother's house", "None of your business", "the world", ...
• Unusable: "New York" is likely an Australian in New York, NY, USA and who may have an attachment to one state or another, but they need to be asked; I cannot identify which city/regional team they might be invited to
• Ambiguous: "Surrey Hills" is the name of suburbs in both Melbourne, Victoria and Sydney, New South Wales. Again, this person needs to be asked what city/state team they might be interested in joining.

Since bothering people with inviations when they are already members is undesirable, I also use the team endpoint to get member names for all the city/state teams, and thus (finally!) produce results in several classes:

• Those who are members of Team Autralia and a city team: nothing to do
• Those who are not members of Team Australia or a city team, but I can idetify which city team they should be invited to
• Those who are members of Team Australia but not an identifiable city team
• Those who are members of a city team but not Team Australia
• Those who are not members of Team Australia and for whom I can't work out a location

For the last group, we're mostly doing nothing so far, as the number of names we can identify locations for is enough!

The manal step of recognising a misspelled location or checking the state a town or suburb is in seems unavoidable, but I record all I identify so if someone new uses the same location information they're recognised automatically.

Finally, I post my names in an approrpriate forum and record that I've posted them.

Personally (although the manual bits are irritating) I am very pleased with this little project. It uses three endpoints and requires the cooperation of several people (I am not an administrator of Team Australia, and am only a backup admin for one of the state teams) but we – for the first time! – have a team operating and playing matches representing every state's capital city and run by administrators who "belong" to that city. (For a while one admin was physically located in the UK, but identified as Australian and helped with her home state's team.)

Granted, one of our teams currently has only 19 members, but the Northern Territory's capital Darwin has a population last I checked of about one hundred thousand people. More than 19 of them have chess.com accounts, but not everyone is interested in team matches or daily chess.

I hope some of you find this of interest. As an example of something that would have been ridiculously difficult without api.chess.com, uses three endpoints and some data from outside chess.com (sadly gathered manually as noted) and which has established or revitalised several teams I think it is a #dev success story.

For the future, I plan to finish automating what I can, convert the script so that it may run on a web server and also present the unknown location data there for someone to classify. Astute readers will notice that will take me out of the loop except for operation of the web server.

Hi Skelos,

Thank you for sharing your experience. The public API is really great to support team building, and after a few months using it for recruiting efforts the benefit is huge. My biggest pain is actually the automation of invitations, private messages to players that are in risk of time-overs, etc. I would prefer an API endpoint that could be controlled rather than having to automate the impersonation of a user sending the messages.

The only criticism is that it would be great if you switch to Python. Quite difficult to get Perl hackers these days...

Is it difficult to find perl people these days? I'm out of touch, but perhaps that is the case. My background with perl predates Guido van Rossum's first paper on Python, and it used to be nearly ubiquitous in Unix (later Linux) operations groups and the early web was built with it.

I have not automated the sending of any invitations. Clearly I could; I choose not to, and have not been asked to. The thought about warning players of timeouts is interesting; I understand that you have built something to check for potential timeouts?

Question came up today about players belonging to multiple city teams which play in competitions which have rules about only representing one city per season.

Thus, I knocked up a utility to check that for the Australian city teams. Two endpoints: the club players endpoint obviously, but also the club profile endpoint as I wished to ignore any administrators in multiple teams, as we have some backups helping the smaller teams.

@r000k I did use perl again too. 😈

@r000k you might be interested to know that as an experiment I re-wrote that last script in Python. Pros and cons pretty much as you'd expect. The "requests" library (once I found  it!) is very nice for a HTTP/HTTPS client and has JSON support too. Very nifty.

Otherwise, all the little things: using format() with print(), regular expression access as function calls, yada yada.

Accessing the multi-level JSON data structures was a wash; more concise in perl (and a stronger indication of types with all those $, % and @ that get scattered around) but maybe slower to unpack as you read.

As usual, for a large team I'd rather Python (although I'd grind my teeth at the exceptions) and for a disciplined small team or good individual perl programmer whichever they know better will win. Bad perl code can easily be totally unreadable, but I've seen compiled C code where the compiled code was easier to understand than the source. A bad programmer can make anything unreadable.

I see also (not needed today) that there is an update to Python's database interface. A few years back perl's DBI interface had it all over Python. Now maybe Python has caught up in that area.

An embarrassment of riches, really.

Python's a nice language. A real shame about those exceptions.

[ Having got my mostly off-topic post off my chest I'll shut up now; Python is definitely a sensible choice for access to api.chess.com, but it's not far ahead if at all of perl. I'd not dealt with complex data structures in Python for a while or possibly ever, so it was worth the look. ]