Documentation for the NetherGames Network REST API

API Host

apiv2.nethergames.org
Rate Limits

Beginning July 29th 2021, we require developers who use the NetherGames API for nonpersonal use (for example, but not limited to, Discord stats bots and statistics tracker websites) to register an application to continue using the API. As such, we have adjusted the rate limit for unauthenticated requests from 1000/hour to 250/hour.
By default, if the Authorization header is omitted or invalid, your IP address is limited to 250 requests every hour. If you're building an application that integrates with our API, please create an API integration. If the Authorization header is set to a valid API token, your IP address is limited to 1000 requests per hour.

API Endpoints

GET /v1/announcements

List the recent game announcements by type.

Request Query Params

The type is required and should be one of "board", "title", or "message".

| Property | Type | Default | Validation |
| -------- | -------- | ------- | ----------- |
| limit | ?integer | 100 | range 1-100 |
| type | string | | |


Successful Response

Board and Message:

An array of content strings.

Title:

An array of objects with the following shape:

| Property | Type |
| -------- | ------- |
| title | string |
| subtitle | string |
| fadeIn | integer |
| duration | integer |
| fadeOut | integer |


GET /v1/announcements/discord

List the recent public Discord announcements.

Request Query Params

| Property | Type | Default | Validation |
| -------- | -------- | ------- | ---------- |
| limit | ?integer | 50 | range 1-50 |


Successful Response

An array of objects with the following shape:

| Property | Type |
| ----------- | ----------------------------------- |
| attachments | array of discord attachment objects |
| author | partial discord user object |
| content | string |
| time | timestamp |


GET /v1/factions/:name

Get a faction by its name.

Successful Response

| Property | Type |
| -------- | ---------------------- |
| id | integer |
| name | string |
| leader | string |
| strength | integer |
| allies | array of faction names |
| officers | array of player names |
| members | array of player names |


GET /v1/guilds/:name

Get a guild by its name.

Successful Response

| Property | Type |
| -------- | --------------------- |
| name | string |
| leader | string |
| maxSize | integer |
| motd | ?string |
| tag | ?string |
| tagColor | ?string/hex code |
| rawTag | ?string |
| officers | array of player names |
| members | array of player names |


GET /v1/leaderboard

List the leaderboard entries for the specified type.

Request Query Params

| Property | Type | Default | Validation |
| -------- | -------- | ------- | ----------------------------- |
| limit | ?integer | 100 | range 1-100 |
| type | Type | | |
| column | Column | | only used for type "game" |
| scope | Scope | | only used for type "factions" |


Type:

- credits
- deaths
- factions
- game
- kdr
- kills
- parkour
- voters
- wins
- xp

Column:

- bb_doubles_wins
- bb_solo_wins
- bb_wins
- bh_wins
- br_wins
- bw_beds_broken
- bw_deaths
- bw_diamonds_collected
- bw_doubles_beds_broken
- bw_doubles_deaths
- bw_doubles_final_kills
- bw_doubles_kills
- bw_doubles_wins
- bw_emeralds_collected
- bw_final_kills
- bw_gold_collected
- bw_iron_collected
- bw_kills
- bw_solo_beds_broken
- bw_solo_deaths
- bw_solo_final_kills
- bw_solo_kills
- bw_solo_wins
- bw_squads_beds_broken
- bw_squads_deaths
- bw_squads_final_kills
- bw_squads_kills
- bw_squads_wins
- bw_trios_beds_broken
- bw_trios_deaths
- bw_trios_final_kills
- bw_trios_kills
- bw_trios_wins
- bw_wins
- ctf_deaths
- ctf_doubles_kills
- ctf_doubles_wins
- ctf_flags_collected
- ctf_flags_returned
- ctf_kills
- ctf_squads_kills
- ctf_squads_wins
- ctf_wins
- duels_arrows_shot
- duels_deaths
- duels_kills
- duels_losses
- duels_melee_hits
- duels_wins
- mm_bow_kills
- mm_classic_deaths
- mm_classic_kills
- mm_classic_wins
- mm_deaths
- mm_infection_deaths
- mm_infection_kills
- mm_infection_wins
- mm_kills
- mm_knife_kills
- mm_throw_knife_kills
- mm_wins
- ms_fails
- ms_successes
- ms_wins
- rc_laps
- rc_wins
- sc_goals
- sc_wins
- sg_deaths
- sg_kills
- sg_wins
- sw_arrows_shot
- sw_blocks_broken
- sw_blocks_placed
- sw_deaths
- sw_doubles_deaths
- sw_doubles_insane_deaths
- sw_doubles_insane_kills
- sw_doubles_kills
- sw_doubles_losses
- sw_doubles_normal_deaths
- sw_doubles_normal_kills
- sw_doubles_wins
- sw_eggs_thrown
- sw_epearls_thrown
- sw_kills
- sw_losses
- sw_solo_deaths
- sw_solo_insane_deaths
- sw_solo_insane_kills
- sw_solo_kills
- sw_solo_losses
- sw_solo_normal_deaths
- sw_solo_normal_kills
- sw_solo_wins
- sw_wins
- tb_arrows_shot
- tb_deaths
- tb_goals
- tb_kills
- tb_losses
- tb_melee_hits
- tb_wins
- tr_blocks_dropped
- tr_losses
- tr_time_record
- tr_wins
- weekly_kills
- weekly_wins

Scope:

- bestStreak
- kills
- streak

Successful Response

An array of objects with the following shape for each type:

Credits:

| Property | Type |
| -------- | ------- |
| player | string |
| credits | integer |


Factions:

If the scope query param is specified, the shape is the following:

| Property | Type |
| ---------------- | ------- |
| player | string |
| {{scope column}} | integer |


Otherwise, top factions are listed:

| Property | Type |
| -------- | ------- |
| name | string |
| leader | string |
| strength | integer |


Game:

| Property | Type |
| --------------- | ------- |
| player | string |
| {{column name}} | integer |


KDR:

| Property | Type |
| -------- | ------- |
| player | string |
| kdr | integer |


Kills:

| Property | Type |
| -------- | ------- |
| player | string |
| kills | integer |


Parkour:

| Property | Type |
| -------- | ------ |
| name | string |
| time | float |


Voters:

| Property | Type |
| -------- | ------- |
| nickname | string |
| votes | integer |


Wins:

| Property | Type |
| -------- | ------- |
| player | string |
| wins | integer |


XP:

| Property | Type |
| -------- | ------- |
| player | string |
| xp | integer |


GET /v1/ping

Get data for the specified Minecraft Bedrock server.

Request Query Params

| Property | Type | Default |
| -------- | ---------------------------- | ------- |
| ip | ip address/hostname (string) | |
| port | integer | 19132 |


Successful Response

Example object:

{
"rinfo": {
"address": "51.89.1.138",
"family": "IPv4",
"port": 19132,
"size": 176
},
"advertise": "MCPE;§r§k§b.§r §o§e§lN§6G§r§7: §bNEW UPDATE EU;440;1.16.210;1785;1790;1364977352939892390;WaterdogPE Proxy;Survival;1;19132;19132;",
"serverId": {
"low": -1469092186,
"high": 317808555,
"unsigned": false
},
"pingId": {
"low": 3110,
"high": 0,
"unsigned": false
},
"game": "MCPE",
"version": "1.16.210",
"name": "§r§k§b.§r §o§e§lN§6G§r§7: §bNEW UPDATE EU",
"cleanName": ". NG: NEW UPDATE EU",
"currentPlayers": "1785",
"maxPlayers": "1790",
"ackId": 3147,
"connected": true
}


GET /v1/players/:username

Get a player by their username.

Successful Response

| Property | Type |
| ------------- | --------------------------- |
| name | string |
| xuid | string |
| bio | ?string |
| guild | ?string |
| level | integer |
| online | boolean |
| statusCredits | integer |
| xp | integer |
| ranks | array of rank names |
| rankColors | array of rank colors |
| tier | ?string |
| tierColor | ?string |
| kills | integer |
| deaths | integer |
| wins | integer |
| losses | integer |
| firstJoin | timestamp |
| firstJoined | ?unix timestamp |
| lastJoin | timestamp |
| lastJoined | unix timestamp |
| lastSeen | string |
| lastServer | string |
| discordData | mixed object |
| winsData | ?mixed object |
| extra | ?mixed object |
| voteStatus | integer |
| factionData | partial player faction data |
| punishments | array of punishment objects |
| warnings | array of warning objects |


GET /v1/players/:username/avatar

Get the specified player's avatar. If the skin does not exist, Steve is returned.

Successful Response

The player's head (64x64) with a Content-Type of image/png.

GET /v1/players/:username/punishments

List the public punishments for the specified player.

Successful Response

An array of objects with the following shape:

| Property | Type |
| -------- | ------- |
| id | integer |
| type | integer |
| reason | string |
| expires | integer |


Type has the following shape:

| Value | Name |
| ----- | ---- |
| 1 | Ban |
| 2 | Mute |


GET /v1/players/:username/skin

Get the specified player's skin. If the skin does not exist, Steve is returned.

Request Query Params

| Property | Type | Default | Description |
| -------- | -------- | ------- | --------------------------------- |
| head | ?boolean | false | Extract the player's head (64x64) |


Successful Response

An image with a Content-Type of image/png.

GET /v1/players/:username/vote-status

Get the vote status for the specified player.

Successful Response

| Property | Type |
| -------- | ------- |
| status | integer |


Status has the following shape:

| State | Value |
| --------- | ----- |
| None | 0 |
| Unclaimed | 1 |
| Claimed | 2 |


GET /v1/players/:username/warnings

List the public warnings for the specified player.

Successful Response

An array of objects with the following shape:

| Property | Type |
| -------- | ------- |
| id | string |
| reason | string |
| time | integer |


POST /v1/players/batch

Batch query for partial player objects.

Request Body

Find players by names:

| Property | Type | Validation |
| -------- | -------- | ---------- |
| names | string[] | size 1-100 |


Find players by ranks:

| Property | Type | Default | Validation |
| -------- | ---------- | ------- | ----------- |
| ranks | string[] | | size 1-100 |
| limit | ?integer | 100 | range 1-100 |
| cursor | ?xuid/null | null | |


ranks can include the following values:

- Admin
- Advisor
- Artist
- Builder
- Crew
- Dev
- Director
- Discord
- Emerald
- Legend
- Mod
- Partner
- Supervisor
- Support
- Tester
- Trainee
- Ultra
- YouTube

Find players by tier:

| Property | Type | Default | Validation |
| -------- | ----------- | ------- | --------------- |
| tier | string/null | | valid tier name |
| limit | ?integer | 100 | range 1-100 |
| cursor | ?xuid/null | null | |


If tier is null, only tierless players are returned. To get the next page, set cursor to the XUID of the last player in the previous response.

tier can be one of the following values:

- Elite
- Eagle
- Guardian
- Gold
- Silver

Successful Response

An array of player objects without the following properties:

- voteStatus
- factionData
- punishments
- warnings

GET /v1/servers

Successful Response

A nested key-value mapping of game stats objects, keyed by a lowercase game type (see GET /v1/servers/meta).

| Property | Type |
| --------- | ----------------- |
| game type | game stats object |


Game Stats Object

Each object contains at least max and count. Some games also contain subtypes, such as Doubles,
Solo, 1v1 and 2v2.

| Property | Type |
| ----------- | ----------------- |
| max | integer |
| count | integer |
| {{subtype}} | game stats object |


Note: In the near future, all game types will be returned as lowercase (Solo will be solo).

GET /v1/servers/meta

Successful Response

A key-value mapping of game types to their full names.

| Property | Type |
| --------- | --------- |
| game type | full name |


Example Response:

{
"AC": "Arcade",
"BB": "Build Battle",
"Beta": "Beta",
"BH": "Block Hunt",
"BR": "Battle Royale",
"BW": "Bedwars",
"Creative": "Creative",
"CTF": "Capture the Flag",
"Duels": "Duels",
"Factions": "Factions",
"Lobby": "Lobby",
"MM": "Murder Mystery",
"MS": "Momma Says",
"RC": "Races",
"Replay": "Replay",
"SB": "Skyblock",
"SC": "Soccer",
"SG": "Survival Games",
"SP": "Spleef",
"SW": "SkyWars",
"TB": "The Bridge",
"TR": "TNT Run",
"UHC": "UHC"
}


GET /v1/servers/settings

Successful Response

| Property | Type |
| -------- | -------- |
| motds | string[] |


GET /v1/stream

Successful Response

| Property | Type | Description |
| --------- | -------------- | ---------------------------------------------------- |
| streaming | boolean | Is NetherGamesNetwork currently streaming on Twitch? |
| stream | ?stream object | Current stream or null if streaming is false. |


Stream Object:

| Property | Type |
| ------------ | ---------------- |
| id | string |
| user | user object |
| game | ?game object |
| type | string |
| title | string |
| viewers | integer |
| startDate | timestamp |
| thumbnailUrl | string |
| tags | array of strings |


User Object:

| Property | Type |
| --------------------- | --------- |
| id | string |
| name | string |
| displayName | string |
| description | string |
| type | string |
| broadcasterType | string |
| profilePictureUrl | string |
| offlinePlaceholderUrl | string |
| views | integer |
| creationDate | timestamp |


Game Object:

| Property | Type |
| --------- | ------ |
| id | string |
| name | string |
| boxArtUrl | string |


Technical Issues

If you believe you may have found an issue with the REST API, please contact NetherGames Support - support@nethergames.org. Your report will be forwarded to the developers.


Questions? Contact our support team here or by clicking the chat button in the bottom right corner.
Was this article helpful?
Cancel
Thank you!