Simple REST API

RESTWhat is this all about? To make it simple, a Representational State Transfer (REST) API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the Hypertext Transfer Protocol (HTTP). That is why REST API can be used practically for any programming language.

Our easy-to-use REST API allows managing a number of features, namely:

  • Retrieving server status information
  • Retrieving server usage statistics
  • Querying latest server and client versions
  • Querying remote channels and clients
  • Downloading remote icons

We’re constantly improving our services so this list will grow over time. All URLs in our REST API have the following base URL:

https://api.planetteamspeak.com/

GET serverstatus/<IP>:<PORT>

This resource will return the last known status of a TeamSpeak 3 Server specified by IP address and port number. The data is gathered directly from the official public list of TS3 Servers so there is no direct communication with your server at all.

Example Request:

GET https://api.planetteamspeak.com/serverstatus/84.200.62.248:9987/

Example Response:

{
  "status": "success",
  "result": {
    "name":           "Planet TeamSpeak",
    "address":        "84.200.62.248:9987",
    "country":        "DE",
    "users":          91,
    "slots":          512,
    "online":         true,
    "password":       false,
    "createchannels": true,
    "premium":        true,
    "hidden":         false,
    "serverquery":    true
  }
}

Example Code:

View on JSFiddle


GET serverhistory/<IP>:<PORT>

This resource will return the usage history of a TeamSpeak 3 Server specified by IP address and port number. All times are UTC. Note that the storage capacity for unclaimed (unregistered) servers is limited to 48 hours to to decrease load on our database backend.

Parameters:

duration
The number of days you want to retrieve based on the current date. You can specify an integer between 1 (default) and 31.
interpolation
Whether or not to interpolate missing values. You can specify an integer. Defaults to false.
imputation
Whether or not to replace missing values with -1. Defaults to false.
padding
Whether or not to pad the current day with future -1 values (requires imputation). Defaults to false.

Example Request:

GET https://api.planetteamspeak.com/serverhistory/84.200.62.248:9987/?duration=1

Example Response:

{
  "status": "success",
  "result": {
    "duration": 1,
    "data": {
      "2014-07-03 00:00:00": 85,
      "2014-07-03 00:15:00": 83,
      "2014-07-03 00:30:00": 74,
      "2014-07-03 00:45:00": 78,
      "2014-07-03 01:00:00": 81,
      "2014-07-03 01:15:00": 76
    }
  }
}

Example Code:

View on JSFiddle


GET updatecheck

This resource will return the version information including build numbers (timestamps of compile time) for the latest TeamSpeak 3 stable releases.

Example Request:

GET https://api.planetteamspeak.com/updatecheck/

Example Response:

{
  "status": "success",
  "result": {
    "clientver": "3.0.16",
    "clientrev": 1407159763,
    "serverver": "3.0.10.3",
    "serverrev": 1388593719
  }
}

Example Code:

View on JSFiddle


GET servericon/<IP>:<PORT> PREMIUM SERVERQUERY

This resource will download and return a remote icon from a TeamSpeak 3 Server specified by IP address and port number. The icon source is encoded as base64 and can be used in data URI schemes.

Note:
In order to utilize this API, you need to claim the specified server and enable ServerQuery connectivity from the Control Panel.

Parameters:

id
The crc32 polynomial of the icon file. This is an unsigned integer equal to the icon ID that is used as a value for the i_icon_id permission.
img
Whether or not to send the result as an image instead of the regular JSON string. Defaults to false.

Example Request:

GET https://api.planetteamspeak.com/servericon/84.200.62.248:9987/?id=1404200104

Example Response:

{
  "status": "success",
  "result": {
    "mime": "image/png",
    "size": 3552,
    "data": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8..."
  }
}

Example Code:

View on JSFiddle


GET servernodes/<IP>:<PORT> PREMIUM SERVERQUERY

This resource will query and return all nodes required to generate a treeview for a TeamSpeak 3 Server specified by IP address and port number. To reduce the ammount of data that needs to be sent, several node properties are stored in a combination of bit flags.

Note:
In order to utilize this API, you need to claim the specified server and enable ServerQuery connectivity from the Control Panel.

Example Request:

GET https://api.planetteamspeak.com/servernodes/84.200.62.248:9987/

Example Response:

{
  "status": "success",
  "result": {
    "data": [
      {
        "ident":    "ts3_s1",
        "parent":   "ts3",
        "children": 14,
        "level":    1,
        "first":    true,
        "last":     false,
        "siblings": [],
        "class":    "server",
        "name":     "Planet TeamSpeak",
        "image":    "server-open",
        "props": {
          "id":       1,
          "icon":     1404200104,
          "welcmsg":  "Welcome to this TeamSpeak 3 Server...",
          "hostmsg":  "",
          "version":  "3.0.11",
          "platform": "FreeBSD",
          "country":  "DE",
          "users":    21,
          "slots":    128,
          "flags":    13
        }
      },
      {
        "ident":    "ts3_c1",
        "parent":   "ts3_s1",
        "children": 1,
        "level":    2,
        "first":    true,
        "last":     false,
        "siblings": [],
        "class":    "channel",
        "name":     "Entrance Area",
        "image":    "channel-open",
        "props": {
          "id":       1,
          "icon":     0,
          "path":     "Entrance Area",
          "topic":    "This is the Default Channel...",
          "codec":    4,
          "users":    1,
          "slots":    128,
          "famusers": 1,
          "famslots": 128,
          "spacer":   "none",
          "flags":    101
        }
      },
      {
        "ident":    "ts3_u1",
        "parent":   "ts3_c1",
        "children": 0,
        "level":    4,
        "first":    true,
        "last":     false,
        "siblings": [
          true
        ],
        "class":    "client",
        "name":     "ScP",
        "image":    "client-idle",
        "props": {
          "id":       11,
          "icon":     2146392738,
          "version":  "3.0.16",
          "platform": "OS X",
          "country":  "DE",
          "awaymesg": "",
          "memberof": [
            {
              "name":  "Owners",
              "icon":  1404200104,
              "order": 1,
              "flags": 48
            }
          ],
          "flags":    0
        }
      }
    ]
  }
}

Example Code:

View on JSFiddle

  • 0x01
    The server is currently online.
    0x02
    The server is protected with a password.
    0x04
    The server is configured to start automatically.
    0x08
    The server is reporting to official server list.
    0x10
    The server nas not been claimed by any user and is asking for an initial privilege key.
  • 0x01
    The channel marked as default.
    0x02
    The channel is protected with a password. Note that the default channel cannot have a password.
    0x04
    The channel is permanent and must be deleted manually.
    0x08
    The channel is semi-permanent and weill be deleted automatically during the next server restart.
    0x10
    The channel is configured to use a music codec (e.g. CELT Mono or Opus Music).
    0x20
    The channel has a needed talk power configured and therefore is moderated.
    0x40
    The channel is subscribed and clients residing in it are visible.
    0x80
    The channel is a spacer intended for cosmetic purposes.
  • 0x01
    The client is currently away.
    0x02
    The client is currently recording.
    0x04
    The client has Channel Commander privileges.
    0x08
    The client has Priority Speaker privileges.
    0x10
    The client has sufficient talk power and therefore is allowed to speak.
    0x20
    The client has insufficient talk power and therefore is not allowed to speak.
    0x40
    The client either has no input device or has its microphone muted.
    0x80
    The client either has no output device or has its speakers muted.
  • 0x01
    The group name is displayed before a client nickname in brackets.
    0x02
    The group name is displayed after a client nickname in brackets.
    0x04
    The group is of type ServerQuery and has access to every virtual server in the TS3 instance.
    0x08
    The group is a regular group and is limited to a single virtual server.
    0x10
    The group is permanent and clients will remain members until they’re removed manually.
    0x20
    The group is a server group. Note that if this bit is not set, it’s a channel group.