.net
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.

game
The game flavor to fetch, e.g. 8x4 or 12x1 or 9x5, etc. Default is 8x4.
winnable
0 for regular, 1 for the winnable flavors. Default is 0.
start
The zero-based record number to begin at, defaulting to 0.
length
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.
html
1 means return minimally formatted HTML suitable for display in a browser, 0 means return JSON. Default is 0.
raw
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.
column
This is the column number to sort by.
2streak
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:
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.

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.

num
The number of the tournament (viewable from the history scores pages)
html
0 for JSON, 1 for simple HTML. Default is 0.

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.

code
the number of the tournament echoed back
start
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
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.
games
a list of the games in this tournament. We particuarly recommend the JSON for this.
theme
the number of the tournament theme like so:
#theme name
0Quickie
1Masters
2Speedster
3Threat
4Classic Wide
5Traditional
6Freakout
7Masters Prep
8Potluck
9Wide Open
10Narrow Straits
11Standard Stuff
12Super Quickie
13Zany Zero
14Elevens
15All-in-One
16Mini
17Quartets
18Lightning
19Spelunker
20Skeet Shooting
21Twelve of a Kind
22Streaker
23Australian Open
24British Open
25US Open
winner
user who came in first. Sometimes empty because no one played
comment
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
deadly
you only get to try the game once
stats
the number of wins for each game (see the JSON to understand the contents)
results
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:

game
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.
number
the number of the game ranging from 0-32767 inclusive.
difficulty
The difficulty category of this game. Difficulty levels are described in more detail here.
html
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:

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.

User

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:

https://www.freecell.net/f/fcu.p?username=MrFixit&html=1
This returns the following information.

username
Echoes the username passmeter passed via the URL
usercode
The integer uniquely indentifying this user in the system.
createDate
The date the user created the account. Note that many show a date of August 2004 when we first began capturing that information.
lastLoginDate
The last time this user has been seen.
eloRating
The ELO rating of this user.
gameInProgress
Just a flag to indicate whether the user is in an active game.
totalTimeOn
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.

game
The format of the game, e.g. 8x4
winnable
A flag to indicate that the deals have all been verified as winnable.
streak
The current streak in this variant
allTime
The all time highest streak the user has achieved in this variant
play
The number of times the user has played this variant
wins
The number of times the user has won this variant
dailyStreak
The current number of games they've won in the row today (server time).
bestToday
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.
yearStreak
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.
bestThisYear
Similar to the bestToday, their highest streak so far this year.
lastPlayTime
Unix time of their last play
totalTime
Total seconds they've spent playing this variant.
gameInProgress
A flag indicating this variant has an active game.

Daily

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 },
  ...
  ]
}

HotStreak

Results from the daily HotStreak can be fetched via:

https://www.freecell.net/f/fchs.p?date=20200927&html=1&raw=1
date
The date to fetch formatted as yyyyMMdd.
html
Whether to render to simple HTML or default to JSON
raw
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.

https://www.freecell.net/f/fce.p?html=1
(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:

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.

datetime
Unix epoch date and time for when the game was completed
username
nickname of user
columns
number of columns
cells
number of cells
difficulty
difficulty 1-12
game number
unique seed for this game
win/lose
W = win, L = lose
mode
0 = streak, 1 = not scored, 2 = tournament, 3 = blind tournament, 4 = winnable, 5 = HotStreak
elapsed
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.

Summary

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.

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