API Documentation

The EarthMC API is served using Vercel and NextJS serverless functions for optimal response times and reliablity. It provides plenty of data such as players, towns, nations, alliances and more! The repository is open source and can be found here.

Quick Start

For this example, we will use JavaScript combined with the Node Package Manager to install a fetch package that will allow us to send GET requests.

Note: To stop abuse, there is a rate limit of 10 requests per 8 seconds.
1. Install a fetch package in your chosen language.

$ npm install undici

2. Require/import the package.

const { request } = require('undici')

3. Send a get request to the specified route, and wait for the result.
const towns = await request('https://emctoolkit.vercel.app/api/aurora/towns').catch(() => {})
if (!towns) {
	// Handle error
	return console.error('An error occurred fetching towns!')
}

// Example code - logs all towns with more than 100 chunks claimed.
const bigTowns = towns.map(t => t.area > 100)
console.log(bigTowns)

Usage

This section provides all of the endpoints available for use, note that for generic routes you don't need to specify a map.

To begin, your URL to fetch must begin with the following:https://emc-toolkit.vercel.app/api/
Then, one of the routes from the list below can be appended to create a full endpoint.

List of Endpoints

Generic
Server Info

Endpoint:serverinfo
Response: Object | Error string + 404
Timeout (ms):5000

Archive (Map Data)

Endpoint:archive/timestamp?map=mapName
Response: Object | Error 500
Timeout (ms):10000

Map Specific

Replace the 'map' parameter with the map name.

All Players

Endpoint:map/allplayers
Response: Array of players. (with custom data)
Timeout (ms):15000

Online Players

Endpoint:map/onlineplayers
Response: Array of online players.
Timeout (ms):5000

Townless Players

Endpoint:map/townlessplayers
Response: Array of townless players.
Timeout (ms):5000

Residents

Endpoint:map/residents
Response: Array of residents from all towns.
Timeout (ms):5000

Towns

Endpoint:map/towns
Response: Array of towns.
Timeout (ms):10000

Joinable Nations

Endpoint:map/towns/townName/joinable
Response: Array of nations the specified town can join.
Timeout (ms):10000

Nations

Endpoint:map/nations
Response: Array of nations.
Timeout (ms):30000

Invitable Towns

Endpoint:map/nations/nationName/invitable
Response: Array of towns within the nation's invite range.
Timeout (ms):10000

Alliances

Endpoint:map/alliances
Response: Array of alliances. (Registered by our editors)
Timeout (ms):10000

News

Endpoint:map/news
Response: Object with the latest news. (Reported in EMCL)
Timeout (ms):5000

Nearby
Players

Endpoint:map/nearby/players/xPos/zPos/xBlocks/zBlocks
Response: Array of nearby players within at the specified position and radius.
Timeout (ms):5000

Towns

Endpoint:map/nearby/towns/xPos/zPos/xBlocks/zBlocks/
Response: Array of nearby towns within at the specified position and radius.
Timeout (ms):5000

Nations

Endpoint:map/nearby/nations/xPos/zPos/xBlocks/zBlocks
Response: Array of nearby nations within at the specified position and radius.
Timeout (ms):5000