All site revenue goes to charity

Data Feeds

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.

Scores Data Feed

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.

The game flavor to fetch, e.g. 8x4 or 12x1 or 9x5, etc. Default is 8x4.
0 for regular, 1 for the winnable flavors. Default is 0.
The zero-based record number to begin at, defaulting to 0.
The chunk size to return, defaulting to 100. The 'start' and 'length' parameters together can be used to page through the data returning manageable chunks with each fetch.
1 means return minimally formatted HTML suitable for display in a browser, 0 means return JSON. Default is 0.
1 means return the raw underlying data as opposed to the human-readable form. For instance, idle time can be returned either as something like "3d" (three days) or as a Unix epoch timestamp of the last play time. Default is 0 for human-formatted data.
This is the column number to sort by.
3alltime streak
4daily streak
5alltime best daily streak
6yearly streak
7plays of this variant
8wins of this variant
9win percentage
10average play time
11average streak length (approximate)
12idle time
13total time playing this variant

The default is 2 (streak).

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:

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.

Tournament Data Feed

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.

The number of the tournament (viewable from the history scores pages)
0 for JSON, 1 for simple HTML. Default is 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.

the number of the tournament echoed back
start time of the tournament represented as a Unix epoch. Lots online about that and lots of tools to convert it to human-readable form (e.g. POSIX localtime). Google search "Unix epoch".
end time as Unix epoch. An epoch is just a count of seconds so substracting end - start gives the duration in seconds of the tournament.
a list of the games in this tournament. We particuarly recommend the JSON for this.
the number of the tournament theme like so:
#theme name
4Classic Wide
7Masters Prep
9Wide Open
10Narrow Straits
11Standard Stuff
12Super Quickie
13Zany Zero
20Skeet Shooting
21Twelve of a Kind
23Australian Open
24British Open
25US Open
user who came in first. Sometimes empty because no one played
Almost always empty. Left over from when we first started tournaments and a winner could write something about the tournament. As we ramped up to more frequent tournaments this became intractable.
noDraft (aka blind)
your can't see other's wins to decide whether or not to tackle a given game
you only get to try the game once
the number of wins for each game (see the JSON to understand the contents)
the players, the number of games they won, and their playing time

Game Statistics

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:

Like the scores feed, the game parameter is the columns by cells describing the game variant, e.g. 8x4 for standard 8 columns 4 cells, or 9x5 for 9 columns and 5 cells.
the number of the game ranging from 0-32767 inclusive.
The difficulty category of this game. Difficulty levels are described in more detail here.
Like the other feeds you receive either JSON (the default) or simple HTML.

An example query asking for statistics on standard 8x4 game 12345 difficulty level 5 in HTML would look like this:


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.


You can fetch detailed info about a user via the user data feed. It returns a handful of fields general to users followed by a list of the users particular scores. Again, we recommend JSON as this data is not flat.

An example URL would be:

This returns the following information.

Echoes the username passmeter passed via the URL
The integer uniquely indentifying this user in the system.
The date the user created the account. Note that many show a date of August 2004 when we first began capturing that information.
The last time this user has been seen.
The ELO rating of this user.
Just a flag to indicate whether the user is in an active game.
Total time in seconds this person has played Freecell.
The following fields are repeated for every game variant the user has played via the games[] array.

The format of the game, e.g. 8x4
A flag to indicate that the deals have all been verified as winnable.
The current streak in this variant
The all time highest streak the user has achieved in this variant
The number of times the user has played this variant
The number of times the user has won this variant
The current number of games they've won in the row today (server time).
The best streak they've had today. For example, maybe they ran up a streak of 20 today but lost it. Their bestToday will be 20 until they pass themselves up.
Their current streak for the current calendar year. For example, maybe they had a streak of 30 last year and have added 20 more this year for a total current streak of 50. The yearly streak will only be 20 because only those games were completed within the current calendar year.
Similar to the bestToday, their highest streak so far this year.
Unix time of their last play
Total seconds they've spent playing this variant.
A flag indicating this variant has an active game.


You can fetch the top 24 for a given date and variant, an example URL being:


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:

The date to fetch formatted as yyyyMMdd.
Whether to render to simple HTML or default to JSON
Simply decides whether to format the starttime field as a full date/time string or to return the Unix epoch.

Elo Ratings

Top 1000 players with the highest Elo ratings.

(No arguments needed, just fetches current list)

Daily Play Logs

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:


For example:


The first line is a header line which describes the columns.

Unix epoch date and time for when the game was completed
nickname of user
number of columns
number of cells
difficulty 1-12
game number
unique seed for this game
W = win, L = lose
0 = streak, 1 = not scored, 2 = tournament, 3 = blind tournament, 4 = winnable, 5 = HotStreak
Elapsed playing time in seconds

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.


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.

All content copyright ©2022 Freecell.net
By using our games you consent to our minimal use of cookies to maintain basic state.
Maintained by Dennis Cronin