Difference between revisions of "Server Status (API)"

Latest revision as of 18:14, 31 August 2012

Implementation Status: Implemented
URI: https://api.kag2d.com/server/ip/IPADDRESS/port/PORT/status
HTTP Verbs Supported: GET
Response Type: JSON dictionary
HTTP Auth Required: No

IPADDRESS is the IPv4 or IPv6 address of the server, PORT is the game port.

Current structure:

• (int) DNcycle: Whether or not the server has the day/night cycle enabled. 0/1 represent boolean. Should always be present.
• (int) DNState: The current daylight/night state. Values are 0-255. Should always be present.
• (int) currentPlayers: The current number of players in the server. Should always be present.
• (string) description: The description of the server (e.g. sv_description). Currently does not exceed 144 characters but may be more in the future. Should always be present.
• (string) firstSeen: ISO 9075 date format indicating when the API first recorded this server. See Server Addresses (API).
  • Note: This is likely soon going to be replaced with a HTTP header. Not sure which one yet.
• (string) gameMode: string representing the game mode. See gameMode (API). Should always be present.
• (int) gameState: 0/1 representing boolean. 0 means the game is in warmup/build time, 1 means the game is running. Should always be present.
• (int) gold: 0/1 representing boolean. 0 is not gold, 1 is gold only. Should always be present.
• (string) lastUpdate: when the API last updated this server.
  • Note: This is very soon going to be replaced with a HTTP Last-Modified header, so please check for that and use it instead if it is present.
• (int) mapH: The height of the current map, in tiles. Should always be present.
• (int) mapW: The width of the current map, in tiles. If this and mapH are both zero, it likely means a map is not loaded/generated yet. Should always be present.
• (int) maxPlayers: The player limit currently set on this server. Should always be present.
• (int) password: 0/1 representing boolean. 0 is no password, 1 means a password is required to enter the server. Should always be present.
• (array) playerList: a list of players in the server as of the lastUpdate/Last-Modified time. Each player in the list is actually a dictionary, the username can be found in the "username" key. Additional keys will likely be added in the future.
  • Note: This is going to be changing to an object type as players have extra data associated with them. Should always be present.
  • Note: The number of items in this list is not guaranteed to match currentPlayers
• (string) serverIPv6Address: The IPv6 address of the server. Not always present as most servers are IPv4-only. See IPv6 and Server Addresses (API). serverIPv6Address or serverIPv4Address will always be present.
• (string) serveriPv4Address: The IPv4 address of the server. Not always present (there will eventually be IPv6-only servers). See Server Addresses (API). serverIPv6Address or serverIPv4Address will always be present.
• (string) serverName: The name of the server.
• (int) serverPort: The port of the server.

Additional keys will be added in the future, possibly to the top level dictionary as well as the serverStatus dictionary. Do not write code which will fail if additional keys are present. Do not write code which will break/crash if one of the above attributes is missing.

Examples

https://api.kag2d.com/server/ip/96.44.143.42/port/50301/status : {

 "serverStatus": {
   "DNCycle": 1, 
   "DNState": 0, 
   "build": 489, 
   "connectable": 1, 
   "currentPlayers": 12, 
   "description": "If you enjoy, consider donating, and get a reward! Go to our thread in the server subforum on forum.kag2d.com for more info", 
   "firstSeen": "2012-07-10 18:26:44", 
   "gameMode": "Capture the Flag!", 
   "gameState": 1, 
   "gold": 1, 
   "lastUpdate": "2012-08-31 17:12:05", 
   "mapH": 100, 
   "mapW": 300, 
   "maxPlayers": 32, 
   "maxSpectatorPlayers": 0, 
   "password": 0, 
   "playerList": [
     {
       "username": "gabriel7080"
     }, 
     {
       "username": "paquinn"
     }, 
     {
       "username": "Zolpy"
     }, 
     {
       "username": "Lucas"
     }, 
     {
       "username": "builderdude1"
     }, 
     {
       "username": "Maverick"
     }, 
     {
       "username": "UnnamedPlayer"
     }, 
     {
       "username": "LostPix"
     }, 
     {
       "username": "Dantedeathhermit"
     }, 
     {
       "username": "bkcat"
     }, 
     {
       "username": "mgakg"
     }, 
     {
       "username": "drworld"
     }
   ], 
   "reservedPlayers": 0, 
   "serverIPv4Address": "96.44.143.42", 
   "serverName": "Official MOLE Server, 32 slot CTF, TX", 
   "serverPort": 50301, 
   "spectatorPlayers": 0
 }

}
https://api.kag2d.com/server/ip/2400:c400::113:212:96:217/port/50301/status : {

 "serverStatus": {
   "DNCycle": 0, 
   "DNState": 0, 
   "build": 458, 
   "connectable": 1, 
   "currentPlayers": 0, 
   "description": "Managed by Lavalord. (Foxodi blame One and Chesse for the name)", 
   "firstSeen": "2012-07-15 01:40:53", 
   "gameMode": "Capture the Flag!", 
   "gameState": 1, 
   "gold": 0, 
   "lastUpdate": "2012-08-04 00:42:15", 
   "mapH": 150, 
   "mapW": 200, 
   "maxPlayers": 24, 
   "maxSpectatorPlayers": 0, 
   "password": 1, 
   "playerList": [], 
   "reservedPlayers": 0, 
   "serverIPv4Address": "113.212.96.217", 
   "serverIPv6Address": "2400:c400::113:212:96:217", 
   "serverName": "CW server", 
   "serverPort": 50301, 
   "spectatorPlayers": 0
 }

}
https://api.kag2d.com/server/ip/67.23.118.185/port/50314/status : {

 "serverStatus": {
   "DNCycle": 1, 
   "DNState": 0, 
   "build": 488, 
   "connectable": 1, 
   "currentPlayers": 0, 
   "description": "Basic FullCTF with unit counters, hosted in the eastern US (Reston, VA)", 
   "firstSeen": "2012-07-10 18:26:49", 
   "gameMode": "Capture the Flag!", 
   "gameState": 1, 
   "gold": 1, 
   "lastUpdate": "2012-08-31 17:14:03", 
   "mapH": 128, 
   "mapW": 200, 
   "maxPlayers": 48, 
   "maxSpectatorPlayers": 0, 
   "password": 0, 
   "playerList": [], 
   "reservedPlayers": 0, 
   "serverIPv4Address": "67.23.118.185", 
   "serverIPv6Address": "2607:fd50:1:91b0::c411", 
   "serverName": "U13 USEast 48 slot FullCTF Gold", 
   "serverPort": 50314, 
   "spectatorPlayers": 0
 }

}