문서

지리 정보

마인크래프트 좌표를 넣으면 현실에서 어디인지 알려드립니다.

이 문서의 목차 (5)

마코노미의 월드는 실제 지구를 축소한 지형입니다.
그래서 좌표 하나만 있으면 그곳이 현실에서 어느 나라인지, 어느 도시 근처인지 알 수 있습니다.

좌표 → 지리#

GET /v1/location/resolve?world={월드}&x={x}&z={z}

키 필요

curl -H "Authorization: Bearer ml_…" \
     "https://api.mcmi.kr/v1/location/resolve?x=26005&z=-7693"

{
  "data": {
    "input": { "world": "world", "x": 26005, "z": -7693 },
    "coordinates": { "latitude": 37.5665, "longitude": 126.978 },
    "ocean": false,
    "country": {
      "name": "대한민국",
      "officialName": "대한민국",
      "englishName": "South Korea",
      "iso": "KR",
      "type": "SOVEREIGN_COUNTRY",
      "continent": "Asia"
    },
    "nearest_city": { "name": "서울", "realDistanceKm": 2.4, "blockDistance": 4 },
    "coast": { "distanceKm": 28.1, "blockDistance": 52 },
    "layers": {}
  }
}

질의 변수#

변수기본값설명
worldworld월드 이름
x필수마인크래프트 X 좌표
z필수마인크래프트 Z 좌표

Y(높이)는 받지 않습니다. 지리 판정에 쓰이지 않기 때문입니다.

읽으실 때 주의하실 점#

중요

이름이 세 개인 이유#

  • name — 서버 언어 설정에 따른 이름입니다. 바뀔 수 있습니다
  • officialName — 정식 국호
  • englishName — 영문명. 저장하거나 비교하실 키로는 이걸 쓰세요

국가가 같은지 비교하실 때 name 을 쓰시면 서버 설정이 바뀌는 순간 어긋납니다.

중요

거리가 두 개인 이유#

  • realDistanceKm — 실제 지구 거리(km). 사람에게 보여드릴 값입니다
  • blockDistance — 맵 위 블록 거리. 이동 시간이나 범위 판정에 쓰실 값입니다

지도를 평면에 펼친 방식이라 고위도로 갈수록 두 값이 크게 벌어집니다.
blockDistance 는 null 일 수 있으니 꼭 확인하고 쓰세요.

참고

바다와 "모름"은 다릅니다#

  • ocean: true 이고 country 가 없으면(비어 있으면) 바다 위예요. 정상적인 답이에요.
  • 404 → 그 월드에 지리 정보 자체가 없습니다

둘을 같게 처리하시면 바다에 있는 분을 "위치 불명"으로 보여주시게 됩니다.

경고

이 엔드포인트는 게임 서버 안의 판정 결과를 가져옵니다.
브릿지가 준비되지 않은 동안에는 503 이 옵니다 — 잠시 뒤 다시 시도해 주세요.

활용 예시#

const url = new URL("https://api.mcmi.kr/v1/location/resolve");
url.searchParams.set("x", x);
url.searchParams.set("z", z);

const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
if (res.status === 503) return "지리 정보를 잠시 볼 수 없어요";
if (res.status === 404) return "이 월드는 지리 정보가 없어요";

const { data } = await res.json();
if (data.ocean) return "바다 한가운데입니다 🌊";

const city = data.nearest_city;
return `${data.country.name} — ${city.name}에서 ${city.realDistanceKm}km`;

참고 사항#

이 지리 API는 서버 상태가 좋지 못할 경우 오류를 반환합니다.

API 개요 · 유저 상점

댓글

댓글은 마코노미 디스코드 서버 멤버만 쓸 수 있어요. 디스코드로 로그인