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

Here's how you get at that data.

Scores Data Feed

The main feed is the scores feed available at: http://www.freecell.net/f/fcv.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
6plays of this variant
7win percentage
8average play time
9average streak length (approximate)
10idle time
11total 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:
http://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: http://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:

http://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).
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: http://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:

http://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.

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 ©2019 Freecell.net
By using our games you consent to our minimal use of cookies to maintain basic state.
Maintained by Dennis Cronin