Skip to content

API

Jump to bottom
Newcomer1989 edited this page Nov 25, 2020 · 2 revisions

Ranksystem API

General

The API is an interface for third party applications to GET information from a TSN Ranksystem instance. It returns the data as JSON string.
For the moment the API can be used to get information only. We can also imagine (if requested) to make a REST API out of this. This could be used to POST, PUT & DELETE data to the Ranksystem instance.
To be able to use the API of the Ranksystem, you need to create an API key. This is needed for authentication purpose.

Create API key

You can create an API key about the Ranksystem web interface -> Add-ons -> API -> Plus Symbol.
After saving the key, you also got the anchor-symbol to copy the full URL to reach the API.

Example:
https://ts-n.net/ranksystem_dev/api/?apikey=t8c6wvpi9cjc4k1bj9y42t0dtpedfsadtcyjt2xxbybdgg04l1dogxywwvoegsn5

How To use the API

You need to build a GET request.

URL build:
https://domain_to_your_ranksystem.com/sub_folder_if_exists/api/?apikey= [APIKEY] & [Paramater] & [More Paramater]

The output of the API is in JSON string.

Parameters

Available parameters are:

  • groups - Get details about the TeamSpeak servergroups.
  • rankconfig - Get the rankup definition, which contains the assignment of (needed) time to servergroup.
  • server - Get details about the TeamSpeak server.
  • userstats - Get additional statistics about the TeamSpeak user.
  • user - Get details about the TeamSpeak user.

Parameter: Groups

Usage

Get details about the TeamSpeak servergroups.

Example:
https://ts-n.net/ranksystem_dev/api/?apikey=[APIKEY]&groups

A sub parameter is necessary for the groups to be able to get data.

Sub parameters

  • all - Get details about all TeamSpeak user. Result is limited by 100 entries.
  • limit - Define a number that limits the number of results. Maximum value is 1000. Default is 100.
  • order - Define a sorting order. Value of 'sort' param is necessary. Add as value 'asc' for ascending or 'desc' for descending.
  • sgid - Get details about TeamSpeak servergroups by the servergroup TS-database-ID.
  • sgidname - Get details about TeamSpeak servergroups by servergroup name or a part of it.
  • sort - Define a sorting. Available is each column name, which is given back as a result.

Examples

  • All Example: ?apikey=[APIKEY]&groups&all.
  • Limit Example: ?apikey=[APIKEY]&groups&limit=10.
  • Order Example: ?apikey=[APIKEY]&groups&all&sort=sgid&order=asc.
  • Sgid Example: ?apikey=[APIKEY]&groups&sgid=123.
  • Sgidname Example: 1. Filter by servergroup name. ?apikey=[APIKEY]&groups&sgidname=Level01 .
    2. Filter by servergroup name with a percent sign as placeholder. ?apikey=[APIKEY]&groups&sgidname=Level%.
  • Sort Example: 1. Sort by servergroup name. ?apikey=[APIKEY]&groups&all&sort=sgidname.
    2. Sort by TeamSpeak sort-ID. ?apikey=[APIKEY]&groups&all&sort=sortid.

Output

Example JSON output 
{
   "0":{
      "sgidname":"ServerIcon",
      "iconid":"2955756441",
      "icondate":"1430461196",
      "sortid":"0",
      "type":"0",
      "ext":"png",
      "iconpath":".\/tsicons\/servericon.png"
   },
   "1":{
      "sgidname":"Guest Server Query",
      "iconid":"0",
      "icondate":"0",
      "sortid":"0",
      "type":"2",
      "ext":"",
      "iconpath":""
   },
   "2":{
      "sgidname":"Admin Server Query",
      "iconid":"0",
      "icondate":"0",
      "sortid":"0",
      "type":"2",
      "ext":"",
      "iconpath":""
   },
   "3":{
      "sgidname":"Server Admin",
      "iconid":"300",
      "icondate":"0",
      "sortid":"0",
      "type":"0",
      "ext":"png",
      "iconpath":".\/tsicons\/300.png"
   },
   "5029":{
      "sgidname":"Level 81",
      "iconid":"1049849931",
      "icondate":"1484474138",
      "sortid":"1000",
      "type":"1",
      "ext":"png",
      "iconpath":".\/tsicons\/5029.png"
   }
}

Parameter: Rankconfig

Usage

Get the rankup definition, which contains the assignment of (needed) time to servergroup.

Example:
https://ts-n.net/ranksystem_dev/api/?apikey=[APIKEY]&rankconfig

Here are no sub parameters needed.

Output

Example JSON output 
{
   "rankup_time_assess_mode":{
      "mode":"1",
      "mode_desc":"active time"
   },
   "rankup_definition":[
      {
         "grpid":"4950",
         "seconds":"3600"
      },
      {
         "grpid":"4951",
         "seconds":"7200"
      },
      {
         "grpid":"4952",
         "seconds":"10800"
      },
      {
         "grpid":"4953",
         "seconds":"14400"
      },
      {
         "grpid":"4954",
         "seconds":"21600"
      },
      {
         "grpid":"4955",
         "seconds":"28800"
      }
   ]
}

Parameter: Server

Usage

Get details about the TeamSpeak server, see the output tab for a detailed list of data.

Example:
https://ts-n.net/ranksystem_dev/api/?apikey=[APIKEY]&server

Output

Copy of the outpdate on 02/10/2020

Example JSON output 
[
   {
      "total_user":"126",
      "total_online_time":"60383285",
      "total_online_month":"8897466",
      "total_online_week":"1563542",
      "total_active_time":"39276463",
      "total_inactive_time":"21106822",
      "country_nation_name_1":"GB",
      "country_nation_name_2":"DE",
      "country_nation_name_3":"ZA",
      "country_nation_name_4":"NL",
      "country_nation_name_5":"BE",
      "country_nation_1":"53",
      "country_nation_2":"25",
      "country_nation_3":"9",
      "country_nation_4":"6",
      "country_nation_5":"3",
      "country_nation_other":"14",
      "platform_1":"117",
      "platform_2":"3",
      "platform_3":"1",
      "platform_4":"2",
      "platform_5":"0",
      "platform_other":"3",
      "version_name_1":"3.5.3 [Build: 1588756070]",
      "version_name_2":"3.5.2 [Build: 1585812952]",
      "version_name_3":"3.3.2 [Build: 1566767614]",
      "version_name_4":"3.5.0 [Build: 1582117478]",
      "version_name_5":"3.5.1 [Build: 1582118844]",
      "version_1":"86",
      "version_2":"17",
      "version_3":"14",
      "version_4":"2",
      "version_5":"2",
      "version_other":"5",
      "server_status":"1",
      "server_free_slots":"97",
      "server_used_slots":"3",
      "server_channel_amount":"33",
      "server_ping":"18",
      "server_packet_loss":"0.0126",
      "server_bytes_down":"25219715377",
      "server_bytes_up":"68212729933",
      "server_uptime":"5042010",
      "server_id":"1",
      "server_name":"Saly Factory Teamspeak Server",
      "server_pass":"0",
      "server_creation_date":"1589659788",
      "server_platform":"Linux",
      "server_weblist":"1",
      "server_version":"3.12.1 [Build: 1585305527]",
      "user_today":"17",
      "user_week":"38",
      "user_month":"52",
      "user_quarter":"87"
   }
]

Parameter: Userstats

Usage

Get details about the TeamSpeak servergroups.

Example:
https://ts-n.net/ranksystem_dev/api/?apikey=[APIKEY]&userstats

A sub parameter is necessary for the groups to be able to get data.

Sub parameters

  • all - Get details about all TeamSpeak user. Result is limited by 100 entries.
  • limit - Define a number that limits the number of results. Maximum value is 1000. Default is 100.
  • order - Define a sorting order.
  • part - Define, which part of the result you want to get. This is needed, when more then 100 clients are inside the result. At default you will get the first 100 clients. To get the next 100 clients, you will need to ask for part 2
  • sort - Define a sorting. Available is each column name, which is given back as a result.
  • uuid - Get details about TeamSpeak user by unique client ID.

Examples

  • All Example: ?apikey=[APIKEY]&userstats&all.
  • Limit Example: ?apikey=[APIKEY]&userstats&limit=10".
  • Order Example: ?apikey=[APIKEY]&userstats&all&order=asc.
  • Part Example: ?apikey=[APIKEY]&userstats&all&part=2.
  • Sort Examples: 1. Sort by online time of the week. ?apikey=[APIKEY]&userstats&all&sort=count_week.
    2. Sort by idle time of the week. ?apikey=[APIKEY]&userstats&all&sort=(count_week-idle_week).
    3. Sort by online time of the month. userstats&all&sort=count_month .
  • Uuid Example: userstats&uuid=[UUID].

Output

The output for a single user when ?apikey=[APIKEY]&userstats&all is used

Example JSON output 
{
   "++3ZoIIdbbQhmyJoJJmOpI0rhMg=":{
      "removed":"0",
      "count_week":"0",
      "count_month":"0",
      "idle_week":"0",
      "idle_month":"0",
      "achiev_count":"0",
      "total_connections":"1",
      "base64hash":"plonnjkaicbngnlecbjlccgicejjiokeincliemi",
      "client_total_up":"0",
      "client_total_down":"6847",
      "client_description":"",
      "active_week":"0",
      "active_month":"0",
      "last_calculated":"1602192678",
      "uuid":"++3ZoIIdbbQhmyJoJJmOpI0rhMg=",
      "cldbid":"292882",
      "count":"2.000",
      "name":"Crystar",
      "lastseen":"1515614948",
      "grpid":"0",
      "nextup":"3598",
      "idle":"0.000",
      "cldgroup":"45",
      "online":"0",
      "boosttime":"0",
      "rank":"35556",
      "platform":"Windows",
      "nation":"DE",
      "version":"3.1.7 [Build: 1513163251]",
      "firstcon":"1515614946",
      "except":"0",
      "grpsince":"0",
      "cid":"365"
   }
}

Parameter: User

Usage

Get details about the TeamSpeak servergroups.

Example:
https://ts-n.net/ranksystem_dev/api/?apikey=[APIKEY]&user

A sub parameter is necessary for the groups to be able to get data.

Sub parameters

  • all - Get details about all TeamSpeak user. Result is limited by 100 entries.
  • cldbid - Get details about TeamSpeak user by client TS-database ID.
  • limit - Define a number that limits the number of results. Maximum value is 1000. Default is 100.
  • name - Get details about TeamSpeak user by client nickname.
  • online - Get the online TeamSpeak user.
  • order - Define a sorting order. Add value 'asc' for ascending or 'desc' for descending.
  • part - Define, which part of the result you want to get. This is needed, when more then 100 clients are inside the result. At default you will get the first 100 clients. To get the next 100 clients, you will need to ask for part 2.
  • sort - "Define a sorting. Available is each column name, which is given back as a result.
  • uuid - Get details about TeamSpeak user by unique client ID.

Examples

  • All Example: ?apikey=[APIKEY]&userstats&all.
  • cldbid Example: ?apikey=[APIKEY]&user&cldbid=7775.
  • Limit Example: ?apikey=[APIKEY]&user&all&limit=10.
  • name Example: 1. Filter by client nicknam: ?apikey=[APIKEY]&user&name=arriej.
    2. Filter by client nickname with a percent sign as placeholder: ?apikey=[APIKEY]&user&name=%user%.
  • online Example: ?apikey=[APIKEY]&user&online.
  • Order Example: ?apikey=[APIKEY]&userstats&all&order=asc.
  • Part Example: ?apikey=[APIKEY]&user&name=TeamSpeakUser&part=2.
  • Sort Examples: 1. Sort by online time. ?apikey=[APIKEY]&user&all&sort=count.
    2. Sort by active time. ?apikey=[APIKEY]&user&all&sort=(count-idle).
    3. Sort by rank ?apikey=[APIKEY]&user&all&sort=rank`.
  • Uuid Example: ?apikey=[APIKEY]&userstats&uuid=[UUID].

Output

The output for a single user when ?apikey=[APIKEY]&user&uuid=xrTKhT/HDl4ea0WoFDQH2zOpmKg= is used

Example JSON output 
{
   "xrTKhT\/HDl4ea0WoFDQH2zOpmKg=":{
      "cldbid":"7775",
      "count":"32092308.000",
      "name":"Newcomer1989",
      "lastseen":"1606339410",
      "grpid":"5017",
      "nextup":"119082",
      "idle":"13282590.000",
      "cldgroup":"44,1912,4616,5017,5866",
      "online":"1",
      "boosttime":"0",
      "rank":"7",
      "platform":"Windows",
      "nation":"DE",
      "version":"5.0.0-beta33 [Build: 1605693829]",
      "firstcon":"0",
      "except":"0",
      "grpsince":"1602792696",
      "cid":"361"
   }
}
Clone this wiki locally