API Wardog Servers

Обзор

Базовый URL — https://api.wardogservers.com. Все ответы приходят в JSON, для чтения ключ API не нужен.

Полный контракт опубликован в виде документа OpenAPI 3.1 по адресу https://api.wardogservers.com/openapi.json ↗. Источник истины — этот документ, а эта страница — его краткое изложение.

• Сборщик опрашивает браузер серверов в игре во всех регионах примерно раз в минуту. Текущий интервал указан в каждом ответе в поле 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, прежде чем показывать цифры как актуальные. Оно равно true, если сбор данных приостановлен или снимок старше, чем refreshSeconds плюс 60 секунд. Устаревшие ответы также отправляются с 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 — интервал, в котором ничего не записано, обычно потому, что сборщик был на паузе. Показывай разрыв, не интерполируй.

Интервалы записываются один раз на снимок с момента включения истории, без заполнения задним числом. Минутные интервалы хранятся 7 дней, пятиминутные — 90 дней, часовые — бессрочно.

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 с максимальным значением одного снимка в каждом интервале. Эндпоинт тепловой карты усредняет метрику по дням недели и часам UTC за последние 28 полных дней, при желании — для одного региона. Peaks возвращает максимальное число игроков в одном снимке в целом и по типам — за всё время и за каждые из последних 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 (вариант, мир или небо), 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 ищет точное совпадение с кодом подключения или последнее известное название без учёта регистра, так что находит и сервер, который сейчас офлайн; у серверов онлайн serverId и так есть в /v1/servers.

Кэширование и опрос

Каждый ответ содержит ETag. Отправь его обратно в If-None-Match, и если снимок не изменился, придёт 304 без тела — это почти ничего не стоит ни одной из сторон. Задуманный сценарий — опрос раз в минуту с If-None-Match.

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'); // Сборщик отстаёт; продолжай показывать последние известные данные

Свежие ответы кэшируются на edge-серверах на 15 секунд, так что всплески одинаковых запросов обходятся дёшево. Жёсткого лимита запросов сейчас нет, но опрос чаще meta.refreshSeconds не даст более новых данных и в будущем может ограничиваться. Если нужен весь список, загрузи /v1/snapshot один раз и фильтруй локально, а не листай /v1/servers по страницам.

Ошибки

Ошибки приходят в JSON со стабильным кодом и понятным человеку сообщением. Сообщение может меняться, так что ориентируйся на код.

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

Условия использования

API бесплатен для проектов сообщества: Discord-ботов, оверлеев, дашбордов, исследований. Если показываешь данные публично, укажи Wardog Servers со ссылкой и не выдавай их за официальные данные BULKHEAD или Team17.

API для чтения версионируется под /v1. В рамках версии могут добавляться новые поля, так что спокойно относись к незнакомым ключам. Ломающие изменения выйдут в новой версии и сначала будут объявлены на этой странице.

Вопросы, проект, которым хочется похвастаться, или нужное поле: Discord @xcausxn.