Json API
333networks has a Json API. With this API, it is possible to obtain server lists and specific server information for your own banners, ubrowser or other application.
Permission & Terms of Use
The following permissions and conditions are in effect for making use of the Json API:
You are allowed to access our API with any application and/or script, self-made or not, to obtain our server lists and server information on the condition that somewhere, anywhere visible in your application or script you mention that the information is obtained from 333networks. Monetisation of 333networks data (and bandwidth) is not allowed without prior, explicit permission from 333networks.
You are not allowed to flood the API with requests or query our API continuously or with a short interval. If you draw too much network traffic from 333networks, we consider this flooding and will terminate your ability to query our API. Server information is updated every 5 minutes, there is no point in requesting information at a faster rate as there will be no new information available.
Intended use: use the serverlist request to get show a list of all servers. After loading the list, your visitors/users can select a single server to display detailed information. Do NOT use the serverlist to immediately show detailed information for ALL servers, this causes a ludicrous amount of information requests and will get you excluded from our API. Not sure whether you are doing it right? Contact us!
Use
The Json API consists of three functions to query for information. The methods occur over HTTP and are presented as Json data. The first function requests the "Message of the Day", often used to make announcements about the game. The second method returns a list of servers and can be manipulated by gamename. The third method returns detailed server information for an individual server.
Message of the Day
It is possible to pull announcements from the 333networks Json API with the motd command. This command returns an html string with the current 333networks announcements for the selected gamename. This string is suitable for direct JQuery's .html() function. Additionally, it contains the amount of servers and players as described for the serverlist. This method can be used to announce service messages.
Serverlist
With the API you can pull a serverlist directly from the masterserver. The API applies the following regex to process your request:
In this regex, ([\w]{1,20}) refers to the gamename. This is the abbreviation that every game specifies in their masterserver protocol. A comprehensive list of gamenames is found on the games page by looking at the last part of the URL.
It is also possible to provide GET information in the url. Allowed options are:
- s - sort by country, hostname, gametype, ip, hostport, numplayers and mapname.
- o - sorting order: 'a' for ascending and 'd' for descending.
- r - number of results. Defaults to 50 if not specified. Minimum 1, maximum 1000.
- p - page. Show the specified page with results. Total number of entries is included in the result.
- q - search query. Identical to the search query on the servers page. Maximum query length is 90 characters.
- gametype - filter by gametype using provided string. Maximum length 90 characters.
- hostname - filter by server name using provided string. Maximum length 90 characters.
- mapname - filter by map name or map title using provided string. Maximum length 90 characters.
- country - filter by country code (2 letter ISO 3166 code).
Note that these are wrap-around filters; all results that contain the provided string are returned.
Serverlist request examples:
The following examples have different outcomes. In the first example, we request a serverlist of all servers, regardless of type and/or name. The second example requests only servers of the game Unreal. In the last example, we request a serverlist with the gamename 333networks, with only 2 results per page, page 1 and with the search word master.
https://master.333networks.com/json/unreal
https://master.333networks.com/json/333networks?r=2&p=1&q=master
Serverlist result examples:
The API returns Json data in the following format, using the third request as an example. This is example data and may vary from what you receive when performing the same query.
[
[
{
"id":1990,
"ip":"::ffff:84.83.176.234"
"hostport":28900,
"hostname":"master.333networks.com (333networks MasterServer)",
"gamename":"333networks",
"gametype":"MasterServer",
"label":"333networks Masterserver",
"country":"NL",
"numplayers":15,
"maxplayers":2966,
"maptitle":null,
"mapname":"333networks",
"dt_added":1616895602,
"dt_updated":1621019250,
},
{
"id":1117,
"ip":"::ffff:162.154.33.129",
"hostport":28900
"hostname":"master.gonespy.com",
"gamename":"333networks",
"gametype":"Masterserver",
"label":"333networks Masterserver",
"country":"US",
"numplayers":5,
"maxplayers":847,
"maptitle":"",
"mapname":"333networks",
"dt_added":1616593343,
"dt_updated":1621019247,
}
],
{
"players":20,
"total":5
}
]The result contains an array of server entries and the total amount of entries. In this case, that is 2 entries listed and 5 total entries, implying that there is one more server not shown or on a next page. With the specified number of results specified by the user and the total amount of servers provided by the API, you can calculate how many pages there are to be specified. If applicable, it also shows the current number of players that are currently in the selected servers. Every server entry has a number of unsorted keywords. Timestamps are linux epoch, in UTC.
The available keywords that are returned by the API are:
There are more keywords available for individual servers. Detailed information about a server is obtained with the individual request as described below. Keywords of both requests are described in the tables below.
Server details
Your application or script can also request detailed information for a single server. This is done in a similar way as requesting a server list. The following general regex is used by 333networks:
This restricts requests to the correct url with a gamename ([\w]{1,20}) and an IP:port (d{1,3}.d{1,3}.d{1,3}.d{1,3}):(d{1,5}) for IPv4 addresses and numerical port number. There are no additional query options or GET options. It is possible that the gamename specified does not match the gamename as stored in our database. The result will include the correct gamename that was specified in our database.
The following example requests detailed information by IP address and hostport.
Server details request:
Server details result:
The API returns Json data in the following format, using the requests above as an example. This is example data and may vary from what you receive when performing the same query.
{
"id":3,
"ip":"::ffff:45.74.100.250",
"hostport":10205,
"mapname":"DXMP_iceworld2",
"adminname":"Canna the visionary l Disciple Derp191 and RoninMastaFX",
"hostname":"~Canna's Buddhist Server~",
"mapurl":"/map/default/333networks.jpg",
"gamever":"1100",
"gametype":"CDX BDM",
"gamename":"deusex",
"country":"CA",
"dt_updated":1621022768,
"player_0":
{
"sid":3,
"name":"Dark191",
"team":"0",
"frags":8,
"mesh":"cmJCDenton",
"skin":"None",
"face":""
"ping":63,
"dt_player":1621022768,
"misc":"",
},
"player_1":
{
"sid":3,
"name":"Anya",
"team":"0",
"frags":12,
"mesh":"cmJCDenton",
"skin":"None",
"face":""
"ping":54,
"dt_player":1621022768,
"misc":"",
},
}The result has a single entry of parameters with a number of unsorted keywords. The available keywords are in addition to the keywords are specified in multiple tables below.
The player object player_n represent the players in the server. This is a Json object as part of the larger object above. The available keywords are specified in the table below.
Error codes:
It is possible that a query is malformed, outdated or simply invalid. The Json API reports these occurrences with an error code and where possible additional information. When a problem occurs the errorvalue is set from null to 1. The in value provides a shorthand description of where or during what operation the query failed. Additional fields may be provided with specific errors. The following situations are handled.
| Situation | Returned values | Description |
|---|---|---|
| Internal error (500) | error => 1 in => 'internal_error' internal => 'detailed report' | The internal field is only shown if enabled on the masterserver. |
| Incorrect URL formatting | error => 1 in => 'url_format' | The query or URL have the wrong format or contain invalid characters. Verify that your gamename and server address are correctly parsed. |
| Query options | error => 1 in => 'options' options => [array of correct options] | One or more query options do not meet the required template or criteria. See section "Serverlist" above for requirements. The options field contains an array of options and values that are accepted in the current query. |
| Not in database | error => 1 in => 'not_in_db' ip => 'IP-address' port => 'port number' | The combination of provided IP-address and port were not found in the database. The provided IP-address and port are provided back for user feedback or verification that the intended address was entered correctly. |
Keyword reference
Values, type and descriptions of fields that are returned by the Json API:
Server identifier information
| Value | Type | Description |
|---|---|---|
| id | int | gameserver ID in list database |
| sid | int | reference ID for detailed information |
| ip | text | server IP address (in IPv4 format) |
| queryport | int | UDP status query port |
| hostport | int | hostport to join the server |
| hostname | text | name of the specific server |
| country | text | 2-letter country code where the server is hosted |
| location | text | GameSpy regional indication (continent index or 0 for world) |
Server flags & datetime
| Value | Type | Description |
|---|---|---|
| f_protocol | int | protocol index to distinguish between GameSpy v0 and others |
| f_blacklist | int | server blacklisted? |
| f_auth | int | authenticated response to the secure/validate challenge? |
| f_direct | int | direct beacon to the masterserver? |
| dt_added | long | UTC epoch time that the server was added |
| dt_beacon | long | UTC epoch time that the server sent a heartbeat |
| dt_sync | long | UTC epoch time that the server was last synced from another masterserver |
| dt_updated | long | UTC epoch time that the server information was updated |
| dt_serverinfo | long | UTC epoch time that the detailed server information was updated |
Gamedata
| Value | Type | Description |
|---|---|---|
| gamename | text | gamename of the server |
| label | text | comprehensible game title associated with gamename |
| gamever | text | game version of the server |
| minnetver | text | minimal required game version to join |
Game settings (detailed information)
| Value | Type | Description |
|---|---|---|
| listenserver | text | dedicated server indication |
| adminname | text | server administrator's name |
| adminemail | text | server administrator's contact information |
| password | text | passworded or non-public server |
| gametype | text | type of game: capture the flag, deathmatch, assault and more |
| gamestyle | text | in-game playing style |
| changelevels | text | automatically change levels after match end |
| mapurl | text | direct url of the map thumbnail relative from this site's domain |
| mapname | text | filename of current map |
| maptitle | text | title or description of current map |
| minplayers | int | minimum number of players to start the game |
| numplayers | int | current number of players |
| maxplayers | int | maximum number of players simultaneously allowed on the server |
| botskill | text | skill level of bots |
| balanceteams | text | team balancing on join |
| playersbalanceteams | text | players can toggle automatic team balancing |
| friendlyfire | text | friendly fire rate |
| maxteams | text | maximum number of teams |
| timelimit | text | time limit per match |
| goalteamscore | text | score limit per match |
| fraglimit | text | score limit per deathmatch |
| mutators | text | comma-separated mutator/mod list |
| misc | text | miscellaneous server attributes (reserved) |
| player_# | object | player information as Json object for player #, see table below |
Player information
| Value | Type | Description |
|---|---|---|
| sid | int | associated server ID (per player) |
| name | text | player display name |
| team | text | player indication as team number, color code or text string |
| frags | int | number of frags or points |
| mesh | text | player model / mesh |
| skin | text | player body texture |
| face | text | player facial texture |
| ping | int | player ping |
| misc | text | miscellaneous player attributes (reserved) |
| dt_player | long | UTC epoch time that the player information was updated |
Error codes
| Value | Type | Description |
|---|---|---|
| error | int | indication that an error occurred |
| in | text | handler indication where error occurred |
| internal | text | when enabled on the server, a stacktrace or report of the error |
| options | object | query options that were provided when the error occurred |
Feedback
We wrote the Json API with the intention to make the 333networks masterserver data as accessible as possible. If you feel that any functionality is missing or incorrectly shared, do not hesitate to contact us to provide feedback. Additionally, we request that you follow the advice on usage as we described under the Terms of Use on top of this page, so we can keep providing this API.