RFC: Countries

Request For Comments: New country endpoints

As an RFC, we are publishing our plans in the hope that you would provide constructive criticism to help us make it better before it is created. We plan to publish an RFC for each major collection of endpoints.

A common request is to be able to look up players in a country, and players which are active (see this forum thread). This Published-Data API provides only data that has been prepared before you ask for it, so it cannot provide custom searches. These new country endpoints attempt to supply the per-country and active-player lists requested in one data set that should be fast to download for most countries (we estimate that the largest data set, for the USA, would be about 2Mb; most would be a few Kb to download).

This is not intended to replace the Player Stats, such as ratings, timeouts, etc., but only to support certain collection processes that you currently use.

/pub/country/{XX}

Where "XX" is the 2-letter country code. The data response will be:

• "@id" of its own URL
• "code" is the 2-letter country code
• "name" is the English name

Future additions to this country data may include translated names, flag URLs (same as we display on this site), and possibly other data. We do not intended this to be a Wikipedia entry! This is only for the purpose of allowing automated tools to recognize groups of players by self-stated nationality. The Player Profile data format will be updated so that the "country" field is a URL pointing to this endpoint.

/pub/country/{XX}/players

Where "XX" is the 2-letter country code. The response is a simple array named "players", consisting of username-based PlayerProfile URLs of enabled users who have logged in over the past 7 days.

Because this lists URLs, your client should be able to link to each player profile as needed to collect any required information. In the future, based on that URL you will be able to retrieve more player stats.

This list can get large for certain countries with a lot of active players. As such we do not anticipate adding additional player data on this endpoint; you will need to request the relevant data from the Player Profile. You will need to filter the data yourself, to remove players you already have data for.

Both endpoints will update their data no more often than once per day. This is not useful for determining who is online.

Sounds both good and sufficient for checking players flying a country flag but not a member of that country's team. I know when I switched from "International" to showing the Australian flag I received an invitation to Team Australia quite quickly, but who noticed I do not know.

The question is active vs. inactive, and while inactive players (who may not have been logged in for years) are largely uninteresting, this endpoint I think will want to document why only active players are provided. Otherwise I foresee a Frequently Asked Question.

Indeed, if it is not too expensive to provide two endpoints, one for all players and one for active players, I would do that.

That's a good point, @skelos! The queries on the database are straight forward, and if there is demand we can do it.

However, people were often requesting new registrations to see if there are people who they would like to invite to their club (etc.), and because many countries have so many players we need a way to make sure the response size is small enough to be realistically handled.For example, the USA has over 6 million players, and just a list of usernames would be a 70Mb download each time.

One way to break it up would be to time-based paginate the results, like with the game archive — then most developers only need to request the most recent month. But this has the problem that people move! To find people who registered long ago and moved nearby, you would need to request every month back to the beginning, just to check. This becomes complex.

By only listing the active players, we know that people playing games and changing their profile are in that list somewhere, and if you check and update your local records once per week then you can know you have a complete list.

Thanks @bcurtis. No, I don't care to download 70MB to find out who I might invite! Yikes. Your explanation is valuable and I would consider hanging on to it for the eventual documentation.

I'm trying to think when I'd want the full 70MB list and coming up short. Basically I can only think of people doing research and that's very hypothetical. If you're starting a new country team, you don't want hundreds or thousands of people week one anyway as that would lead to chaos.

I see enough chaos. Let me quietly crawl away now and consider sleeping. 3am? Yeah, sleep is reasonable.

Good night!

The 70MB list would only be of interest to someone running some statistics on a large data set.  I'm not sure what statistics they would want that for, though...

Agreed, @MGleason. There are a lot of interesting statistics that we might pull out of the data behind this site, certainly worth exploring at some point. For this API, we are focusing only on providing the data that help developers make things more fun and useful for current players. I think that's the strongest argument for limiting results to people who have logged in over the past week.

@bcurtis - your initial proposal is good and I dont have any comment at this moment. It is exactly what I needed.

Just maybe one information to add to output would be location, so for purpose of city related teams to quickly recognize players ie from Prague without the need of calling all player profiles of all active CZ players.

I know that many club admins would like access to when a member last played for the club and how often. Is that something that could be added to the, "Sort members" function?

@Karnakatz, not really a country feature as it's general to any team. Good idea though as anyone who has compiled that data manually will attest. (Me.)

@bcurtis -- should we re-ask for this functionality in another thread? (And I understand "Yes, please ask elsewhere" does not equal "... and we'll implement it.")

Oops. Sorry, Skelos. Walked into the ladies by mistake. (How embarrassment).

Nah. Just not a programmer. Maybe even not a programmer who has been forced to use programming interfaces that "just grew" like Topsy. For some things, experience counts!

I had dealings with an enterprise directory once, and while this isn't the same (and has a totally different interface) what is associated with what else is not always obvious, and can get very hard to fix if you don't get the original design at least mostly right, so I'm very glad @bcurtis and company are asking questions and I'm happy to offer suggestions. Good ones I hope, but I may only hope!

Definitely the feature is wanted, but it's a characteristic of a team, I think: "Which players have played/not played for us in the last six (weeks|months|matches)" [ lots to think about ].

Or possibly it could be a characteristic of a person: "What teams has this player played for/not played for in the last ...". But my first thought is to associate it with a team. I manage only me as an individual (and keep collecting teams, even if not all of them play as they're admin groups).

As an admin I have (usually) a single team, er, "club" hat on.

Cheers!

We prepared the per-country players listing today, and ran into some storage issues. The spec on that portion should be considered in flux — we will try to get similar information to you, but we will need to do it in a more streamlined way. More info will be posted here as we solve the problems.

@skelos — yes, please do make new feature requests in new forum threads. If the request modifies the proposed endpoints in this RFC thread, then this place is appropriate. New ideas that don't fit ought to go somewhere else where they will ne noticed.

Acknowledged, @bcurtis. I'll review the forums and do some thinking in the (my) morning and post as appropriate. Please ignore the noise here; if I don't ask elsewhere, I shouldn't expect to get. (So I will ask. )

To keep things light and fast, the per-country players-listing has these changes:

• only lists players who have logged in over the previous day; the exact timing is a little fuzzy, but we can guarantee that if you check each day you will observe everyone who is active
• only the usernames are listed, not URLs pointing to the player profile API endpoint; to obtain the profile of players new or otherwise interesting for your purposes, you will need to compose the URL yourself

These endpoints are now available for use. Official documentation will be provided next week.

Thanks @bcurtis. I don't imagine names rather than URLs will be a practical problem; we'll see who and how often hits your APIs to discover what load you need to deal with.

I am using /pub/country/{XX}/players for last 2 days without any issues. For CZ (approx.3500) players is response immediate and easy to process. Thanks.

I have to find some time and start playing with this ... I'm being left behind!

Is there an endpoint that returns the list of all countries' abbreviations?  Just wondering.

If not, perhaps /pub/country could serve this purpose.

Er, won't chess.com have followed some standard for this? I'd be surprised if there wasn't an ISO standard for country codes. Or at least an Internet RFC for top level domains. I could research, but if chess.com have done anything unique then yes, please, a list of country names and abbreviations would be useful. If chess.com is strictly following some standard  it might be better simply to refer to it.