API Documentation | Mercator Information Service

Mercator Web & Bot API

Available API Endpoints

Overview of all JSON and HTTP endpoints exposed by the Mercator Information Service website, the Eternal Lands Clock service, and the integrated BotManagement REST API.

Authentication

Personal API Token

Protected endpoints identify the caller and their roles (ROLE_USER, ROLE_GUILD, ROLE_ADMIN) via a personal API token generated in Player Settings. You can supply your token in any of the following ways:

# 1. Authorization Bearer Header (Recommended)
curl -H "Authorization: Bearer merc_..." http://mercator.holy-eternalland.de/api/me

# 2. X-AUTH-TOKEN Header
curl -H "X-AUTH-TOKEN: merc_..." http://mercator.holy-eternalland.de/api/messages

# 3. Query Parameter
curl "http://mercator.holy-eternalland.de/api/watchlist?api_token=merc_..."

Game Time & ElInfo Endpoints

Public JSON

GET /_elday/clock-data

Eternal Lands Clock Proxy Data

Returns normalized Eternal Lands game time, day name, special day description, and invasion status used by the digital clock widget.

{
  "eldata": {
    "GameDay": "12",
    "GameMonth": "1",
    "GameYear": "0032",
    "GameHour": "3",
    "GameMinute": "42",
    "GameSecond": "10",
    "GameDayName": "Normal Day",
    "GameDayDescription": "Just an ordinary day",
    "GIWS_Monsters": "0",
    "GIWS_Text": ""
  }
}

GET /botmanagement/elinfo.json

Direct Bot ElInfo Payload

Fetches the live elinfo.json payload directly from the Mercator Bot API (GameDay, GameHour, GameMinute, GameDayName, GameDayDescription, GIWS_Monsters, Timestamp).

Public Website JSON API

Public JSON

GET /api/marketsearch?q={item}&per_page=30&buy_page=1&sell_page=1

Market Search API

Searches bot buy and sell offers by item name. Optional query parameters: q (search term), per_page (10–200), buy_page, sell_page.

GET /api/specialdays?page=1&limit=25

Special Days History

Returns paginated Eternal Lands special day records (id, gamedate, specialday, donatedby, spdaydate).

GET /api/lottery?page=1&limit=25

Lottery Winners

Returns paginated Daily Lottery results (id, winner, win, lotterydate).

GET /api/announcements?page=1&limit=25

Moderator Announcements

Returns paginated moderator and server broadcasts (excluding Joker/Pear events).

GET /api/pears?page=1&limit=25

Joker & Pear Events

Returns paginated Joker and Pear finder announcements (id, gametime, modmessages, time).

GET /api/invances?page=1&limit=25

Invance Broadcasts

Returns paginated Invance status broadcasts (id, gametime, invance, invancedate).

Token-Authenticated Player API

API Token / Session

GET /api/me

Authenticated Player Identity & Roles

Returns the player profile and granted security roles (ROLE_USER, ROLE_GUILD, ROLE_ADMIN) associated with the API token.

{
  "username": "vinoveritas",
  "roles": ["ROLE_USER", "ROLE_GUILD", "ROLE_ADMIN"],
  "guild": "K&M",
  "combat": 142,
  "instancelevel": 120,
  "isonline": true
}

GET /api/messages • POST /api/messages/send

Player Inbox, Outbox & Send In-Game Message

GET /api/messages returns all inbox and outbox messages for the token owner.
POST /api/messages/send queues an in-game message from the token owner: {"recipient": "playername", "message": "Hello from API!"}.

GET /api/watchlist • GET /api/ignore

Online Player Watchlist & Ignore List

Returns the authenticated player's tracked players split into online and offline, or their personal ignore list.

GET /logviewer/stream?date=current&offset={bytes}&search={query}&channels[]=CHANNEL2&channels[]=CHANNEL3

Live Log Stream (Incremental JSON)

Returns newly appended lines from mercator.log starting at byte offset. Channels CHANNEL2 (Market) and CHANNEL3 (Channel 6) are publicly readable; channels GM and IG require a token or session with ROLE_GUILD.

{
  "entries": [
    {
      "line": 1042,
      "time": "09:41:12",
      "channel": "Market",
      "channelCode": "CHANNEL2",
      "message": "Buying 1k Fire Essence",
      "text": "09:41:12 [Market] Buying 1k Fire Essence"
    }
  ],
  "offset": 184920,
  "isLive": true
}

GET / JSON

Mercator Bot REST API (v1) & BotManagement

Bot Subsystem

GET /api/v1/health • GET /api/v1/status

System Health & Status

Returns JVM uptime, heap memory usage (usedHeapMb, maxHeapMb), database connection state, and active bot session count.

GET / JSON

GET /api/v1/bots

Active Bot Instances

Lists all running bot sessions including name, state, map, coordinates (x, y), facing, gold, and inventoryCount.

GET / JSON

POST /api/v1/bot/{name}/command • POST /botmanagement/bots/{name}/command

Execute Bot Command

Dispatches a command to the specified bot session. JSON payload: {"command": "turn left", "sender": "Admin"}. Via BotManagement requires ROLE_OPERATOR or ROLE_ADMIN.

POST

POST /api/v1/bot/{name}/send-pm • POST /botmanagement/bots/{name}/send-pm

Send In-Game Private Message

Sends an immediate in-game PM from the bot to a player. JSON payload: {"recipient": "PlayerName", "message": "Hello!"}.

POST

POST /api/v1/bot/{name}/reload-policy • POST /botmanagement/bots/{name}/reload-policy

Reload Bot Command Policy

Reloads the database privileges and command permissions for the given bot instance without restarting.

POST

GET /api/v1/orders?all=true • POST /api/v1/orders • PUT /api/v1/orders/{id} • DELETE /api/v1/orders/{id}

Market Orderbook Management

List, create, update, or cancel trade orders.
Create payload: {"buySell": "Purchage|Sell", "itemId": 1, "quantity": 100, "price": 15.0, "playerName": "..."}.
Update payload: {"quantity": 200, "price": 16.5, "buySell": "Sell"}.

REST CRUD

GET /api/v1/inventory • GET /api/v1/trade/history • GET /api/v1/players/online

Inventory, Trade History & Online Players

Returns live bot inventory slots, the latest 100 completed trades, or the list of currently online players with guild and level info.

GET / JSON

GET /api/v1/prices?q={item} • GET /api/v1/items?q={item}

Market Prices & Item Catalog

Queries current bot market prices or the Eternal Lands item catalog (iditem, itemname, itemid, imageid, emu).

GET / JSON