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.