Перейти к содержимому
ВладельцамДобавить сервер

API для разработчиков

Данные каталога для ботов, сайтов кланов и виджетов: состояние сервера, списки серверов игры, история онлайна, игры и вайпы. Числа те же, что на сайте, — после вычета ботов и копий. Онлайн, которому мы не верим, в API не выдаётся за настоящий: у каждого сервера есть поле trust.

Адресhttps://battlemetrics.ru/api/v1
  1. Войдите и выпустите ключ — ниже, в разделе «Ключи и лимиты».
  2. Передавайте его в заголовке Authorization: Bearer bm_live_….
  3. Ответ — JSON в UTF-8, время — ISO 8601 в UTC, поля — snake_case.

Адреса /api/… без v1 обслуживают страницы самого сайта. У них нет версий и обещаний совместимости — строить на них ничего не стоит: сломается без предупреждения.

Запрос
curl https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 200
{
  "id": 51716811,
  "game": "minecraft",
  "name": "DonutSMP.net ѕᴜʀᴠɪᴠᴀʟ",
  "address": "40.223.14.114:25565",
  "ip": "40.223.14.114",
  "port": 25565,
  "query_port": 25565,
  "map": null,
  "country": "us",
  "online": true,
  "players": 24803,
  "max_players": 50000,
  "queue": 0,
  "trust": "confirmed",
  "uptime": 0.968,
  "last_seen": "2026-10-13T01:45:13.051Z",
  "last_wipe": null,
  "promoted": false,
  "url": "https://battlemetrics.ru/game/minecraft/server/51716811",
  "game_name": "Minecraft: Java Edition",
  "players_raw": 24803,
  "bots": 0,
  "canonical_id": null,
  "flagged_at": null,
  "version": "Velocity 1.7.2-26.3",
  "rating": null,
  "review_count": 0,
  "first_seen": "2026-10-08T18:28:30.526Z"
}

Ключи и лимиты

Ключ бесплатный и выпускается сразу. Действующих ключей может быть три: например, для рабочего бота, для разработки и запасной. Целиком ключ показывается один раз — у нас хранится только его свёртка. Потеряли — отзовите и выпустите новый.

Лимит — 60 запросов в минуту на ключ. После паузы можно сделать до 60 подряд, дальше запросы восстанавливаются по одному в секунду. Остаток видно в каждом ответе, в заголовках X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset; при превышении приходит 429 с заголовком Retry-After.

Бесплатно: 60 запросов/минС продвижением: 600 запросов/мин · скоро

Данные обновляются раз в минуту, поэтому ответы можно кэшировать на 15 секунд — чаще спрашивать бесполезно. Ключ секретный: не кладите его в код страницы, которую открывает браузер, — его увидит любой. Показываете наши данные у себя — поставьте ссылку на battlemetrics.ru; это условие из условий использования, п. 8.

Запрос
curl -i https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Заголовки ответа
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-ratelimit-limit: 60
x-ratelimit-remaining: 59
x-ratelimit-reset: 1
cache-control: private, max-age=15

Ошибки

Любая ошибка — это JSON одной формы: code для программы, message для человека. Сообщение может меняться, код — нет.

Коды
400 bad_requestпараметрыПараметр не того вида: в сообщении сказано, какой и что ждём
401 unauthorizedключКлюча нет, он не похож на наш или такого нет
401 key_revokedключКлюч отозван владельцем
403 account_blockedключУчётная запись владельца ключа закрыта
403 forbiddenключГолоса сервера — только ключом из аккаунта его подтверждённого владельца
404 not_foundданныеНет такого сервера, игры или метода
409 untrustedданныеИсторию онлайна сервера, которому мы не верим, не отдаём
429 rate_limitedлимитПревышен лимит; сколько ждать — в Retry-After
500 internalмыОшибка у нас; она уже в журнале
502 · 503 · 504мыСайт не отвечает или на техработах — повторите позже

Тридцать запросов с неверным ключом за минуту с одного адреса — это перебор, а не опечатка: дальше адрес получает 429, пока минута не пройдёт.

Запрос
curl https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 429
{
  "error": {
    "code": "rate_limited",
    "message": "Не больше 60 запросов в минуту на ключ."
  }
}
GET/v1/servers/{id}

Текущее состояние сервера. Онлайн — только подтверждённый антифродом; сырое значение сервера отдаётся отдельным полем.

Поля ответа
playersint | nullПодтверждённый онлайн. null, если trust не confirmed
players_rawintЧто сообщает сам сервер
trustenumconfirmed · suspicious · mirror · farm
last_wipedatetimeВремя последнего вайпа, ISO 8601
promotedboolПлатное место сейчас активно
id · game · nameint · stringНомер, код игры, название
addressstringАдрес для подключения: ip:port
port · query_portintИгровой порт и порт опроса A2S
map · countrystring | nullКарта и код страны
onlineboolОтвечает ли сервер сейчас
max_players · queueintСлоты и очередь
botsintБотов, которых сервер сообщил
uptimefloatДоля времени в сети за неделю, от 0 до 1
canonical_idint | nullДля копии — оригинал, который мы показываем
flagged_atdatetime | nullКогда поставлена пометка
rating · review_countfloat | null · intОценка по отзывам и их число
first_seen · last_seendatetimeКогда впервые увидели и когда ответил последний раз
urlstringКарточка на сайте
Бесплатно: 60 запросов/минС продвижением: 600 запросов/мин · скоро
Запрос
curl https://battlemetrics.ru/api/v1/servers/51716811 \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 200
{
  "id": 51716811,
  "game": "minecraft",
  "name": "DonutSMP.net ѕᴜʀᴠɪᴠᴀʟ",
  "address": "40.223.14.114:25565",
  "ip": "40.223.14.114",
  "port": 25565,
  "query_port": 25565,
  "map": null,
  "country": "us",
  "online": true,
  "players": 24803,
  "max_players": 50000,
  "queue": 0,
  "trust": "confirmed",
  "uptime": 0.968,
  "last_seen": "2026-10-13T01:45:13.051Z",
  "last_wipe": null,
  "promoted": false,
  "url": "https://battlemetrics.ru/game/minecraft/server/51716811",
  "game_name": "Minecraft: Java Edition",
  "players_raw": 24803,
  "bots": 0,
  "canonical_id": null,
  "flagged_at": null,
  "version": "Velocity 1.7.2-26.3",
  "rating": null,
  "review_count": 0,
  "first_seen": "2026-10-08T18:28:30.526Z"
}
GET/v1/servers

Список серверов игры — тот же, что на странице игры: только видимые серверы, по умолчанию только отвечающие сейчас. Помеченных в списке нет.

Параметры
gamestringКод игры, обязателен. Коды — в GET /games
sortenumplayers · fill · ping · wipe · rank · name; по умолчанию players
pageintСтраница, от 1 до 100
per_pageenum20 · 50 · 100
countrystringКод страны: RU, DE…
mapstringТочное название карты
min_playersintНе меньше стольких игроков
qstringЧасть названия, от 3 до 60 символов
offlinebool1 — показать и не отвечающих
Поля ответа
total · pagesintСколько серверов подходит и сколько страниц
servers[]arrayСтроки: те же поля, что у GET /servers/{id}, без players_raw, bots, rating и истории пометок
Запрос
curl https://battlemetrics.ru/api/v1/servers?game=rust&per_page=20 \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 200
{
  "game": "rust",
  "page": 1,
  "per_page": 20,
  "total": 10028,
  "pages": 502,
  "servers": [
    {
      "id": 50208245,
      "game": "rust",
      "name": "Rusty Moose |US Mondays|",
      "address": "205.178.168.77:28010",
      "ip": "205.178.168.77",
      "port": 28010,
      "query_port": 28015,
      "map": "Moose Maps",
      "country": "us",
      "online": true,
      "players": 791,
      "max_players": 825,
      "queue": 0,
      "trust": "confirmed",
      "uptime": 0.7,
      "last_seen": "2026-10-13T01:45:12.096Z",
      "last_wipe": "2026-10-12T18:59:04.000Z",
      "promoted": false,
      "url": "https://battlemetrics.ru/game/rust/server/50208245"
    },
    {
      "id": 50209359,
      "game": "rust",
      "name": "US | Helli's Aimtrain | Facechecks/1v1/Speargun/Hellis",
      "address": "64.40.8.243:28015",
      "ip": "64.40.8.243",
      "port": 28015,
      "query_port": 27017,
      "map": "Custom Map",
      "country": "us",
      "online": true,
      "players": 781,
      "max_players": 825,
      "queue": 0,
      "trust": "confirmed",
      "uptime": 0.991,
      "last_seen": "2026-10-13T01:45:12.096Z",
      "last_wipe": "2026-10-12T11:01:03.000Z",
      "promoted": false,
      "url": "https://battlemetrics.ru/game/rust/server/50209359"
    },
    … ещё 18
  ]
}
GET/v1/servers/{id}/history

История онлайна с тем же шагом, что у графика на карточке. Точка — средний онлайн за шаг по ответившим замерам; шаг, где сервер не ответил ни разу, пропущен, а не записан нулём. Серверам с пометкой историю не отдаём — 409.

Параметры
periodenum24h — шаг 5 минут · 7d — шаг час · 30d — шаг сутки
Поля ответа
step_secintШаг точек в секундах
points[].tdatetimeНачало шага
points[].playersintСредний онлайн за шаг
Запрос
curl https://battlemetrics.ru/api/v1/servers/51716811/history?period=24h \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 200
{
  "server_id": 51716811,
  "period": "24h",
  "step_sec": 300,
  "points": [
    {
      "t": "2026-10-12T01:45:00.000Z",
      "players": 29599
    },
    {
      "t": "2026-10-12T01:50:00.000Z",
      "players": 29518
    },
    {
      "t": "2026-10-12T01:55:00.000Z",
      "players": 29369
    },
    … ещё 286
  ]
}
GET/v1/servers/{id}/votes

Для плагина сервера: голосовал ли игрок за последние сутки и есть ли за это незабранная награда. Игрок указывает ник, когда голосует на карточке. Только ключом из аккаунта подтверждённого владельца этого сервера — иначе 403. Без nick — счёт голосов за месяц и место в игре.

Параметры
nickstringНик в игре, до 32 символов; регистр не важен
Поля ответа
votedboolГолосовал за последние 24 часа
unclaimedintСколько голосов за сутки ещё без выданной награды
last_vote_atdatetime · nullКогда голосовал последний раз за сутки
votes_monthintГолоса этого ника за календарный месяц
Запрос
curl https://battlemetrics.ru/api/v1/servers/{id}/votes?nick=Steve \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 200
{
  "server": 123,
  "nick": "Steve",
  "voted": true,
  "last_vote_at": "2026-09-27T10:15:00.000Z",
  "unclaimed": 1,
  "votes_month": 12
}
GET/v1/servers/{id}/votes/claim

Плагин выдал награду — отметьте голос, чтобы не выдать её дважды. Отмечается самый свежий незабранный голос ника за сутки; claimed: false — забирать нечего. Тело — JSON {"nick": "…"}.

Поля ответа
claimedboolНаграда отмечена
vote_atdatetime · nullКогда был отмеченный голос
Запрос
curl -X POST https://battlemetrics.ru/api/v1/servers/{id}/votes/claim \
  -H "Authorization: Bearer bm_live_••••" \
  -H "content-type: application/json" -d '{"nick":"Steve"}'
Ответ · 200
{
  "server": 123,
  "nick": "Steve",
  "claimed": true,
  "vote_at": "2026-09-27T10:15:00.000Z"
}
GET/v1/games

Все игры каталога и их онлайн сейчас. Игра без онлайна в эту минуту остаётся в списке с нулями: её код нужен для GET /servers.

Поля ответа
code · namestringКод для других методов и название
playersintПодтверждённый онлайн игры
servers_onlineintВидимых серверов, отвечающих сейчас
servers_visibleintВидимых серверов всего
Запрос
curl https://battlemetrics.ru/api/v1/games \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 200
{
  "games": [
    {
      "code": "fivem",
      "name": "FiveM",
      "players": 149662,
      "servers_online": 32562,
      "servers_visible": 106448,
      "url": "https://battlemetrics.ru/game/fivem"
    },
    {
      "code": "minecraft",
      "name": "Minecraft: Java Edition",
      "players": 76166,
      "servers_online": 1380,
      "servers_visible": 1485,
      "url": "https://battlemetrics.ru/game/minecraft"
    },
    {
      "code": "rust",
      "name": "Rust",
      "players": 45156,
      "servers_online": 10031,
      "servers_visible": 35939,
      "url": "https://battlemetrics.ru/game/rust"
    },
    … ещё 120
  ]
}
GET/v1/wipes

Вайпы игры: случившиеся или обещанные. Это два разных знания, и поле fact их различает: true — вайп мы застали сами, false — дата из описания сервера, то есть обещание владельца.

Параметры
gamestringКод игры, обязателен
whenenumupcoming — обещанные · past — случившиеся
hoursintОкно: до 336 часов вперёд или до 168 назад; по умолчанию 24
limitintДо 200 строк, по умолчанию 50
Поля ответа
atdatetimeМомент вайпа
factboolНаблюдение (true) или обещание (false)
cycleenum | nullweekly · biweekly · monthly · other
server_id · name · urlint · stringКакой сервер
Запрос
curl https://battlemetrics.ru/api/v1/wipes?game=rust&when=upcoming \
  -H "Authorization: Bearer bm_live_••••"
Ответ · 200
{
  "game": "rust",
  "when": "upcoming",
  "hours": 24,
  "wipes": [
    {
      "server_id": 278400,
      "name": "[BR/LATAM] Raidados.top 2X MAX4 | Vanilla+ | Wipe 10/10",
      "at": "2026-10-13T10:00:00.000Z",
      "fact": false,
      "cycle": "other",
      "players": 3,
      "max_players": 60,
      "country": "br",
      "url": "https://battlemetrics.ru/game/rust/server/278400"
    },
    {
      "server_id": 5449231,
      "name": "GOLD RUST X10/MAX5 | ДЛЯ НОВИЧКОВ",
      "at": "2026-10-13T10:00:00.000Z",
      "fact": false,
      "cycle": "other",
      "players": 0,
      "max_players": 100,
      "country": "ru",
      "url": "https://battlemetrics.ru/game/rust/server/5449231"
    },
    … ещё 5
  ]
}

Сайт использует cookie: необходимые — для входа и темы, а также счётчики посещений Яндекс Метрика и LiveInternet — по ним мы видим, как пользуются сайтом. Рекламных cookie у нас нет. Подробнее