API
Accessing the API
The API can be accessed through the URL api.earthmc.net/v4. It provides data in JSON format.
Some things to keep in mind when using the API:
- Some data is placed in arrays to ensure order is maintained when creating the JSON, namely coordinates and permissions. Their order corresponds to their in-game order.
- Data is omitted if it does not exist. For example, if a town is not in a nation it will not show the "nation" key. This is to save on data transferred and to make handling of non-existent values consistent, it is recommended you use try-catch or your language of choice's equivalent when handling any data that may not be present.
- Prior version endpoint functionality is maintained for limited time when a new API version releases, version 1 and 2 of the API were disabled on January 14, 2025.
- Players may opt out of having their data included in the API, in which case their data will not appear in most endpoints.
Opt-out
You can opt out of most of your data being included in the API using the '/api opt-out' command.
API Keys
You can create an API key for your minecraft account using the /api key create command. It is recommended you never share your key
Your API key allows you:
- to connect to the server's SSE
/eventsendpoint - to query your own resident data even if you have opted out (other users will still not be able to)
- to fetch data of all shops you own at the server's
/shopendpoint
Endpoints
Server
Accessed at https://api.earthmc.net/v4/
The following is an example of the response to a GET request to the above URL.
{
"version": "1.19.4", // The server's current version as a string
"moonPhase": "LAST_QUARTER", // The moon's current phase (https://jd.papermc.io/paper/1.20/io/papermc/paper/world/MoonPhase.html)
"timestamps": {
"newDayTime": 43200, // Time the new day occurs at
"serverTimeOfDay": 15235 // The time of day in seconds in the server's timezone
},
"status": {
"hasStorm": true, // True if the server is currently raining
"isThundering": false // True if the server is currently thundering
},
"stats": {
"time": 21068, // The amount of ticks that have passed within the current day
"fullTime": 896133068, // The amount of ticks that have ever passed
"maxPlayers": 200, // The total amount of players that can connect to the server
"numOnlinePlayers": 184, // The current amount of online players
"numOnlineNomads": 7, // The current amount of online players with no town
"numResidents": 27858, // The total amount of currently registered Towny residents
"numNomads": 14711, // The total amount of registered Towny residents who have no town
"numTowns": 3007, // The total amount of currently registered Towny towns
"numTownBlocks": 273417, // The total amount of town blocks across all towns
"numNations": 513, // The total amount of currently registered Towny nations
"numQuarters": 5875, // The total amount of Quarters on the server
"numCuboids": 9773 // The total amount of cuboids within all quarters
},
"voteParty": {
"target": 5000, // The total votes required to trigger a vote party
"numRemaining": 4141 // The votes remaining before a vote party
}
}
Towns
Accessed at https://api.earthmc.net/v4/towns
The following is an abridged version of the response to a GET request to the above URL which contains every currently registered Towny town within a JSON array.
[
{
"name": "Huzhou",
"uuid": "c891767e-2992-419c-a748-7df00a25b781"
},
{
"name": "Vladivostok",
"uuid": "51c2dc6d-9a41-4091-a7ce-ece008c178fa"
},
{
"name": "Roros",
"uuid": "0fbaeb5b-bea0-46a1-b6fe-c2ed314ab03f"
},
{
"name": "Gulag",
"uuid": "2835f0bc-820a-4ef3-a2ba-8fdfd5d4e36b"
},
{
"name": "Aydın",
"uuid": "582d0ff1-10da-4ca6-99f8-97946cc776e8"
}
]
To query specific towns (with more data), you can use a POST request, and specify an array of towns to query in the body.
Example POST request
{
"query": [ // You can use both UUIDs and names
"51c2dc6d-9a41-4091-a7ce-ece008c178fa",
"Teslin"
]
}
Example POST response
[
{
"name": "Teslin", // Town's name
"uuid": "969d4960-f082-4be0-9e32-f14ed0b7cd50", // Town's UUID
"board": "Fishing every Friday! Join our Discord, link can be found on the signs!", // Town's board as seen on /t, null if none is present
"founder": "tuzzzie", // The founder of the town as seen on /t
"wiki": null, // The town's wiki URL as a string if set, returns null if not
"mayor": {
"name": "Fruitloopins",
"uuid": "fed0ec4a-f1ad-4b97-9443-876391668b34"
},
"nation": { // Nested nation values will be null if the town has no nation
"name": "Yukon",
"uuid": "3ce63924-44f9-404a-93e0-2fe87a22edd9"
},
"timestamps": {
"registered": 1660454740242, // A Unix timestamp representing when the town was created
"joinedNationAt": 1660454906803, // A Unix timestamp representing when the town joined its nation, null if the town has no nation
"ruinedAt": null // A Unix timestamp representing when the town fell to ruin, null if the town is not ruined
},
"status": {
"isPublic": false, // True if the town is public
"isOpen": true, // True if the town is open
"isNeutral": false, // True if the town is neutral
"isCapital": true, // True if the town is the nation's capital
"isOverClaimed": true, // True if the town has more claims than it should
"isRuined": false, // True if the town is ruined
"isForSale": false, // True if the town is for sale
"hasNation": true, // True if the town has a nation
"hasOverclaimShield": false, // True if the town currently has an overclaim shield
"canOutsidersSpawn": false, // True if the town allows outsiders to teleport
},
"stats": {
"numTownBlocks": 473, // The total number of town blocks the town has
"maxTownBlocks": 114, // The maximum town blocks the town can claim
"numResidents": 7, // The current number of residents in the town
"numTrusted": 5, // The total number of trusted residents in the town
"numOutlaws": 3, // The total number of players that are outlawed in the town
"balance": 51, // The town's balance as seen on /t
"forSalePrice": null // The price the town is for sale at, null if the town is not for sale
},
"perms": {
"build": [
false,
false,
false,
false
],
"destroy": [
false,
false,
false,
false
],
"switch": [
false,
false,
false,
false
],
"itemUse": [
false,
false,
false,
false
],
"flags": {
"pvp": false,
"explosion": false,
"fire": false,
"mobs": false
}
},
"coordinates": {
"spawn": { // The location of the town's spawn
"world": "earth",
"x": -25227.14828937919,
"y": 86,
"z": -11394.414899422554,
"pitch": 16.419712,
"yaw": -60.628418
},
"homeBlock": [ // X and Z of the town's home block
-1577,
-713
],
"townBlocks": [ // A JSON array representing all the town blocks in this town, abridged to reduce size, first value is X, second is Z, multiply by 16 to get actual coordinate
[
-1551,
-710
],
[
-1551,
-709
],
[
-1551,
-712
],
[
-1551,
-711
],
[
-1551,
-714
]
]
},
"residents": [ // A JSON array representing all the resident's in the town
{
"name": "SilentlyyJudging",
"uuid": "00abc813-22c4-4734-88a5-609821971147"
},
{
"name": "Fruitloopins",
"uuid": "fed0ec4a-f1ad-4b97-9443-876391668b34"
},
{
"name": "catgirljodie",
"uuid": "6ff64e22-8d20-40bf-9914-a2d6172e65cc"
},
{
"name": "AuroraServer",
"uuid": "d633b540-2509-4aeb-af94-ea9ea2c481ee"
},
{
"name": "tuzzzie",
"uuid": "8391474f-4b57-412a-a835-96bd2c253219"
},
{
"name": "Thaamoth",
"uuid": "fa61c5dc-2677-4509-b20e-d159da20c9fd"
},
{
"name": "rangegirl28",
"uuid": "6ae5516a-c5e6-488f-97a4-311aaf6ecced"
}
],
"trusted": [
{
"name": "Fruitloopins",
"uuid": "fed0ec4a-f1ad-4b97-9443-876391668b34"
},
{
"name": "Masrain",
"uuid": "ea0c4d98-106d-416c-9647-06203f861e1b"
},
{
"name": "CorruptedGreed",
"uuid": "f17d77ab-aed4-44e7-96ef-ec9cd473eda3"
},
{
"name": "HaisevaGreed",
"uuid": "253dd297-cb8d-4b9a-9aae-ffe71883956f"
},
{
"name": "tuzzzie",
"uuid": "8391474f-4b57-412a-a835-96bd2c253219"
}
],
"outlaws": [
{
"name": "Fruitloopins",
"uuid": "fed0ec4a-f1ad-4b97-9443-876391668b34"
},
{
"name": "Masrain",
"uuid": "ea0c4d98-106d-416c-9647-06203f861e1b"
},
{
"name": "CorruptedGreed",
"uuid": "f17d77ab-aed4-44e7-96ef-ec9cd473eda3"
},
{
"name": "HaisevaGreed",
"uuid": "253dd297-cb8d-4b9a-9aae-ffe71883956f"
},
{
"name": "tuzzzie",
"uuid": "8391474f-4b57-412a-a835-96bd2c253219"
}
],
"quarters": [ // The UUID of every quarter in this town, can be looked up in the quarter's endpoint, empty if none are present
"8a7c56d1-d45a-4f5f-ac42-751c2e8c1b3d",
"aeac5e83-62e5-421d-9737-9f33825479ec",
"49a4da60-4589-45ff-a0ba-0fd54c45ba9f",
"54177617-694d-43b1-b2d9-2bb553fd8775",
"fc8a7c21-2992-4584-970c-e0b98c2233cd",
"47cf0463-dd50-4b2b-b533-5b57b3a51c09",
"853908a4-2d76-4055-b83a-cee9cda714ce",
"95d00017-845f-4ccd-883a-9104aabc1391",
"473c2da9-e0b1-467a-87c8-98a59b62e386",
"7645cc85-0d54-4ce0-800e-d358ae647aac",
"0253c695-15aa-48a6-9592-d558224dcff7",
"66ec664a-7eb9-47a6-aa53-1b692ef37e5e",
"3c130442-4521-47f2-9eb9-2f61db1c3b58",
"7fc3351c-42b0-4d55-b309-5ea7325519d4",
"0624ab20-19c8-4277-a900-5f336417ad67",
"93bd12da-9854-41eb-ad35-fb7789e47811",
"c5190a18-2001-475a-a9cc-b584998e6d91",
"9d966cc2-61c4-45e6-a792-45cd6a5affb6",
"fed851f7-09f7-49c4-9a12-51b22834145f",
"e8e594bd-2651-4559-a717-dbd75c125de6",
"439b01d5-a2b7-4a3c-8cb5-3e8389e1215e",
"f244d142-a0e0-4bf5-bb28-d497024203a1",
"d9fbef25-ce0e-4675-91ea-4b1e969a80c2",
"12303d82-e59d-4f5e-bdfe-20e8c5f8b758",
"738ed341-b3c8-4f60-b1dc-daee44adcb96",
"283feb0d-9db9-404e-bb4e-139377502d25",
"93a839ea-0f69-4e36-adcc-869439b22070",
"7f139395-5117-4937-80b2-3e3ab6c8aa11",
"bf765fbc-c41c-4dd5-b796-51dd1ebd0d6b",
"a112b649-e104-4aab-930b-5ef186eeed18",
"8ab5df2e-0201-47de-b342-c013cc14b0d2",
"0ef3bab8-e78f-4527-a0b6-2a1fa192a7d8",
"1717528c-4b1e-4e9e-8775-47def673a192",
"12de6b21-7376-4d5b-9fa3-1c95a693ccbc",
"41372449-d667-4567-97a3-7fe769ddb82f",
"74b89914-f80e-41f5-918c-8961767caff4",
"c50e1d12-a125-46a2-b6bb-a88972a017b7",
"0ba51d36-57d7-4a6a-b3fb-a3127c2fb3da",
"609fc31e-2e54-480e-aa7f-313c8eee351b",
"f0248886-ebad-4dcc-bc22-53e3b3ef6a92",
"e54aa634-0939-43b7-b0ec-9486d5d2c12d",
"da15b4bd-1182-41a0-8ff1-c6ca3c04508f",
"998dc903-8605-4be0-bc75-46cc4438b1f2",
"32157422-7b06-4299-9e04-0668c2b18b7b",
"f29944ef-4b60-4145-a848-27d7fb879e1c",
"02cad4e4-00fc-4f8e-a3fb-9d9981f25ae1",
"ff737a85-24c6-4abf-a656-c2c01a4ebe70"
],
"ranks": { // Arrays of everyone in every rank in the town, ranks with no players are empty
"Councillor": [
"Fruitloopins",
"tuzzzie"
],
"Builder": [],
"Recruiter": [],
"Police": [],
"Tax-exempt": [],
"Treasurer": [],
"Realtor": [],
"Settler": []
}
}
]
Nations
Accessed at https://api.earthmc.net/v4/nations
The following is an abridged version of the response to a GET request to the above URL which contains every currently registered Towny nation within a JSON array.
[
{
"name": "North_Pole",
"uuid": "f8553418-202f-431a-8127-6e4eb0bb258e"
},
{
"name": "Guinea",
"uuid": "6a458663-16ff-49c9-a27e-3ad5b3b9caf5"
},
{
"name": "severnaya",
"uuid": "ceff7448-5b6d-4494-a91d-b555a97a96e9"
},
{
"name": "Texas",
"uuid": "873d49aa-f086-4525-aef5-f36897037412"
},
{
"name": "Emirates",
"uuid": "b1d39d3f-8723-4d8b-916f-3de0d2492e4d"
}
]
To query specific nations (with more data), you can use a POST request, and specify an array of nations to query in the body.
Example POST request
{
"query": [ // You can use both UUIDs and names
"b1d39d3f-8723-4d8b-916f-3de0d2492e4d",
"Yukon"
]
}
Example POST response
[
{
"name": "Yukon", // Nation's name
"uuid": "3ce63924-44f9-404a-93e0-2fe87a22edd9", // Nation's UUID
"board": "Larger than Life", // Nation's board as seen on /n, null if no board is set
"dynmapColour": "FFA500", // Nation's hex Dynmap colour
"dynmapOutline": "FFFF00", // Nation's hex Dynmap outline
"wiki": null, // The nation's wiki URL as a string if set, returns null if not
"king": {
"name": "tuzzzie",
"uuid": "8391474f-4b57-412a-a835-96bd2c253219"
},
"capital": {
"name": "Teslin",
"uuid": "969d4960-f082-4be0-9e32-f14ed0b7cd50"
},
"timestamps": {
"registered": 1660454906803 // A Unix timestamp representing when the nation was created
},
"status": {
"isPublic": true, // True if the nation is public
"isOpen": true, // True if the nation is open
"isNeutral": true // True if the nation is neutral
},
"stats": {
"numTownBlocks": 1764, // The total number of town blocks the nation has
"numResidents": 50, // The current number of residents in the nation
"numTowns": 20, // The current number of towns in the nation
"numAllies": 5, // The current number of allies the nation has
"numEnemies": 2, // The current number of enemies the nation has
"balance": 1790 // The nation's balance as seen on /n
},
"coordinates": {
"spawn": { // The location of the nation's spawn
"world": "earth",
"x": -24932.5,
"y": 99.1875,
"z": -11442.5,
"pitch": 0.010773102,
"yaw": 179.99843
}
},
"residents": [ // A JSON array representing all the residents in this nation, abridged to reduce size
{
"name": "TheGrimReaper_34",
"uuid": "33cfd874-1554-4cbb-b54a-9ff93667a954"
},
{
"name": "kundumji",
"uuid": "44861aef-8d09-4a16-8654-a5db565cf0bb"
},
{
"name": "Dandelion23062",
"uuid": "66c71f8c-1b06-4719-9f64-39d1b8dbb4e2"
},
{
"name": "Madlykeanu",
"uuid": "36ad238b-e8e4-40c5-9be3-feb97e9fb5db"
},
{
"name": "cletustturtle",
"uuid": "36ff784a-234b-4a0f-a5bf-c1d76ef3a2c5"
}
],
"towns": [ // A JSON array representing all the towns in this nation, abridged to reduce size
{
"name": "Corlu",
"uuid": "d77e7fc1-aed9-4402-9000-4ed2f5a07eab"
},
{
"name": "Ram_Ranch",
"uuid": "78db92c0-e222-42b7-865f-1ede376503ef"
},
{
"name": "Kruzof",
"uuid": "6f10a165-cbd1-481d-935c-3e1d9cd6d643"
},
{
"name": "Aduna",
"uuid": "089e67b0-0cd6-4d2e-8348-34a0d603ee06"
},
{
"name": "Slushberg",
"uuid": "3b58b9c4-3124-4f06-8a1f-439b122325f0"
}
],
"allies": [ // A JSON array representing all the allies this nation has, empty if the nation has no allies
{
"name": "Venice",
"uuid": "5341d292-28bb-4c8e-a404-0076cfa2f478"
},
{
"name": "Aland",
"uuid": "bc7d0767-7c81-4090-87be-6ee61d840410"
},
{
"name": "Kalaallit_Nunaat",
"uuid": "18fc4239-9a69-48a2-ad0b-5cd45880d04b"
},
{
"name": "Tassie",
"uuid": "2e36d7c8-5ea7-49d8-bd9a-d99b033be83f"
},
{
"name": "Germany",
"uuid": "d7833c7a-2fe6-4f26-9120-00e0759c555f"
}
],
"enemies": [ // A JSON array representing all the enemies this nation has, empty if the nation has no enemies
{
"name": "Mongolia",
"uuid": "becfc4fd-6cc6-4f9c-aa3c-2ea542ce6236"
},
{
"name": "Russia",
"uuid": "a43c4aff-f472-4fe2-9f77-c307dda1defc"
}
],
"sanctioned": [], // A JSON array representing all the town's this nation has sanctioned, empty if the nation has sanctioned no towns
"ranks": { // Arrays of everyone in every rank in the nation, ranks with no players are empty
"Chancellor": [
"Fruitloopins",
"tuzzzie"
],
"Colonist": [],
"Diplomat": []
}
}
]
Nearby
Accessed at https://api.earthmc.net/v4/nearby
Returns an array of all the elements of type search_type (TOWN) in a given radius of a target location of type target_type (TOWN|COORDINATE).
Use a POST request, and specify an array of nearby queries in the body.
Example POST request with a nearby query based on a town
{
"query": [
{
"target_type": "TOWN",
"target": "Melbourne",
"search_type": "TOWN",
"radius": 100
}
]
}
Example POST request with a nearby query based on coordinates
{
"query": [
{
"target_type": "COORDINATE",
"target": [
2000,
10000
],
"search_type": "TOWN",
"radius": 10000
}
]
}
Example POST response for a nearby query with search_type set to TOWN (the only type currently available)
[
[
{
"name":"Jyväskylä",
"uuid":"0b69c00d-c112-4ca0-a16c-ce551120e464"
},
{
"name":"Watson",
"uuid":"5851f859-0c4e-49bb-9e5c-5a2f9121585c"
}
]
]
Players
Accessed at https://api.earthmc.net/v4/players
The following is an abridged version of the response to a GET request to the above URL which contains every currently registered Towny resident within a JSON array.
[
{
"name": "deb0rahah",
"uuid": "eca37341-fb75-4776-a7c6-b5b785e736a8"
},
{
"name": "MiniBird675",
"uuid": "9ac5f867-59a4-485e-b239-51da7155e367"
},
{
"name": "MrZioX",
"uuid": "bf055853-9510-4541-ba2f-753b293c0600"
},
{
"name": "_EukaliptUs",
"uuid": "013dddcc-5406-470d-bb69-c2fcdb5f8f2c"
},
{
"name": "4O4Lucas",
"uuid": "9c5a1c2e-76e9-4e09-81ff-e975f0ea1b3c"
}
]
To query specific players (with more data), you can use a POST request, and specify an array of players to query in the body.
Example POST request
{
"query": [ // You can use, UUIDs, names, and their discord ID if their discord is linked
"eca37341-fb75-4776-a7c6-b5b785e736a8",
"Fruitloopins",
"160374716928884736"
]
}
Example POST response
[
{
"name": "Fruitloopins", // Player's username
"uuid": "fed0ec4a-f1ad-4b97-9443-876391668b34", // Player's UUID
"title": "<rainbow>King", // Title set through /n set title, null if no title is set
"surname": "of Yukon", // Surname set through /n set surname, null if no surname is set
"formattedName": "<rainbow>King Fruitloopins of Yukon", // Formatted name combining title, username and surname
"about": "CEO of this feature", // About section of /res set with /res set about, null if there is no about set
"town": { // Child values are null if no town or nation
"name": "Teslin",
"uuid": "969d4960-f082-4be0-9e32-f14ed0b7cd50"
},
"nation": {
"name": "Yukon",
"uuid": "3ce63924-44f9-404a-93e0-2fe87a22edd9"
},
"timestamps": {
"registered": 1651299304371, // A Unix timestamp representing the time the player joined the server
"joinedTownAt": 1701704799323, // A Unix timestamp representing when the player joined their town, null if the player has no town
"lastOnline": 1711116371655 // A Unix timestamp representing when the player was lastOnline, can be null if the player is an NPC
},
"status": {
"isOnline": true, // True if the player is currently online
"isNPC": false, // True if the player is a Towny NPC
"isMayor": false, // True if the player is a mayor of a town
"isKing": false, // True if the player is the king of a nation
"hasTown": true, // True if the player is currently in a town
"hasNation": true // True if the player is currently in a nation
},
"stats": {
"balance": 2838, // The player's current gold balance as seen on /res
"numFriends": 1 // The amount of friends this player has
},
"perms": {
"build": [
false,
false,
false,
false
],
"destroy": [
false,
false,
false,
false
],
"switch": [
false,
false,
false,
false
],
"itemUse": [
false,
false,
false,
false
],
"flags": {
"pvp": false,
"explosion": false,
"fire": false,
"mobs": false
}
},
"ranks": {
"townRanks": [ // A JSON array representing the town ranks this player holds, empty if the player holds no ranks
"Councillor"
],
"nationRanks": [ // A JSON array representing the nation ranks this player holds, empty if the player holds no ranks
"Chancellor"
]
},
"friends": [ // A JSON array representing the res friends this player has, empty if the player has no friends
{
"name": "tuzzzie",
"uuid": "8391474f-4b57-412a-a835-96bd2c253219"
}
],
"discord": "160374716928884736"
}
]
Quarters
Accessed at https://api.earthmc.net/v4/quarters
The following is an abridged version of the response to a GET request to the above URL which contains every currently registered quarter within a JSON array.
[
{
"name":null,
"uuid":"412c7c07-eaa4-4870-bbb0-a8eaa205f925"
},
{
"name":null,
"uuid":"4399a284-ded4-4fd8-8966-126d6e489c84"
},
{
"name":null,
"uuid":"cc3189e3-87d1-4d42-81c6-e9033cf644b3"
},
{
"name":null,
"uuid":"5572325c-9716-48ae-ab16-7294282e50f0"
},
{
"name":null,
"uuid":"8fd1f7be-f0fb-4da5-b82c-d4dcdd6644ec"
}
]
To query specific quarters (with more data), you can use a POST request, and specify an array of quarters to query in the body.
Example POST request
{
"query": [
"5fb3b17a-c67e-476e-b8ad-f030955ef8ea",
"3a30a7dc-4892-4de4-b3ed-d2768ae5ae26"
]
}
Example POST response
[
{
"uuid": "5fb3b17a-c67e-476e-b8ad-f030955ef8ea", // The quarter's UUID
"type": "APARTMENT", // The quarter's type (https://github.com/Fruitloopins/Quarters/wiki/Quarter-Types)
"owner": { // Nested values are null if the quarter has no owner
"name": "Mcplayer21",
"uuid": "57bcd815-d93a-4e4a-904f-d01b3459ce17"
},
"town": {
"name": "Washington_DC",
"uuid": "065caae9-5b75-4f2e-aabe-826a209e8247"
},
"timestamps": {
"registered": 1697904112328, // A Unix timestamp representing the time the quarter was created
"claimedAt": 1710726377127 // A Unix timestamp representing the time the quarter was claimed at, null if the quarter has no owner
},
"status": {
"isEmbassy": true // True if the quarter is an embassy
},
"stats": {
"price": null, // An integer representing the quarter's sale price, null if the quarter is not for sale
"volume": 1890, // The total number of blocks within the quarter's bounds
"numCuboids": 1 // The total amount of cuboids this quarter is made up of
},
"colour": [ // A JSON array representing the RGB values of the quarter
64,
194,
121
],
"trusted": [], // A JSON array representing all the trusted players in this quarter, empty if nobody is trusted
"cuboids": [ // A JSON array representing every cuboid in this quarter
{
"pos1": [
-18395,
93,
-8215
],
"pos2": [
-18381,
88,
-8235
]
}
]
}
]
Discord
The discord endpoint has been merged with the players endpoint.
You can query residents using their discord ID, and fetch their username, or vice versa.
Location
Accessed at https://api.earthmc.net/v4/location
Get Towny-related information on a specific location, for instance if it belongs to a town.
Use a POST request, and specify an array of locations (sets of [X, Z] coordinates) to query in the body.
Example POST request
{
"query": [
[0, 0],
[100, 100]
]
}
Example POST response
[
{
"location": {
"x":0,
"z":0
},
"isWilderness":false,
"town": {
"name":"Jyväskylä",
"uuid":"0b69c00d-c112-4ca0-a16c-ce551120e464"
},
"nation": {
"name":"Finland",
"uuid":"ae16c3c0-f8ab-4715-8553-019168008c49"
}
}
]
Mystery Master
Accessed at https://api.earthmc.net/v4/mm
Get the top 50 players participating in Mystery Master. Response returns name, uuid and change. Change indicates in what direction they've moved on the score board.
The following is an example of the response to a GET request to the above URL.
[
{
"name": "Xin_hachamecha",
"uuid": "8b543488-dd1d-4440-aa44-457fa25249fc",
"change": "UP"
},
{
"name": "kazucc",
"uuid": "21dc99b4-b0dc-4aa5-9913-3b5ff2594229",
"change": "UP"
},
{
"name": "UrbanTracker_lol",
"uuid": "6743993e-bdd2-4835-90f3-2e8cd14dccf7",
"change": "DOWN"
},
{
"name": "Nutsuko",
"uuid": "4e6f74b3-b260-447e-98bf-a025b728eb4b",
"change": "UP"
},
{
"name": "psiroq",
"uuid": "2673751e-5866-42a7-92ea-24bacd856c73",
"change": "DOWN"
},
{
"name": "junjun4654",
"uuid": "e3c6db0a-2f6b-4430-988c-610a9ccd659b",
"change": "UP"
},
{
"name": "seychelles4567",
"uuid": "c445b40f-bce5-4d23-98b1-b31b92f16ae7",
"change": "UP"
},
{
"name": "Pamena",
"uuid": "554f4bb7-d663-4c1b-a5b3-c70758e63792",
"change": "DOWN"
},
{
"name": "Vibezisacutie",
"uuid": "96dcee81-ef04-4104-83bc-8e151b3bf58c",
"change": "UP"
},
{
"name": "Ariohc",
"uuid": "9c28d713-79e7-41f4-aaed-5b4ab81da015",
"change": "DOWN"
}
]
Online Players
Accessed at https://api.earthmc.net/v4/online
Returns a JSON object with a count of how many players are online and their names and uuid. Players that have opted themselves out of appearing in the API will not appear in the players array, but are included in the count.
Example response (GET request):
{
"count": 1,
"players": [
{
"name": "Warriorrr",
"uuid": "e25ad129-fe8a-4306-b1af-1dee1ff59841"
}
]
}
QuickShops
Accessed at https://api.earthmc.net/v4/shop
Returns a list of shops the specified player owns. Note that the shop endpoint requires an API key to return data. The api key's owner must match the UUID being queried, otherwise an empty list is returned.
Example POST request
{
"query": ["5b8274bf-b162-4336-85a0-48f9d5380a78"],
"key": "API_KEY"
}
Example POST response
[
{
"0": {
"item": "TOTEM_OF_UNDYING",
"price": 150.0,
"amount": 1,
"type": "selling",
"stock": 3,
"location": {
"x": 0,
"y": 0,
"z": 0
}
},
"1": {
"item": "DIAMOND_CHESTPLATE",
"price": 2.0,
"amount": 1,
"type": "selling",
"stock": 15,
"location": {
"x": 0,
"y": 0,
"z": 0
}
}
}
]
POST Templates
Templates are supported for Player, Town, Nation, Quarter and Location endpoints. Only get what you asked for.
POST Templates are optional JSON objects you can provide in POST requests bodies to specify which fields the requested objects should feature.
In a new template JSON object in the body, simply recreate each field of the object you are requesting, and set its value to true if you want it to be present in the response.
You do not have to specifically set the other fields to false, everything that is not present or not true will not be included.
note
Templates do not support nested components. You can only select top-level fields, and all their nested contents will be added.
Here is an example of a POST request to /towns with a template:
{
"query": ["Mojo", "JavaScript"],
"template": {
"name": true,
"mayor": true,
"board": false, // This is optional
"nation": 839, // 839 is not a valid value. This key will be skipped despite existing in the Town object.
"jacko": true // This key does not exist in the Town object, so despite being true, it will not be included
}
}
And here is the response:
[
{
"name": "Mojo",
"mayor": {
"name": "12BarBruise",
"uuid": "e17c3b1d-1c20-41ec-928a-6f7f375c42f9"
}
},
{
"name": "JavaScript",
"mayor": {
"name": "Raurok",
"uuid": "ea0d3135-b9c1-4236-8886-ff489851e69d"
}
}
]
Server sent events (SSE)
Accessed at https://api.earthmc.net/v4/events
Server sent events allow clients to establish a blocking connection to the server, where the server sends real-time updates for various events.
Connecting requires an API key to be passed in the headers, in the following format: Authorization Bearer <key>
Clients must specify what events they'd like to listen to using the ?listen= query parameter in the URL.
E.g. https://api.earthmc.net/v4/events?listen=NewDay,TownDeleted,NationRenamed
These are the current events available:
"NewDay",
"NationCreated", "NationDeleted", "NationRenamed", "NationKingChanged", "NationMerged",
"TownCreated", "TownDeleted", "TownRenamed", "TownMayorChanged", "TownMerged", "TownRuined", "TownReclaimed",
"TownJoinedNation", "TownLeftNation",
"ResidentJoinedTown", "ResidentLeftTown",
"ShopSoldItem", "ShopBoughtItem", "ShopOutOfStock", "ShopOutOfSpace", "ShopOutOfGold"
- Some events are only sent to the relevant/affected player.
E.g. a ResidentJoinedTown event is only sent to the affected town's mayor. As each API key is linked to an in-game account, it is easy to verify if a client should be sent an event or not.
Event responses
All event responses carry a "timestamp" field with the current unix seconds
- Newday
{
"timestamp": 1774520132
}
- NationCreated, NationDeleted
{
"nation": {
"name": "France",
"uuid": "2a013de4-d29b-4603-830e-28517629866c"
},
"king": {
"name": "Veyronity",
"uuid": "5b8274bf-b162-4336-85a0-48f9d5380a78"
},
"capital": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"timestamp": 1774520132
}
- NationRenamed
{
"nation": {
"name": "Germany",
"uuid": "d7833c7a-2fe6-4f26-9120-00e0759c555f"
},
"oldName": "Deutschland"
"timestamp": 1774520132
}
- NationKingChanged
{
"nation": {
"name": "France",
"uuid": "2a013de4-d29b-4603-830e-28517629866c"
},
"newKing": {
"name": "Veyronity",
"uuid": "5b8274bf-b162-4336-85a0-48f9d5380a78"
},
"oldKing": {
"name": "TiowoiT",
"uuid": "1619c62c-0198-4139-a204-cd767d4b95c5"
},
"isCapitalChange": true, // If this is false, newCapital and oldCapital are not included in the response.
"newCapital": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"oldCapital": {
"name": "Monaco",
"uuid": "395b2240-9526-40e3-9b9d-dd8a473ed30e"
},
"timestamp": 1774520132
}
- NationMerged
{
"oldNation": {
"name": "Germany", // The nation that is merging into the other
"uuid": "d7833c7a-2fe6-4f26-9120-00e0759c555f"
},
"remainingNation": {
"name": "France", // The nation that is being merged into, i.e. the remaining nation
"uuid": "2a013de4-d29b-4603-830e-28517629866c"
},
"timestamp": 1774520132
}
- TownCreated, TownDeleted
{
"town": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"mayor": {
"name": "Veyronity",
"uuid": "5b8274bf-b162-4336-85a0-48f9d5380a78"
},
"timestamp": 1774520132
}
- TownRenamed
{
"town": {
"name": "New_Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"oldName": "Paris",
"timestamp": 1774520132
}
- TownMayorChanged
{
"town": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"newMayor": {
"name": "Veyronity",
"uuid": "5b8274bf-b162-4336-85a0-48f9d5380a78"
},
"oldMayor": {
"name": "TiowoiT",
"uuid": "1619c62c-0198-4139-a204-cd767d4b95c5"
},
"timestamp": 1774520132
}
- TownMerged
{
"oldTown": {
"name": "Monaco", // The town that is merging into the other
"uuid": "395b2240-9526-40e3-9b9d-dd8a473ed30e"
},
"remainingTown": {
"name": "Paris", // The town that is being merged into, i.e. the remaining town
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"timestamp": 1774520132
}
- TownRuined
{
"town": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"oldMayor": {
"name": "Veyronity",
"uuid": "5b8274bf-b162-4336-85a0-48f9d5380a78"
},
"timestamp": 1774520132
}
- TownReclaimed
{
"town": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"newMayor": {
"name": "Veyronity",
"uuid": "5b8274bf-b162-4336-85a0-48f9d5380a78"
},
"timestamp": 1774520132
}
note
The following events are only sent to the relevant/affected player. Nation and town events are only sent to the nation leader or town mayor respectively. Shop events are only sent to the shop owner.
- TownJoinedNation, TownLeftNation
{
"nation": {
"name": "France",
"uuid": "2a013de4-d29b-4603-830e-28517629866c"
},
"town": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"timestamp": 1774520132
}
- ResidentJoinedTown, ResidentLeftTown
{
"town": {
"name": "Paris",
"uuid": "d6a45111-f95b-4ac2-ba52-07e8e449a622"
},
"resident": {
"name": "Veyronity",
"uuid": "5b8274bf-b162-4336-85a0-48f9d5380a78"
}
"timestamp": 1774520132
}
- ShopSoldItem
{
"shop": {
"item": "TOTEM_OF_UNDYING",
"price": 150.0,
"amount": 1,
"type": "selling",
"stock": 3,
"location": {
"x": 0,
"y": 0,
"z": 0
}
},
"buyer": "Veyronity",
"timestamp": 1774520132
}
- ShopBoughtItem
{
"shop": {
"item": "PLAYER_HEAD",
"price": 125.0,
"amount": 1,
"type": "buying",
"stock": 128,
"location": {
"x": 0,
"y": 0,
"z": 0
}
},
"seller": "Veyronity",
"timestamp": 1774520132
}
- ShopOutOfStock
{
"action": "out_of_stock"
"shop": {
"item": "TOTEM_OF_UNDYING",
"price": 150.0,
"amount": 1,
"type": "selling",
"stock": 3
},
"timestamp": 1774520132
}
- ShopOutOfSpace
{
"action": "out_of_space"
"shop": {
"item": "TOTEM_OF_UNDYING",
"price": 150.0,
"amount": 1,
"type": "selling",
"stock": 3,
"location": {
"x": 0,
"y": 0,
"z": 0
}
},
"timestamp": 1774520132
}
- ShopOutOfGold
{
"timestamp": 1774520132
}