API MonWave

Открытые данные мониторинга в JSON: игры, серверы, статистика и виджеты для сайтов. Без регистрации и без ключа. Владельцам серверов — отдельное API с личным ключом: голоса игроков и награда за голос.
Без регистрации
Публичные методы работают без ключа
Прямо из браузера
Публичные методы разрешены с любых сайтов (CORS)
JSON, UTF-8
Данные в data, страницы списка — в meta
Свежесть
Серверы опрашиваются раз в 10–15 минут; ответ можно кэшировать 60 секунд
Адрес API
https://monwave.ru/api/v1

Старая форма адреса https://monwave.ru/api?endpoint=servers&game=cs2 тоже работает.

Методы

МетодЧто отдаёт
GET /gamesВсе игры: slug, названия, число серверов, ссылка на раздел
GET /servers?game=cs2Серверы игры по рейтингу. page — страница, limit — сколько на странице (1–100, по умолчанию 25). Поля: id, name, address, players, max_players, map, country, rating, url. Недоступные сейчас серверы тоже в списке — в конце
GET /servers/{id}Один сервер: то же плюс средний онлайн, доля ответов на опросы (uptime, %), дата добавления и last_offline — с какого момента сервер недоступен (null — сервер онлайн)
GET /servers/lookup?address=203.0.113.10:27015Тот же ответ, но по адресу сервера (IP или домен с портом) — если не знаете номер сервера на monwave
GET /statsВсего серверов, игр и игроков онлайн. С ?game=cs2 — по одной игре: серверы, игроки, среднее число игроков на сервере и наибольший онлайн одного сервера — сейчас
GET /widget/{id}Картинка-виджет сервера (SVG). theme=light — светлая, format=html — HTML-версия для iframe. Вместо номера можно адрес: /widget?ip=203.0.113.10:27015

Серверы из чёрного списка в ответы и виджеты не попадают.

Пример ответа

GET /api/v1/servers?game=cs2&limit=1

{"data": [{"id": 12345, "name": "Мой сервер", "address": "203.0.113.10:27015", "game": "cs2",
           "players": 18, "max_players": 32, "map": "de_mirage", "country": "RU", "rating": 54,
           "url": "https://monwave.ru/cs2/servers/203.0.113.10:27015"}],
 "meta": {"game": "cs2", "page": 1, "limit": 1, "total": 862, "pages": 862}}

Нужно больше: запросы с параметрами по каждому методу — в конструкторе запросов.

Примеры

const res  = await fetch("https://monwave.ru/api/v1/servers?game=cs2&limit=25");
if (!res.ok) throw new Error(`monwave: ${res.status}`); // 429/503 — повторить позже
const json = await res.json();

console.log(`Серверов: ${json.meta.total}`);
json.data.forEach(s => console.log(`${s.name} — ${s.players}/${s.max_players}`));
import requests

r = requests.get("https://monwave.ru/api/v1/servers",
                 params={"game": "cs2", "limit": 25}, timeout=10)
r.raise_for_status()  # 429/503 — повторите через r.headers["Retry-After"] секунд
data = r.json()

print("Серверов:", data["meta"]["total"])
for s in data["data"]:
    print(s["name"], "—", s["players"], "/", s["max_players"])
<?php
$data = json_decode(file_get_contents('https://monwave.ru/api/v1/servers?game=cs2&limit=25'), true);

echo 'Серверов: ' . $data['meta']['total'] . "\n";
foreach ($data['data'] as $s) {
    echo $s['name'] . ' — ' . $s['players'] . '/' . $s['max_players'] . "\n";
}

Виджет сервера для сайта

Онлайн, карта и статус сервера — картинкой или блоком. Вместо 12345 — номер сервера: он есть в ответах /servers и /servers/lookup и на странице сервера в блоке виджета.

<a href="https://monwave.ru" target="_blank"><img src="https://monwave.ru/api/widget/12345" width="320" height="120" alt="MonWave"></a>
<iframe src="https://monwave.ru/api/widget/12345?format=html&theme=light" width="340" height="140" frameborder="0"></iframe>

Лимиты и ошибки

Частота. Не больше 10 запросов в секунду с одного IP, короткий всплеск — до 20. Больше — ответ 429 с заголовком Retry-After.
Кэш. Данные меняются раз в 10–15 минут: кэшируйте ответы у себя хотя бы на минуту и не опрашивайте чаще.
КодЧто значит
200Всё хорошо
400Не хватает параметра — например, game у /servers
404Нет такого метода, игры или сервера
405Публичные методы — только GET
429Слишком часто — подождите столько секунд, сколько в заголовке Retry-After
503Сайт под высокой нагрузкой — повторите позже (Retry-After, обычно 30 секунд)
API для владельцев серверов
Личный ключ сервера выдаётся только его подтверждённому владельцу
  • Голосовал ли игрок за сутки — и «забрать голос», чтобы выдать награду ровно один раз
  • Новые голоса по порядку — для Discord-бота или сайта сервера
  • Данные своего сервера и счётчики голосов
Как подключить