Wardog Servers API

개요

기본 URL: https://api.wardogservers.com. 모든 응답은 JSON이고, 읽기에는 API 키가 필요 없어요.

전체 명세는 https://api.wardogservers.com/openapi.json ↗에 OpenAPI 3.1 문서로 공개돼 있어요. 기준은 그 문서이고, 이 페이지는 읽기 쉽게 정리한 요약이에요.

• 수집기는 모든 지역의 게임 내 서버 브라우저를 약 1분마다 조회해요. 현재 주기는 모든 응답의 meta.refreshSeconds에 나와요.
• 브라우저 요청은 wardogservers.com에서 온 것만 받아요. 다른 도메인의 웹 페이지가 아니라 직접 운영하는 서버, 봇, 스크립트에서 API를 호출하세요.
• 알 수 없거나 중복되었거나 형식이 잘못된 쿼리 파라미터는 무시하지 않고 400으로 거부해요. 그래서 오타가 있으면 조용히 전체 결과를 돌려주는 대신 확실하게 실패해요.

빠른 시작

대부분은 요청 세 가지로 충분해요: 현재 합계, 필터에 맞는 가장 붐비는 서버, 인스턴스 ID로 조회하는 서버 하나.

# 현재 합계
curl https://api.wardogservers.com/v1/stats

# 참가할 자리가 있는 유럽 서부 커뮤니티 서버, 붐비는 순
curl "https://api.wardogservers.com/v1/servers?region=eu-west&type=community&hideFull=true&limit=10"

# 인스턴스 ID로 서버 하나 조회
curl https://api.wardogservers.com/v1/servers/$ID

/v1/stats 응답을 줄여 보면 이래요:

{
  "data": {
    "serverCount": 3544,
    "playerCount": 252109,
    "officialServerCount": 2765,
    "communityServerCount": 779
  },
  "meta": {
    "fetchedAt": "2026-09-13T12:54:57.302Z",
    "snapshotId": "95635cb938811a34…",
    "refreshSeconds": 60,
    "stale": false,
    "requestedRegions": ["asia-east", "asia-southeast", "…"],
    "observedRegions": ["asia-east", "asia-west", "…"]
  }
}

엔드포인트

모든 읽기 엔드포인트는 GET과 HEAD를 받고, If-None-Match를 지원하며, 아래에 설명한 응답 엔벨로프를 써요.

서버 목록 필터링

/v1/servers의 모든 파라미터는 선택 사항이에요. q를 제외한 값은 대소문자를 구분해요.

응답 엔벨로프

성공한 응답에는 항상 data와 meta가 있어요. 목록 엔드포인트에는 pagination이 추가되고, 기록 엔드포인트에는 기간, 그룹, 지표, 버킷 크기를 설명하는 history 객체가 추가돼요.

수치를 현재 값으로 보여 주기 전에 meta.stale을 확인하세요. 수집이 멈췄거나 스냅샷이 refreshSeconds + 60초보다 오래되면 true예요. 오래된 응답에는 Cache-Control: no-store와 X-Data-Stale: true도 함께 붙어요.

서버 객체

/v1/servers와 /v1/snapshot이 반환하는 요약 형태예요. /v1/servers/{id}에서는 같은 필드에 attributes, build, level, cash를 더해 반환해요.

{
  "id": "001ab36e-9985-4a9c-8dff-9dc137826dfe",
  "serverId": "756872",
  "serverIdUpdatedAt": "2026-09-13T11:14:32.995Z",
  "name": "Official #4",
  "nativeName": "f14859cce268",
  "type": "official",
  "region": "eu-south",
  "players": 100,
  "maxPlayers": 100,
  "reservedPlayers": 0,
  "passwordProtected": false,
  "serverNumber": 4,
  "map": { "variant": "Bakurani", "base": "Europe" },
  "mode": { "experience": "Bakurani_KOTH_01", "gameMode": "GM_Session_C", "modifiers": [] },
  "rulesets": ["standard"]
}

기록

/v1/history/players는 열 형식 시계열을 반환해요: 버킷 시작 시각(Unix 초) 배열 하나와 그룹 키마다 값 배열 하나가 인덱스로 맞춰져 있어요. null 값은 아무것도 기록되지 않은 버킷으로, 보통 수집기가 멈췄던 경우예요. 보간하지 말고 빈 구간으로 표시하세요.

버킷은 기록 기능을 켠 순간부터 스냅샷마다 한 번씩 기록되고, 과거 데이터를 채워 넣지는 않아요. 1분 버킷은 7일, 5분 버킷은 90일, 1시간 버킷은 무기한 보관해요.

GET /v1/history/players?window=24h&group=type

{
  "data": {
    "t": [1789217880, 1789217940, 1789218000, "…"],
    "series": {
      "official": [248112, 248390, null, "…"],
      "community": [3902, 3911, null, "…"]
    },
    "peak": { "official": ["…"], "community": ["…"] }
  },
  "history": {
    "window": "24h", "group": "type", "metric": "players",
    "step": 60, "from": 1789217880, "to": 1789304280, "since": 1789257600
  },
  "meta": { "…": "…" }
}

metric=players일 때는 응답에 각 버킷에서 가장 높았던 단일 스냅샷 값을 담은 peak 객체도 들어 있어요. 히트맵 엔드포인트는 최근 28일(온전한 날 기준) 동안 UTC 요일·시간대별 지표 평균을 내고, 지역 하나로 좁힐 수도 있어요. 최고치 엔드포인트는 단일 스냅샷 기준 최고 플레이어 수를 전체와 유형별로, 역대 및 최근 30일(UTC) 각각에 대해 알려 줘요.

서버별 기록

서버별 기록은 참가 코드를 키로 써요. 참가 코드는 인스턴스 ID와 달리 재시작과 맵 변경 후에도 유지돼요. /v1/history/servers/{serverId}에서는 인덱스로 맞춘 배열을 반환해요: 서버가 목록에 있던 동안의 평균 플레이어 수와 단일 조회 최고치, 최대 인원, 버킷 안에서 서버가 목록에 있었던 조회 비율(가동률, 0~1), 버킷이 끝날 때의 맵. 그래서 연속된 맵 값을 보면 로테이션을 알 수 있어요. 코드를 처음 본 순간부터 기록하고 과거 데이터는 채우지 않으며, 그 전까지 이 경로는 404를 반환해요.

GET /v1/history/servers/756872?window=24h

{
  "data": {
    "server": {
      "serverId": "756872",
      "name": "Official #4",
      "type": "official",
      "region": "eu-south",
      "instanceId": "001ab36e-9985-4a9c-8dff-9dc137826dfe",
      "firstSeen": "2026-09-13T00:00:39.000Z",
      "lastSeen": "2026-09-14T11:53:22.000Z",
      "samples": 2132,
      "live": true
    },
    "t": [1789300800, 1789301100, 1789301400, "…"],
    "players": [100, 98, null, "…"],
    "peak": [100, 100, null, "…"],
    "capacity": [100, 100, null, "…"],
    "online": [1, 0.8, null, "…"],
    "map": ["Bakurani", "Bakurani", null, "…"]
  },
  "history": {
    "window": "24h", "step": 300,
    "from": 1789300800, "to": 1789387200, "since": 1789257600
  },
  "meta": { "…": "…" }
}

/v1/history/servers/{serverId}/events에서는 연속된 조회 결과로 변경 기록을 만들어 최신순으로 반환해요: tracking_started, online, offline, restart(공백 없이 인스턴스가 바뀜), build(changelist), map(variant, world, sky), modifiers, limits(레벨·자금 범위, 비밀번호, 최대 인원). 각 이벤트에는 at, kind, 그리고 해당 종류를 정의하는 필드만 담은 before와 after 객체가 있고, 이전이나 이후 상태가 없으면 null이에요. limit은 1~500이고 기본값은 100이에요.

GET /v1/history/servers/756872/events?limit=3

{
  "data": {
    "server": { "serverId": "756872", "name": "Official #4", "…": "…" },
    "events": [
      {
        "at": "2026-09-14T12:40:30.000Z",
        "kind": "map",
        "before": { "map": "Madrid", "world": "Europe", "sky": "DayEarlyFog" },
        "after": { "map": "Detroit", "world": "Europe", "sky": "DayLateGray" }
      },
      {
        "at": "2026-09-14T09:12:04.000Z",
        "kind": "restart",
        "before": { "instanceId": "001ab36e-9985-4a9c-8dff-9dc137826dfe" },
        "after": { "instanceId": "7c1e0b52-3d9a-4e1f-9b6e-2f4c8a9d0e11" }
      },
      {
        "at": "2026-09-13T00:00:39.000Z",
        "kind": "tracking_started",
        "before": null,
        "after": { "instanceId": "…", "changelist": "501228", "map": "Bakurani", "…": "…" }
      }
    ]
  },
  "history": { "limit": 3, "since": 1789257600 },
  "meta": { "…": "…" }
}

/v1/history/servers는 기록된 서버를 최근에 본 순서로 보여 줘요. q는 참가 코드와는 정확히, 마지막으로 알려진 이름과는 대소문자 구분 없이 일치하는지 보기 때문에 지금 오프라인인 서버도 찾을 수 있어요. 온라인 서버는 이미 /v1/servers에 serverId가 들어 있어요.

캐싱과 폴링

모든 응답에는 ETag가 있어요. 이를 If-None-Match로 다시 보내면 스냅샷이 바뀌지 않은 경우 본문 없이 304로 응답하므로, 양쪽 모두 비용이 거의 들지 않아요. If-None-Match와 함께 1분에 한 번 조회하는 게 의도된 사용 방식이에요.

const res = await fetch('https://api.wardogservers.com/v1/snapshot', {
  headers: lastEtag ? { 'if-none-match': lastEtag } : {}
});
if (res.status === 304) return; // 마지막 조회 이후 바뀐 게 없음
lastEtag = res.headers.get('etag');
const { data, meta } = await res.json();
if (meta.stale) console.warn('stale'); // 수집기가 늦어지는 중. 마지막으로 받은 데이터를 계속 표시

최신 응답은 엣지에서 15초 동안 캐시되므로 같은 요청이 몰려도 부담이 적어요. 지금은 엄격한 요청 제한이 없지만, meta.refreshSeconds보다 자주 조회해도 더 새로운 데이터는 받을 수 없고 앞으로 속도가 제한될 수 있어요. 전체 목록이 필요하면 /v1/servers를 페이지별로 넘기지 말고 /v1/snapshot을 한 번 받아서 로컬에서 필터하세요.

오류

오류는 고정된 code와 사람이 읽을 수 있는 message가 담긴 JSON이에요. message는 바뀔 수 있으니 code로 판별하세요.

{
  "error": {
    "code": "bad_request",
    "message": "An unsupported query parameter was supplied."
  }
}

이용 조건

API는 커뮤니티 프로젝트에 무료예요: Discord 봇, 오버레이, 대시보드, 연구. 데이터를 공개적으로 보여 줄 때는 Wardog Servers 링크로 출처를 밝히고, BULKHEAD나 Team17의 공식 데이터처럼 보이게 하지 마세요.

읽기 API는 /v1 버전으로 관리돼요. 같은 버전 안에서도 새 필드가 추가될 수 있으니 모르는 키가 있어도 문제없게 처리하세요. 호환성이 깨지는 변경은 새 버전으로 내고, 이 페이지에서 먼저 알릴게요.

질문, 자랑하고 싶은 프로젝트, 필요한 필드가 있다면: Discord @xcausxn.