API Reference

플래닛어스는 서버 내 데이터에 접근할 수 있는 공개 REST API를 제공합니다.
국가 디스코드 봇 제작, 외부 사이트 연동, 자동화 등 다양한 용도로 활용할 수 있습니다.

기본 정보

항목	내용
Base URL	`https://api.planetearth.kr`
응답 형식	JSON
인증	없음 (공개 API)
캐시 TTL	5분 (일반) / 1시간 (Mojang 닉네임·UUID 변환)

요청 제한

종류	제한
일반 엔드포인트	IP당 15분에 70회
Bulk 엔드포인트	IP당 15분에 5회

응답 형식

모든 응답은 status 필드를 포함합니다.

성공

{
  "status": "SUCCESS",
  "data": [ ... ]
}

실패

{
  "status": "FAILED",
  "error": {
    "code": "NO_DATA_FOUND",
    "message": "주어진 입력에 맞는 정보를 찾을 수 없습니다."
  }
}

에러 코드

코드	HTTP	설명
`NO_DATA_FOUND`	404	조건에 맞는 데이터 없음
`NO_PARAMETER_PROVIDED`	400	파라메터 누락
`MULTIPLE_PARAMETERS_PROVIDED`	400	파라메터 2개 이상 입력
`INVALID_PARAMETERS_PROVIDED`	400	파라메터 형식 오류
`INVALID_NAME_PROVIDED`	404	존재하지 않는 마인크래프트 닉네임
`RATE_LIMITED`	429	요청 횟수 초과
`UPSTREAM_ERROR`	502 / 503	외부 API 연결 실패 (지도 서버: 502, Mojang API: 503)
`SERVER_ERROR`	500	서버 내부 오류

엔드포인트

마을

`GET /town`

이름 또는 UUID로 마을 정보를 조회합니다.

Query Parameters

파라메터	타입	설명
`name`	string	마을 이름
`uuid`	string	마을 UUID

파라메터는 하나만 입력해야 합니다.

Response Fields

필드	타입	설명
`name`	string	마을 이름
`uuid`	string	마을 UUID
`mayor`	string	마을장 닉네임
`nation`	string	소속 국가 이름
`residents`	string	주민 목록 (`,` 구분)
`memberCount`	number	전체 주민 수
`onlineMemberCount`	number	현재 온라인 주민 수
`onlineMembers`	string	현재 온라인 주민 목록 (`,` 구분)
`claimSize`	number	클레임한 청크 수
`balance`	number	마을 잔고
`townBoard`	string	마을 게시판 내용
`trustedResidents`	string	트러스트 주민 목록
`outlaws`	string	아웃로 목록
`founder`	string	마을 설립자
`registered`	number	마을 설립일 (Unix ms)
`joinedNationAt`	number	국가 가입일 (Unix ms)
`spawn`	string	마을 스폰 좌표

Example Request

GET https://api.planetearth.kr/town?name=Dev_Island

Example Response

{
  "status": "SUCCESS",
  "data": [
    {
      "name": "Dev_Island",
      "uuid": "36315f61-0685-4668-865c-87e0ca85cfda",
      "mayor": "aceda8",
      "nation": "Dev",
      "residents": "aceda8, ashpoints, Heiz, Irochi_, I_loveryo, LonelyUniverse_, MA5O, Maltes_, Royang_, Squirrel, TownyAPI, Virtual_Tabi, Yellim",
      "memberCount": 13,
      "onlineMemberCount": 1,
      "onlineMembers": "Heiz",
      "claimSize": 82,
      "balance": 512031.0,
      "townBoard": "d",
      "trustedResidents": "",
      "outlaws": "",
      "founder": "Irochi_",
      "registered": 1663982084499,
      "joinedNationAt": 1725978155425,
      "spawn": "world, -1682.9804406008402, 130.0, 5095.724900104271, 37.90424, 5.7425537"
    }
  ]
}

`GET /town/list`

모든 마을의 이름과 UUID 목록을 반환합니다.

Response Fields

필드	타입	설명
`name`	string	마을 이름
`uuid`	string	마을 UUID

Example Request

GET https://api.planetearth.kr/town/list

`GET /town/bulk`

모든 마을의 전체 정보를 반환합니다.
onlineMemberCount, onlineMembers 필드는 포함되지 않습니다.

Bulk Endpoint — 15분당 5회 제한

Example Request

GET https://api.planetearth.kr/town/bulk

국가

`GET /nation`

이름 또는 UUID로 국가 정보를 조회합니다.

Query Parameters

파라메터	타입	설명
`name`	string	국가 이름
`uuid`	string	국가 UUID

파라메터는 하나만 입력해야 합니다.

Response Fields

필드	타입	설명
`name`	string	국가 이름
`uuid`	string	국가 UUID
`capital`	string	수도 마을 이름
`leader`	string	국왕 닉네임
`towns`	string	소속 마을 목록 (`,` 구분)
`memberCount`	number	전체 주민 수
`balance`	number	국가 잔고
`allies`	string	동맹 국가 목록
`enemies`	string	적대 국가 목록
`nationBoard`	string	국가 게시판 내용
`registered`	number	국가 설립일 (Unix ms)

Example Request

GET https://api.planetearth.kr/nation?name=Dev

Example Response

{
  "status": "SUCCESS",
  "data": [
    {
      "name": "Dev",
      "uuid": "6bcf7309-d828-4a83-88fb-02a63d69d821",
      "capital": "Dev_Island",
      "leader": "aceda8",
      "towns": "Dev_Island",
      "memberCount": 13,
      "balance": 956188.0,
      "allies": "",
      "enemies": "",
      "nationBoard": "/nation set board [메세지]",
      "registered": 1725978155425
    }
  ]
}

`GET /nation/list`

모든 국가의 이름과 UUID 목록을 반환합니다.

Response Fields

필드	타입	설명
`name`	string	국가 이름
`uuid`	string	국가 UUID

Example Request

GET https://api.planetearth.kr/nation/list

`GET /nation/bulk`

모든 국가의 전체 정보를 반환합니다.

Bulk Endpoint — 15분당 5회 제한

Example Request

GET https://api.planetearth.kr/nation/bulk

주민

`GET /resident`

닉네임, UUID, 또는 마을 이름으로 주민 정보를 조회합니다.
마을 이름으로 조회 시 해당 마을 소속 주민 전체가 반환됩니다.

Query Parameters

파라메터	타입	설명
`name`	string	마인크래프트 닉네임
`uuid`	string	마인크래프트 UUID
`town`	string	마을 이름

파라메터는 하나만 입력해야 합니다.

Response Fields

필드	타입	설명
`name`	string	닉네임
`uuid`	string	UUID
`town`	string	소속 마을
`nation`	string	소속 국가
`townRanks`	string	마을 직위
`nationRanks`	string	국가 직위
`title`	string	칭호 (이름 앞)
`surname`	string	칭호 (이름 뒤)
`balance`	number	잔고
`friends`	string	친구 목록
`registered`	number	첫 접속일 (Unix ms)
`lastOnline`	number	마지막 접속일 (Unix ms)
`joinedTownAt`	number	마을 가입일 (Unix ms)
`online`	boolean	현재 온라인 여부

Example Request

GET https://api.planetearth.kr/resident?name=Irochi_

Example Response

{
  "status": "SUCCESS",
  "data": [
    {
      "name": "Irochi_",
      "uuid": "626dfe3b-7820-48c7-9974-1e332b4ffe60",
      "town": "Dev_Island",
      "nation": "Dev",
      "townRanks": "",
      "nationRanks": "군인, PVP",
      "title": "",
      "surname": "",
      "balance": 5448.0,
      "friends": "",
      "registered": 1663865955658,
      "lastOnline": 1777807004043,
      "joinedTownAt": 1766499540032,
      "online": false
    }
  ]
}

`GET /resident/list`

모든 주민의 이름과 UUID 목록을 반환합니다.

Response Fields

필드	타입	설명
`name`	string	닉네임
`uuid`	string	UUID

Example Request

GET https://api.planetearth.kr/resident/list

`GET /resident/bulk`

모든 주민의 전체 정보를 반환합니다.
online 필드는 포함되지 않습니다.

Bulk Endpoint — 15분당 5회 제한

Example Request

GET https://api.planetearth.kr/resident/bulk

디스코드

`GET /discord`

디스코드 ID, UUID, 또는 닉네임으로 마인크래프트 ↔ 디스코드 연동 정보를 조회합니다.
name 파라메터 사용 시 Mojang API를 통해 UUID로 변환합니다.

Query Parameters

파라메터	타입	설명
`discord`	string	디스코드 ID
`uuid`	string	마인크래프트 UUID
`name`	string	마인크래프트 닉네임

파라메터는 하나만 입력해야 합니다.

Response Fields

필드	타입	설명
`discord`	string	디스코드 ID
`uuid`	string	마인크래프트 UUID
`name`	string	마인크래프트 닉네임

Example Request

GET https://api.planetearth.kr/discord?name=Irochi_

Example Response

{
  "status": "SUCCESS",
  "data": [
    {
      "discord": "1086117494189723658",
      "uuid": "626dfe3b-7820-48c7-9974-1e332b4ffe60",
      "name": "Irochi_"
    }
  ]
}

거래소

`GET /auction`

닉네임, UUID, 또는 경매 ID로 현재 등록된 유저 거래소 아이템을 조회합니다.

Query Parameters

파라메터	타입	설명
`name`	string	판매자 닉네임
`uuid`	string	판매자 UUID
`id`	string	아이템 UUID

파라메터는 하나만 입력해야 합니다.

Response Fields

필드	타입	설명
`id`	string	아이템 UUID
`seller`	string	판매자 UUID
`sellerName`	string	판매자 닉네임
`price`	number	판매가
`expire_at`	string	경매 만료 일시
`itemInfo.type`	string	아이템 종류 (예: `minecraft:diamond_sword`)
`itemInfo.amount`	number	수량
`itemInfo.displayName`	string \| null	이름 (없을 경우 `null`)
`itemInfo.lore`	string[]	설명 줄 목록
`itemInfo.enchants`	object[]	인첸트 목록 (`{ id, level }`)

Example Request

GET https://api.planetearth.kr/auction?name=Steve

Example Response

{
  "status": "SUCCESS",
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "seller": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "sellerName": "Steve",
      "price": 5000,
      "expire_at": "2024-12-31T23:59:59.000Z",
      "itemInfo": {
        "type": "minecraft:diamond_sword",
        "amount": 1,
        "displayName": "전설의 검",
        "lore": ["강력한 힘이 깃든 검"],
        "enchants": [
          { "id": "minecraft:sharpness", "level": 5 },
          { "id": "minecraft:unbreaking", "level": 3 }
        ]
      }
    }
  ]
}

`GET /auction/list`

현재 거래소에 있는 모든 아이템을 반환합니다. 만료 일시 기준 오름차순 정렬.

Bulk Endpoint — 15분당 5회 제한

Example Request

GET https://api.planetearth.kr/auction/list

`GET /auction/transactions/list`

최근 거래소 거래 내역 100건을 최신 순으로 반환합니다.

Bulk Endpoint — 15분당 5회 제한

Response Fields

필드	타입	설명
`id`	string	거래 ID
`price`	number	거래 금액
`transaction_date`	string	거래 일시
`itemInfo`	object	아이템 정보 (`/auction`과 동일 구조)

Example Request

GET https://api.planetearth.kr/auction/transactions/list

Example Response

{
  "status": "SUCCESS",
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "price": 5000,
      "transaction_date": "2024-12-31T23:59:59.000Z",
      "itemInfo": {
        "type": "minecraft:diamond_sword",
        "amount": 1,
        "displayName": "전설의 검",
        "lore": ["강력한 힘이 깃든 검"],
        "enchants": [
          { "id": "minecraft:sharpness", "level": 5 }
        ]
      }
    }
  ]
}

온라인 플레이어

`GET /online`

현재 서버에 접속 중인 플레이어 목록을 반환합니다.

Example Request

GET https://api.planetearth.kr/online

Example Response

{
  "status": "SUCCESS",
  "data": {
    "total": 57,
    "players": [
      "Heiz",
      "Irochi_",
      "Ago",
      "Yellim",
      "..."
    ]
  }
}

활용 예시

디스코드 인증 봇 (Python)

!auth 명령어를 사용한 유저가 Dev_Island 마을 소속이면 역할을 지급하고 닉네임을 변경하는 예시입니다.

import discord
import requests

TOKEN = ""    # 봇 토큰
ROLE_ID = ""  # 지급할 역할 ID

intents = discord.Intents.all()
client = discord.Client(intents=intents)

@client.event
async def on_ready():
    print(f"Logged in as {client.user}")

@client.event
async def on_message(message):
    if message.author == client.user:
        return

    if not message.content.startswith("!auth"):
        return

    # 1. 디스코드 ID → 마인크래프트 UUID 조회
    res = requests.get(f"https://api.planetearth.kr/discord?discord={message.author.id}").json()
    if res["status"] != "SUCCESS":
        await message.channel.send("플래닛어스 디스코드에 인증되지 않은 유저입니다.")
        return

    uuid = res["data"][0]["uuid"]

    # 2. UUID → 주민 정보 조회
    res = requests.get(f"https://api.planetearth.kr/resident?uuid={uuid}").json()
    if res["status"] != "SUCCESS":
        await message.channel.send("타우니 데이터를 가져올 수 없습니다.")
        return

    resident = res["data"][0]

    # 3. 마을 확인 후 역할 지급
    if resident["town"] != "Dev_Island":
        await message.channel.send("Dev_Island 마을에 가입되지 않은 플레이어입니다.")
        return

    guild = message.guild
    role = discord.utils.get(guild.roles, id=int(ROLE_ID))
    await message.author.add_roles(role)
    await message.author.edit(nick=resident["name"])
    await message.channel.send("인증에 성공했습니다! 권한을 지급합니다.")

client.run(TOKEN)

기본 정보​

요청 제한​

응답 형식​

에러 코드​

엔드포인트​

마을​

GET /town​

GET /town/list​

GET /town/bulk​

국가​

GET /nation​

GET /nation/list​

GET /nation/bulk​

주민​

GET /resident​

GET /resident/list​

GET /resident/bulk​

디스코드​

GET /discord​

거래소​

GET /auction​

GET /auction/list​

GET /auction/transactions/list​

온라인 플레이어​

GET /online​

활용 예시​

디스코드 인증 봇 (Python)​

기본 정보

요청 제한

응답 형식

에러 코드

엔드포인트

마을

`GET /town`

`GET /town/list`

`GET /town/bulk`

국가

`GET /nation`

`GET /nation/list`

`GET /nation/bulk`

주민

`GET /resident`

`GET /resident/list`

`GET /resident/bulk`

디스코드

`GET /discord`

거래소

`GET /auction`

`GET /auction/list`

`GET /auction/transactions/list`

온라인 플레이어

`GET /online`

활용 예시

디스코드 인증 봇 (Python)