API
Accessing the API
The API can be accessed through the URL api.earthmc.net/v3/aurora. 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 has been maintained if you would prefer to use older versions.
note
/aurora/ is the current world name. Aurora was introduced in 2022. Prior worlds, Nova and Classic, are offline and therefore not availabe in the api.
Endpoints
Server
Accessed at https://api.earthmc.net/v3/aurora/
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/v3/aurora/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/v3/aurora/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/v3/aurora/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/v3/aurora/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 both UUIDs and names
"eca37341-fb75-4776-a7c6-b5b785e736a8",
"Fruitloopins"
]
}
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"
}
]
}
]
Quarters
Accessed at https://api.earthmc.net/v3/aurora/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
Accessed at https://api.earthmc.net/v3/aurora/discord
Determine a player's Discord ID from their Minecraft UUID and vice versa using DiscordSRV's link feature.
The player needs to have linked their account beforehand (/discord link in game).
Use a POST request, and specify an array of discord queries in the body.
Use type to specify the nature of your target.
Example POST request
{
"query": [
{
"type": "minecraft",
"target": "fed0ec4a-f1ad-4b97-9443-876391668b34" // <- Minecraft UUID
},
{
"type": "discord",
"target": "160374716928884736" // <- Discord ID
}
]
}
Example POST response
[
{
"id": "160374716928884736", // Discord ID
"uuid": "fed0ec4a-f1ad-4b97-9443-876391668b34" // Minecraft UUID
},
{
"id": "160374716928884736",
"uuid": "f17d77ab-aed4-44e7-96ef-ec9cd473eda3"
}
]
Location
Accessed at https://api.earthmc.net/v3/aurora/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"
}
}
]
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"
}
}
]