status.tw

Introduction

This is documentation for the REST API of status.tw. Below you will find all possible requests with corresponding parameters and an example of the response. This API focuses on basic information such as the server list, player list, etc. Even though we've added some smaller filters for the queries, you'll have to do more filtering yourself.

Terms of use

Below you will find a few conditions and information for the use of this API. This interface is currently still under development and errors may occur. Please also note that the information provided by this API is collected by crawlers, which also do not always work properly. Likewise, this information is not loaded directly from the Teeworlds servers. So it may take a few minutes until the information is updated accordingly.

  1. Of course this API is only there to read the information, which can be viewed on status.tw. It is not possible to change the data displayed there in any way.
  2. This API has a request limit to protect against attacks. An excessive number of requests in a short time leads to the blocking of the requesting IP address.
  3. There's a lot of work in status.tw. We do not allow you to use this API to copy our service with the given information. The use of this API to display server data on web pages, to create a faster server list in TW clients, to create long-term statistics or similar functions is explicitly desired!

Use of Filters

For some queries it is possible to pass additional filters to the query to limit the result. The possible filters are listed with the respective request. The following is an example of how to use filters.

The name of the filter is appended to the base URL of the request. For the first filter with a ? and for the second filter with a &. In the end it is a normal transfer of parameters in a URL.

Examples:

  • GET https://api.status.tw/servers/?ip=147.135.170.176
  • GET https://api.status.tw/servers/?gametype=dm&map=dm2
  • GET https://api.status.tw/players/?country=276&name=nameless
  • GET https://api.status.tw/bans/?ip=127.0.0.1

Servers
GET https://api.status.tw/servers/

The following query allows you to query the server list and some filters to narrow down the result. The returned servers also contain a list of players on each server.

Request filters

ip:
string IP adress the server needs to have
port:
integer The port the server needs to have
map:
string The map which is currently running
gametype:
string The gametype running
min_clients:
integer Minimum amount of clients on this server (>)
max_clients:
integer Maximimum amount of clients which can play on this server
                                
[
    {
        "ip_addr": "127.0.0.1",
        "port": 8303,
        "version": "0.7.2",
        "name": "status.tw Official Server CTF",
        "map": "ctf1",
        "gametype": "CTF",
        "password": false,
        "num_clients": 2,
        "max_clients": 64,
        "num_players": 2,
        "max_players": 20,
        "hostname": "",     # 0.7 only
        "serverlevel": 1,   # 0.7 only
        "num_bot_players": 2,   # 0.7 only
        "num_bot_spectators": 0,    # 0.7 only
        "players": [
            {
                "name": "MrCosmo",
                "clan": "status.tw",
                "country": -1,
                "score": 666,
                "type": 1   # 0.7 only (ingame is used in 0.6)
            },
            {
                "name": "Mr_Anderson",
                "clan": "teecloud.eu",
                "country": -1,
                "score": 1337,
                "type": 1
            }
        ]
    }
]
                                
                            

Players
GET https://api.status.tw/players/

The following query allows you to query the player list and some filters to narrow down the result. The returned players also contain the information of the server they are currently playing on.

Request filters

name:
string Part included in player name (LIKE %...%)
clan:
string The clan of the player
country:
string The country of the player
                                
[
    {
        "name": "MrCosmo",
        "clan": "status.tw",
        "country": -1,
        "score": 6666,
        "type": 1,
        "server_details": {
            "ip_addr": "127.0.0.1",
            "port": 8303,
            "version": "0.7.2",
            "name": "status.tw Official Server CTF",
            "map": "ctf1",
            "gametype": "CTF",
            "password": false,
            "num_clients": 4,
            "max_clients": 64,
            "num_players": 4,
            "max_players": 20,
            "hostname": "",
            "serverlevel": 1,
            "num_bot_players": 2,
            "num_bot_spectators": 0
        }
    }
]
                                
                            

Clans
GET https://api.status.tw/clans/

The following query allows you to query the clan list and some filters to narrow down the result. Each clan contains a list of all players currently playing under that clantag. The information of these players also contains the server information of the server on which they are currently playing.

                                
[
    {
        "clan": "status.tw",
        "players": [
            {
                "name": "MrCosmo",
                "clan": "status.tw",
                "country": -1,
                "score": 666,
                "type": 1,
                "server_details": {
                    "ip_addr": "127.0.0.1",
                    "port": 8303,
                    "version": "0.7.2",
                    "name": "status.tw Official Server CTF",
                    "map": "ctf1",
                    "gametype": "CTF",
                    "password": false,
                    "num_clients": 4,
                    "max_clients": 64,
                    "num_players": 4,
                    "max_players": 20,
                    "hostname": "",
                    "serverlevel": 1,
                    "num_bot_players": 3,
                    "num_bot_spectators": 0
                }
            }
        ]
    }
]
                                
                            

Bans
GET https://api.status.tw/bans/

The following query allows you to query the list of the current masterserver bans and some filters to narrow down the result.

Request filters

ip:
string The IP address which is banned
                                
[
    {
        "ip_addr": "127.0.0.1:8303",
        "active": 0,
        "reason": "The server was too bad",
        "unbanned": "2019-02-05"
    }
]