Index

Teerank provide a JSON API for any purpose. You are free to use it as much as you want.

If you find any bug, regression or typos in the following documentation, fix it or create an issue in the github issue tracker. This API may change but backward compatibility will be kept at all cost. Hence, if something break on your side after a teerank update, open an issue and it will be fixed as soon as possible.

Our results are compressed, however you can use the following command line to get a nicely formated result:

curl <addr> | python -m json.tool

Use a robust JSON parser and always check the result of your requests, escpecially string size. It is possible that our implementation is buggy or even worse, someone comprised teerank and try to harm you.

Custom types

hexstring

hexstring stands for "hexadecimal string", it is a regular json string, but only contains hexadecimal characters. Hexstrings can be converted to regular string. The purpose of using hexstrings is to avoid forbidden chars in filenames or in URLs.

Hexstrings should always terminate with "00". Converting an hexstring to a regular string is done by converting each pair of hexadecimal digit to a byte. For instance, "6e616d656c6573732074656500" is the hexstring for "nameless tee\0", where "6e" convert to "n", ...

time

Time are encoded using the standard RFC-3339. It provide numerous advantages: fixed length, human readable, and is supported on many platforms and libraries. They looks like the following: "2016-01-19T22:42:31Z"

The lowest possible date is "1970-01-01T00:00:00Z", or unix epoch. This date is used to mark the absence of meaningful value.

About

GEThttp://teerank.com/about.json

FieldTypeExampleDescription
{
"nplayers":unsigned"314"Number of players in the database
"nclans":unsigned"271"Number of clans in the database
"nservers":unsigned"1000"Number of servers in the database
}

Player

GEThttp://teerank.com/players/player_id.json

FieldTypeExampleDescription
{
"name":hexstring"6e616d656c6573732074656500"Player name
"clan":hexstring"00"Player clan
"elo":integer1500Player elo points
"rank":unsigned45678Player rank
"lastseen":time"1970-01-01T00:00:00Z"Last time the player was connected
"server_ip":string"1.2.3.4"Last server IP player was connected to
"server_port":string"8300"Last server port player was connected to
"historic":Historic of elo and rank values
{
"length":unsigned2Number fo records
"epoch":time2016-10-22T01:46:00ZCreation date of the historic
"records":Array of records
[
unsigned0Elapsed time since epoch
integer1500Player elo points
unsigned45678Player rank
]
}
}

GEThttp://teerank.com/players/player_id.json?short

FieldTypeExampleDescription
{
"name":hexstring"6e616d656c6573732074656500"Player name
"clan":hexstring"00"Player clan
"elo":integer1500Player elo points
"rank":unsigned45678Player rank
"lastseen":time"1970-01-01T00:00:00Z"Last time the player was connected
"server_ip":string"1.2.3.4"Last server IP player was connected to
"server_port":string"8300"Last server port player was connected to
}

Player list

GEThttp://teerank.com/players/by-rank.json?p=page_number

GEThttp://teerank.com/players/by-lastseen.json?p=page_number

FieldTypeExampleDescription
{
"length":unsigned1Number of players in the following array
"players":Array of length players
[
{
"name":hexstring"6e616d656c6573732074656500"Player name
"clan":hexstring"00"Player clan
"elo":integer1500Player elo points
"rank":unsigned45678Player rank
"lastseen":time"1970-01-01T00:00:00Z"Last time the player was connected
"server_ip":string"1.2.3.4"IP of the last server the player was playing on (can be empty)
"server_port":string"8300"Port of the last server the player was playing on (can be empty)
}
]
}

Clan

GEThttp://teerank.com/clans/clan_id.json

FieldTypeExampleDescription
{
"name":hexstring"00"Clan name
"nmembers":unsigned3Number of players in the clan
"members":Array of nmembers players name
[
hexstring"6e616d656c6573732074656500"Player name
]
}

Clan list

GEThttp://teerank.com/clans/by-nmembers.json?p=page_number

FieldTypeExampleDescription
{
"length":unsigned1Number of clan names in the following array
"clans":Array of length clan names
[
{
"name":hexstring"00"Clan name
"nmembers":unsigned2Number of members
}
]
}

Server

GEThttp://teerank.com/servers/server_addr.json

FieldTypeExampleDescription
{
"ip":hexstring"192.168.0.1"Server IP (Either IPv4 or IPv6)
"port":hexstring"8300"Server port
"name":hexstring"Vanilla CTF5"Server name
"gametype":hexstring"CTF"Server gametype
"map":hexstring"ctf5"Server map
"lastseen":time"2016-10-01T19:33:01Z"Last time the server was succesfully contacted
"expire":time"2016-10-01T19:33:60Z"Next time the server will be contacted
"num_clients":unsigned3Number of players in the server (including spectators)
"max_clients":unsigned16Maximum number of players (including spectators)
"clients":Array of num_clients players
[
{
"name":hexstring"6e616d656c6573732074656500"Player name
"clan":hexstring"00"Player clan
"score":int5Actual player score (spectator also have a score)
"ingame":booltruefalse if spectating, true if playing
}
]
}

Server list

GEThttp://teerank.com/servers/by-nplayers.json?p=page_number

FieldTypeExampleDescription
{
"length":unsigned3Number of servers in the following array
"servers":Array of length servers
[
"name":string"[xyz] servers"Server name
"gametype":string"CTF"Server gametype
"map":string"ctf1"Server map
"nplayers":unsigned5Number of players in the server
"maxplayers":unsigned16Maximum number of players
]
}