Three feeds provide nearly direct access to the site's database. With the exception of email/password info, everything is accessible. You can pull down all the data and load it into your own database, providing whatever queries or views are of interest.
This site generates quite an interesting flow of data around all the Freecell activity here.
Most of the data is available via a simple JSON/HTML feeds. You can specify the parameters either via the URL or via a JSON POST payload.
This section is targeted for software developers and fairly web-savvy folks so if you don't understand it, it's probably not for you. Note: the raw data is what comes out of the operation of the site and the current score keeping. As you extend the views of scores you will probably want to re-scrupt the data to your own purposes in your local database and just use the feeds to keep that roughly in sync.
Here's how you get at that data.
The main feed is the scores feed available at: https://www.freecell.net/f/fcv2.p
Hitting that directly will return a chunk of JSON to your browser. You may specify a number of parameters to fetch the particular data of interest.
2 | streak |
3 | alltime streak |
4 | daily streak |
5 | alltime best daily streak |
6 | yearly streak |
7 | plays of this variant |
8 | wins of this variant |
9 | win percentage |
10 | average play time |
11 | average streak length (approximate) |
12 | idle time |
13 | total time playing this variant |
Some of the column sorts include filters to the entire data set is not returned. If you're fetching for external analysis you'll probably want to sort on a column which does not limit the data set by date. So avoid the "streaks" (2) column as that only returns players who've got active streaks within the last two weeks.
An example URL using URL parameters would be like so:
https://www.freecell.net/f/fcv.p?game=7x4&column=3&html=1
Or you could send the same parameters in the body of a JSON POST:
{ "game": "7x4", "winnable": 0, "column": 3, "html": 1 }(Although obviously if you're sending JSON you're probably not going to ask for HTML)
The data is returned in the order that you see it displayed on the scores page. The first column is the rank, the second is the player name, and the rest are as stated above in the column sort description.
Finally, and perhaps obviously, be judicious in the use of the API as it does ask for work from the database. If I see too many requests coming too fast such that it might impact regular users I'll block the IP address.
Similarly all the tournament data is available from a feed so you can build your own analytics or views on the data.
The tournament data feed URL is: https://www.freecell.net/f/fct.p
Like the scores feed above, hitting that directly will return a chunk of JSON to your browser. There are only two parameters to this one.
Example:
https://www.freecell.net/f/fct.p?num=210012&html=0
We would particuarly recommend the JSON flavor here as the data returned is not flat but contains data structures with data structures. The JSON is much more capable of representing that in a machine-friendly way. There are plenty of tools in all languages to load, parse, and work with JSON.
Most of the fields are self-explanatory but we'll describe them briefly.
# | theme name |
---|---|
0 | Quickie |
1 | Masters |
2 | Speedster |
3 | Threat |
4 | Classic Wide |
5 | Traditional |
6 | Freakout |
7 | Masters Prep |
8 | Potluck |
9 | Wide Open |
10 | Narrow Straits |
11 | Standard Stuff |
12 | Super Quickie |
13 | Zany Zero |
14 | Elevens |
15 | All-in-One |
16 | Mini |
17 | Quartets |
18 | Lightning |
19 | Spelunker |
20 | Skeet Shooting |
21 | Twelve of a Kind |
22 | Streaker |
23 | Australian Open |
24 | British Open |
25 | US Open |
We keep very rudimentary stats on each individual game so you can assess popularity and difficulty.
The game stats data feed URL is: https://www.freecell.net/f/fcg.p
This feed accepts four parameters:
An example query asking for statistics on standard 8x4 game 12345 difficulty level 5 in HTML would look like this:
https://www.freecell.net/f/fcg.p?game=8x4&number=12345&difficulty=5&html=1
Eventually we'll be providing a "last play time" field as well as some other data on each game. You'll be able to use the "last play time" field to only re-fetch the data which has changed obviating the need for a full slurp.
And again, as noted above, be judicious in the use of the API as it does ask for work from the database. If you need to do an automated pull of this data, schedule it for "off hours" in the USA, maybe around 3AM or so.
An example URL would be:
https://www.freecell.net/f/fcu.p?username=MrFixit&html=1This returns the following information.
You can fetch the top 24 for a given date and variant, an example URL being:
https://www.freecell.net/f/fcd.p?date=20200416&game=8x4&html=1
This simply returns an array of users and their streaks in order for the specified date. If less than 24 people played that variant that day, the list will be shorter. If more played it will be truncated. As with all feeds you can specify either JSON or HTML.
An example JSON return will look something like:
{ "winners": [ { "user": "Ladycat2","streak": 120 }, { "user": "tk01","streak": 107 }, { "user": "Turbo_hub3","streak": 106 }, { "user": "Loki","streak": 100 }, ... ] }
Results from the daily HotStreak can be fetched via:
https://www.freecell.net/f/fchs.p?date=20200927&html=1&raw=1
yyyyMMdd
.
Top 1000 players with the highest Elo ratings.
https://www.freecell.net/f/fce.p?html=1(No arguments needed, just fetches current list)
You can access results of every game played each day starting 9/13/2021. The files are in simple CSV format so you can process them without any special programming knowledge using a spreadsheet program.
The name of the file for a particular day is:
https://www.freecell.net/db/play/[year]/[month][day].csv
For example:
https://freecell.net/db/play/2021/0912.csv
The first line is a header line which describes the columns.
Cellmate offers these possible expressions to convert datetime for use in a spreadsheet:
=(A2/86400)+DATE(1970,1,1) which converts to readable UTC =(A2-5*3600)/86400+DATE(1970,1,1) which converts to server time EST (or -4 for dst)
The complete file will appear upon completion of a day's play.
Almost every language these days (except maybe FORTRAN) has JSON support. And there are lots of tools online to display JSON in a human-readable format, e.g.
https://jsonformatter.org/json-pretty-print
Just search online for "JSON prettifier".
And at the risk of repeating myself, be judicious in your use of these APIs. Consider pacing your requests so you don't impact game players. If this starts to negatively impact the player experience I'll have to take action, possibly banning IP address or similar.