API Documentation
Connecting to the API
Our API can be accessed by making requests to https://api.earthpol.com/. This will refer you to all active server root endpoints in a JSON format.
Example:
{
"roots": [
"https://api.earthpol.com/ecliptica/",
"https://api.earthpol.com/astra"
]
}
The current server version is Astra, all of our production API will be located at https://api.earthpol.com/astra. All documentation will use this version.
In addition, you can download our Postman Collection (Click Here) which has all endpoints and query examples setup! Learn more about Postman.
Request Payloads
The EarthPol API uses a unified POST structure across most endpoints. To retrieve detailed data for a specific object (such as a town, nation, player, etc.), send a POST request with a query array in the body. Each item can be either a UUID or a name, depending on the endpoint.
{
"query": [
"search_term_1",
"search_term_2"
]
}
Endpoints
Root
This is the primary endpoint which provides basic server information. The "endpoints" section will outline all active endpoints.
GET: https://api.earthpol.com/astra
{
"version": "1.21.4",
"moonPhase": "LAST_QUARTER",
"time": {
"newDayTime": 86400,
"serverTimeOfDay": 40453,
"stormDuration": 12847,
"thunderDuration": 3592,
"time": 0,
"fullTime": 48000
},
"status": {
"hasStorm": true,
"isThundering": true,
"daylightCycle": false,
"mobSpawning": false,
"keepInventory": false,
"randomTickSpeed": 3,
"viewDistance": 24,
"simulationDistance": 4
},
"stats": {
"maxPlayers": 500,
"numOnlinePlayers": 0,
"numOnlineNomads": 0,
"numResidents": 3328,
"numNomads": 3237,
"numTowns": 29,
"numTownBlocks": 4845,
"numNations": 13,
"numQuarters": 21
},
"endpoints": {
"towns": "https://api.earthpol.com/astra/towns",
"nations": "https://api.earthpol.com/astra/nations",
"players": "https://api.earthpol.com/astra/players",
"shops": "https://api.earthpol.com/astra/shops",
"location": "https://api.earthpol.com/astra/location",
"discord": "https://api.earthpol.com/astra/discord",
"quarters": "https://api.earthpol.com/astra/quarters",
"chat": "https://api.earthpol.com/astra/chat",
"voting": "https://api.earthpol.com/astra/voting",
"sieges": "https://api.earthpol.com/astra/sieges"
}
}
Towns
Endpoint: https://api.earthpol.com/astra/towns
Below is a shortened example of the GET response returned from the URL above, listing all currently registered Towny Towns in a JSON array.
GET: https://api.earthpol.com/astra/towns
[
{
"name": "Havana",
"uuid": "ff50d039-669d-413e-84e0-18c3fd370ea3"
},
{
"name": "Astoria",
"uuid": "834b37c4-ea3b-4faf-b8f0-1a5b8254c574"
},
{
"name": "Anchorage",
"uuid": "a10ceae2-21a9-42a4-8489-dcadc9146cd3"
},
{
"name": "Seattle",
"uuid": "ca3b3504-41e4-4c79-a8bc-3e9f5f465d92"
}
]
You can also POST to this endpoint using the example payload below. You can use either the Town name or the Town UUID
POST: https://api.earthpol.com/astra/towns
Payload:
{
"query": [
//You can query by Town Name or Town UUID, doing both will return double results.
"Havana", //Town Name
"ff50d039-669d-413e-84e0-18c3fd370ea3" //Town UUID
]
}
An example response from the Towns endpoint after a POST request with the above payload would be like this.
Response:
[
{
"name": "Havana",
"uuid": "ff50d039-669d-413e-84e0-18c3fd370ea3",
"board": "VIVA LA LIBERTAD CARAJO",
"founder": "5u5u",
"mayor": {
"name": "jhjhjh098k",
"uuid": "9a2657ea-e15c-4469-8886-6c101151eff0"
},
"nation": {
"name": "Cuba",
"uuid": "5eda99c0-e430-4552-abae-4e7604579483"
},
"timestamps": {
"registered": 1719014016273,
"joinedNationAt": 1719176120296,
"ruinedAt": null
},
"status": {
"isPublic": true,
"isOpen": false,
"isNeutral": false,
"isCapital": true,
"isOverClaimed": true,
"isRuined": false,
"isForSale": false,
"hasNation": true
},
"stats": {
"numTownBlocks": 1020,
"maxTownBlocks": 985,
"bonusBlocks": 0,
"numResidents": 14,
"numTrusted": 9,
"numOutlaws": 1,
"balance": 81.8
},
"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": {
"world": "world",
"x": -27417.029697659815,
"y": 88.75061076465869,
"z": -7704.748858546749,
"pitch": 41.038494,
"yaw": -97.12445
},
"homeBlock": [
-1714,
-482
],
"townBlocks": [
[
-1745,
-479
]
]
},
"residents": [
{
"name": "MrTytanic",
"uuid": "d904bb76-412d-4f6a-af9f-13853b5fc614"
},
{
"name": "jhjhjh098k",
"uuid": "9a2657ea-e15c-4469-8886-6c101151eff0"
}
],
"trusted": [
{
"name": "jhjhjh098k",
"uuid": "9a2657ea-e15c-4469-8886-6c101151eff0"
},
{
"name": "Kauntar",
"uuid": "67dbe22c-f9f8-4f27-a372-3ec9cf7c8ea8"
}
],
"outlaws": [
{
"name": "kreepsta",
"uuid": "dc013ac2-23b9-4a56-84f2-74b6e559ffe1"
}
],
"quarters": [],
"ranks": {
"assistant": [
{
"name": "Ethnzz",
"uuid": "bb045b6c-df6a-4f83-be01-5eb745273f72"
}
],
"trusted": [],
"recruiter": [],
"sheriff": [],
"guard": []
}
}
]
Nations
Endpoint: https://api.earthpol.com/astra/nations
Below is a shortened example of the GET response returned from the URL above, listing all currently registered Towny Nations in a JSON array.
GET: https://api.earthpol.com/astra/nations
[
{
"name": "Japan",
"uuid": "93f28b00-51ba-43b2-930f-a63e496317a2"
},
{
"name": "Cascadia",
"uuid": "e38c9fbc-78d9-4e9b-a90f-870fba949693"
},
{
"name": "Portugal",
"uuid": "617f990b-1f21-4e8a-9791-05c07ccbb431"
},
{
"name": "Cuba",
"uuid": "5eda99c0-e430-4552-abae-4e7604579483"
},
{
"name": "Hokkaido",
"uuid": "1bd8a430-05a5-43da-b74d-5054e843f81d"
}
]
POST: https://api.earthpol.com/astra/nations
Payload:
{
"query": [
//You can query by Nation Name or Nation UUID, doing both will return double results.
"Hokkaido", //Nation Name
"1bd8a430-05a5-43da-b74d-5054e843f81d" //Nation UUID
]
}
Response
[
{
"name": "Hokkaido",
"uuid": "1bd8a430-05a5-43da-b74d-5054e843f81d",
"board": "Glory to Hokkaido!",
"king": {
"name": "0xBit",
"uuid": "d550441b-5fcf-448c-a756-5fa391b89a46"
},
"capital": {
"name": "Sapporo",
"uuid": "d694c985-0514-4f98-a6f2-48213d1a7c47"
},
"timestamps": {
"registered": 1749343045130
},
"status": {
"isPublic": false,
"isOpen": false,
"isNeutral": false
},
"stats": {
"numTownBlocks": 3124,
"numResidents": 47,
"numTowns": 5,
"numAllies": 66,
"numEnemies": 9,
"balance": 3547.0
},
"coordinates": {
"spawn": {
"world": "world",
"x": 48433.35710783266,
"y": 63.0,
"z": -14687.509163325874,
"pitch": 1.5000051,
"yaw": 89.90117
}
},
"residents": [
{
"name": "0xBit",
"uuid": "d550441b-5fcf-448c-a756-5fa391b89a46"
},
{
"name": "Spiceit",
"uuid": "2bddc5c4-fb63-4f4d-9b38-d73e8e1bb2c4"
},
{
"name": "Keipthountx",
"uuid": "1118f770-c55e-4677-af34-40a571a335b5"
},
{
"name": "Frxzt",
"uuid": "0bea07e0-60f9-47e4-bffb-919d2eee7463"
},
{
"name": "korey4907",
"uuid": "c2ee15fb-54f0-4acb-8ed0-2ff9da673f01"
},
{
"name": "Hosentil",
"uuid": "e7d3a4b1-d262-4583-82d9-1418bf62a677"
}
],
"towns": [
{
"name": "HIA",
"uuid": "2d886361-9eb6-4c0b-8011-d6eb36f1f25d"
},
{
"name": "Karafuto",
"uuid": "661e2d58-e1f9-4614-acb0-a92c2a9a99b5"
},
{
"name": "New_Atlanta",
"uuid": "4fa2bd84-1414-410d-ae96-fff5d006cab3"
},
{
"name": "Sapporo",
"uuid": "d694c985-0514-4f98-a6f2-48213d1a7c47"
},
{
"name": "Wakkanai",
"uuid": "3360a5ee-e307-4f13-b1c6-89c7a622a343"
}
],
"allies": [
{
"name": "German_Empire",
"uuid": "00b142fb-a5cf-4cf0-9f0a-e6f43f723c66"
}
],
"enemies": [
{
"name": "SPQM",
"uuid": "913c897d-fc38-4c9f-bc97-02e557fa2876"
}
],
"sanctioned": [],
"discord": "https://discord.gg/KtSPBrQsct",
"ranks": {
"co-leader": [
{
"name": "SpaceJavelin",
"uuid": "2c56e5ab-3995-4481-be09-4e14e5170b25"
}
],
"minister": [
{
"name": "korey4907",
"uuid": "c2ee15fb-54f0-4acb-8ed0-2ff9da673f01"
}
],
"ambassador": [
{
"name": "MarshalTactix",
"uuid": "e9203daa-a7e1-49e9-a691-b18a85dab008"
}
],
"recruiter": [
{
"name": "Tree404",
"uuid": "cf4f0d3d-accc-4d92-a997-0f5d1bf63369"
}
],
"soldier": [
{
"name": "korey4907",
"uuid": "c2ee15fb-54f0-4acb-8ed0-2ff9da673f01"
}
],
"general": [
{
"name": "MarshalTactix",
"uuid": "e9203daa-a7e1-49e9-a691-b18a85dab008"
},
{
"name": "SpaceJavelin",
"uuid": "2c56e5ab-3995-4481-be09-4e14e5170b25"
}
]
}
}
]
Players
Endpoint: https://api.earthpol.com/astra/players
Below is a shortened example of the GET response returned from the URL above, listing all currently registered Towny Residents in a JSON array.
GET: https://api.earthpol.com/astra/players
[
{
"name": "MrTytanic",
"uuid": "d904bb76-412d-4f6a-af9f-13853b5fc614"
},
{
"name": "Kauntar",
"uuid": "67dbe22c-f9f8-4f27-a372-3ec9cf7c8ea8"
},
{
"name": "jhjhjh098k",
"uuid": "9a2657ea-e15c-4469-8886-6c101151eff0"
},
{
"name": "Bustun",
"uuid": "9e47a89a-c251-4df6-9da2-792f2e3f74d0"
}
]
A POST to this endpoint returns information about the player
POST: https://api.earthpol.com/astra/players
Payload:
{
"query": [
//You can query with Player Name or Player UUID
"d904bb76-412d-4f6a-af9f-13853b5fc614", //Player UUID
"MrTytanic", //Player Name
"online" // Returns all online players.
]
}
Response:
[
{
"name": "MrTytanic",
"uuid": "d904bb76-412d-4f6a-af9f-13853b5fc614",
"title": null,
"surname": null,
"formattedName": "MrTytanic",
"about": "/res set about [msg]",
"premium": false,
"town": {
"name": null,
"uuid": null
},
"nation": {
"name": null,
"uuid": null
},
"timestamps": {
"registered": 1748406206481,
"joinedTownAt": null,
"lastOnline": 1753137047306
},
"status": {
"isOnline": false,
"isNPC": false,
"isMayor": false,
"isKing": false,
"hasTown": false,
"hasNation": false
},
"stats": {
"balance": 348.0,
"numFriends": 0
},
"perms": {
"build": [
true,
false,
false,
false
],
"destroy": [
true,
false,
false,
false
],
"switch": [
true,
false,
false,
false
],
"itemUse": [
true,
false,
false,
false
],
"flags": {
"pvp": false,
"explosion": false,
"fire": false,
"mobs": false
}
},
"ranks": {
"townRanks": [],
"nationRanks": []
},
"friends": []
}
]
Location
Endpoint: https://api.earthpol.com/astra/location
This endpoint only supports POST requests with the following payloads.
POST: https://api.earthpol.com/astra/location
Payload:
{
"query": [
[
-27720, // x Coordinate
-7744 // y Coordinate
]
]
}
Response:
[
{
"location": {
"x": -27720,
"z": -7744
},
"isWilderness": false,
"town": {
"name": "Havana",
"uuid": "ff50d039-669d-413e-84e0-18c3fd370ea3"
},
"nation": {
"name": "Cuba",
"uuid": "5eda99c0-e430-4552-abae-4e7604579483"
}
}
]
Shops
Endpoint: https://api.earthpol.com/astra/shops
GET: https://api.earthpol.com/astra/shops
[
{
"id": 4462,
"owner": "13d27295-93bf-402a-8108-f8822e4adceb",
"item": "ItemStack{GOLD_INGOT x 1}",
"price": 1.0,
"type": "SELLING",
"space": -1,
"stock": 410
},
{
"id": 9035,
"owner": "c6361698-4f03-4fb2-bb3c-74e799a22ad5",
"item": "ItemStack{BAKED_POTATO x 56}",
"price": 1.0,
"type": "SELLING",
"space": -1,
"stock": 0
},
{
"id": 9656,
"owner": "c6361698-4f03-4fb2-bb3c-74e799a22ad5",
"item": "ItemStack{BARREL x 33}",
"price": 9.0E11,
"type": "SELLING",
"space": 2.0,
"stock": 0
}
]
POST: https://api.earthpol.com/astra/shops
Payload:
{
"query": [
//You can get ALL Shops by searching the players UUID or you can get a specific shop by searching by shop ID
"d904bb76-412d-4f6a-af9f-13853b5fc614", //Player UUID to search for all shops they own
"2" //Shop ID to find information about a specific shop
]
}
Response:
[
[
{
"id": 2,
"owner": "d904bb76-412d-4f6a-af9f-13853b5fc614",
"item": "ItemStack{NETHERITE_INGOT x 1}",
"price": 1.0,
"type": "SELLING",
"space": -1,
"stock": -1,
"location": {
"world": "world",
"x": -42004.0,
"y": 53.0,
"z": -15520.0
}
},
{
"id": 3,
"owner": "d904bb76-412d-4f6a-af9f-13853b5fc614",
"item": "ItemStack{NETHERITE_BLOCK x 1}",
"price": 9.0,
"type": "SELLING",
"space": -1,
"stock": -1,
"location": {
"world": "world",
"x": -42004.0,
"y": 53.0,
"z": -15518.0
}
},
{
"id": 4,
"owner": "d904bb76-412d-4f6a-af9f-13853b5fc614",
"item": "ItemStack{DIAMOND x 1}",
"price": 13.0,
"type": "SELLING",
"space": -1,
"stock": -1,
"location": {
"world": "world",
"x": -42012.0,
"y": 53.0,
"z": -15521.0
}
}
]
]
Quarters
Endpoint: https://api.earthpol.com/astra/quarters
GET: https://api.earthpol.com/astra/quarters
[
{
"name": "Lovely Residence",
"uuid": "9b88b771-c6df-4219-b67d-6b8a01a3f24e"
},
{
"name": "Cascadia Shop",
"uuid": "e478eb62-6467-4f9b-a167-9d122583e1fa"
},
{
"name": "Drug Store",
"uuid": "8bf32d69-0e66-4ab3-92af-faf7c03f17a9"
},
{
"name": "Perturbing Property",
"uuid": "d5e4cbe0-e8b9-43c0-8af1-6dbef237e129"
}
]
POST: https://api.earthpol.com/astra/quarters
Payload:
{
"query": [
"9b88b771-c6df-4219-b67d-6b8a01a3f24e"
]
}
Response:
[
{
"name": "Lovely Residence",
"uuid": "9b88b771-c6df-4219-b67d-6b8a01a3f24e",
"type": "APARTMENT",
"creator": "9337b63c-8b9f-4690-a369-b7760521699a",
"owner": {
"name": null,
"uuid": null
},
"town": {
"name": "Lisbon",
"uuid": "1924b818-c2a2-46a3-b8be-beb043b76bf0"
},
"nation": {
"name": "Portugal",
"uuid": "617f990b-1f21-4e8a-9791-05c07ccbb431"
},
"timestamps": {
"registered": 1725837773050,
"claimedAt": null
},
"status": {
"isEmbassy": false,
"isForSale": false
},
"stats": {
"price": null,
"volume": 1152,
"numCuboids": 1,
"particleSize": null
},
"colour": [26, 21, 80, 255],
"trusted": [],
"cuboids": [
{
"cornerOne": [-3184, 63, -13332],
"cornerTwo": [-3177, 74, -13321]
}
]
}
]
Discord
Endpoint: https://api.earthpol.com/astra/discord
This endpoint only supports POST requests with the following payloads. We do not use DiscordSRV and instead use an in-house solution. This endpoint is subject to change.
POST: https://api.earthpol.com/astra/discord
Payload:
{
"query": [
//You can query with a Discord ID or a Minecraft UUID, not both at the same time
"325465801710764033", //Discord ID
"d904bb76-412d-4f6a-af9f-13853b5fc614" //Minecraft ID
]
}
Response:
{
"discord": "325465801710764033",
"uuid": "d904bb76-412d-4f6a-af9f-13853b5fc614"
}
Chat
Endpoint: https://api.earthpol.com/astra/chat
This endpoint only supports POST requests with the following payloads.
Example Payload:
{
"query": {
"uuid": ["<uuid1>", "<uuid2>", …], // up to 20 Minecraft UUID strings
"username": ["<user1>", "<user2>", …], // up to 20 usernames
"nickname": ["<nick1>", "<nick2>", …], // up to 20 nicknames
"message": ["<substr1>", "<substr2>", …], // up to 20 message substrings to match
"startTimestamp": "YYYY-MM-DD HH:mm:ss", // inclusive lower time bound
"endTimestamp": "YYYY-MM-DD HH:mm:ss" // inclusive upper time bound
}
}
- Filters are all optional. You only need to supply one or more of these fields to perform a query.
- Combined filter entries (uuid, username, nickname, message) are each limited to 20 items.
- The endpoint will return up to 200 of the most recent chat entries that match any of the supplied filters (ordered by timestamp descending).
- If "query" is empty or omitted entirely, you’ll receive the last 200 messages.
Working Example:
POST: https://api.earthpol.com/astra/chat
Payload:
{
"query": {
"uuid": ["9e47a89a-c251-4df6-9da2-792f2e3f74d0"],
"username": ["Bustun"],
"nickname": ["Busty"],
"message": ["Hello"],
"startTimestamp": "2025-05-23 05:00:00",
"endTimestamp": "2025-05-23 07:00:00"
}
}
Response:
[
{
"entry_id": 9,
"user_uuid": "9e47a89a-c251-4df6-9da2-792f2e3f74d0",
"username": "Bustun",
"nickname": null,
"message": "Hello",
"channel": "GLOBAL",
"timestamp": "2025-05-23T06:38:15Z"
}
]
Voting
Endpoint: https://api.earthpol.com/astra/voting
This endpoint only supports GET requests.
Response:
{
"totalVotesAllTime": 62976,
"totalVotesThisMonth": 7013,
"totalVotesThisWeek": 580,
"totalVotesThisDay": 583,
"votePartyCurrentVotes": 19,
"votePartyVotesRequired": 100,
"votePartyVotesNeeded": 81,
"timeUntilMonthReset": "7 Days 0 Hours 26 Minutes"
}
Sieges
Endpoint: https://api.earthpol.com/astra/sieges
This endpoint only supports GET requests.
battleSessionTimeTill and battleSessionTimeRemaining are returned as millisecond values. Each siege object may also include uuid, sessionBalance, startedAtMillis, endedAtMillis, and a battleSessions array with per-session kill and banner-control history when SiegeStats data is available.
Response:
{
"activeSiegeCount": 1,
"battleSessionTimeTill": 5023012,
"battleSessionTimeRemaining": 0,
"sieges": [
{
"uuid": "4f6320fa-2f46-4c2a-a4f4-1fa0dfbcb2d4",
"name": "Aiacciu",
"type": "CONQUEST",
"status": "In Progress",
"isActive": true,
"startedAtMillis": 1738812000000,
"endedAtMillis": 0,
"attacker": "Nation_A",
"defender": "Aiacciu",
"attackerPoints": 1860,
"defenderPoints": 400,
"sessionBalance": 1460,
"balance": 1460,
"sessionsCompleted": 3,
"sessionsLeft": 9,
"bannerLocation": {
"world": "world",
"x": -123,
"y": 75,
"z": 420
},
"battleSessions": [
{
"sessionNumber": 1,
"startedAtMillis": 1738812600000,
"endedAtMillis": 1738816200000,
"kills": [
{
"timestamp": 1738812800000,
"points": 30,
"reason": "PLAYER_KILL",
"killer": {
"id": 52,
"uuid": "11111111-1111-1111-1111-111111111111",
"name": "AttackerPlayer",
"side": "ATTACKERS"
},
"victim": {
"id": 87,
"uuid": "22222222-2222-2222-2222-222222222222",
"name": "DefenderPlayer",
"side": "DEFENDERS"
}
}
],
"bannerControl": [
{
"timestamp": 1738813000000,
"awardingSide": "ATTACKERS",
"controllersCount": 4,
"points": 80
}
]
}
]
}
]
}
KitPvP Leaderboard
EarthPol also exposes a public KitPvP leaderboard through EarthPol Observatory rather than through EPMCAPI.
Endpoint: https://earthpol.org/api/kitpvp/leaderboard
This endpoint currently supports GET requests with query parameters such as sort, order, limit, and offset.
Example:
GET: https://earthpol.org/api/kitpvp/leaderboard?sort=kills&order=desc&limit=1&offset=0
Response:
{
"sort": "kills",
"order": "desc",
"limit": 1,
"items": [
{
"uuid": "6d0f06c1-f12f-48fb-816f-e9863b4b1d61",
"username": "JimplayzMC",
"kills": 824,
"deaths": 354,
"assists": 140,
"damage": 29117.253477492388,
"damage_taken": 18686.507021899524,
"bow_shots": 150,
"bow_hits": 26,
"current_killstreak": 24,
"best_killstreak": 100,
"updated_at": "2026-02-27T10:22:16.000Z",
"source_updated_at": "2026-02-27T10:22:16.000Z",
"fetched_at": "2026-04-06T19:00:00.000Z"
}
],
"nextCursor": {
"cursorValue": 824,
"cursorUuid": "6d0f06c1-f12f-48fb-816f-e9863b4b1d61"
}
}