API каталога MAX

Каталог gosmax.ru отдаёт данные экосистемы мессенджера MAX через открытые JSON-эндпоинты: поиск по каталогу, срезы категорий, тренды роста и полный датасет-экспорт (99 838 индексируемых записей). Без ключей и регистрации; данные first-party (собраны напрямую со страниц max.ru); использование — со ссылкой на источник (CC BY 4.0, детали на странице датасета).

GET /api/bots/search

Поиск по названию, описанию и тегам. Без q возвращает топ-лист по подписчикам.

Параметр	Значение
`q`	поисковая строка, ≤100 символов; строка длиной ≥2, содержащая хотя бы одну букву/цифру, включает поиск (FTS5/LIKE), иначе — топ-лист
`category`	слаг категории, ≤64 символов
`type`	bot \| channel \| chat \| sticker
`sort`	relevance (дефолт при q) \| subscribers \| name \| added \| growth_7d
`verified`	1 — только подтверждённые в MAX
`curated`	1 — только индексируемые записи (прошедшие quality-gate)
`limit`	дефолт 30, максимум 60
`page`	поиск отдаёт только ВЕРХ выдачи (несколько сотен строк после дедупа) — глубокие страницы вернут пусто; для перечисления каталога используйте /search.json

Ответ: { q, page, limit, hasMore, count, results[] }; каждая запись — slug, name, desc, tags[], cat (название категории, может быть пустым), catIcon, catSlug, type, subs (число или null), v (проверен в MAX: 0/1), ni (не прошёл quality-gate: 0/1). Результаты дедуплицированы по каналу (один канал под несколькими слагами-агрегаторами схлопывается). Кэш: 2 минуты.

GET /api/categories/{slug}

Записи одной категории (те же поля ответа, что у поиска).

Параметр	Значение
`{slug}`	слаг категории в пути; неизвестный → 404, пустой → 400
`type`	bot \| channel \| chat \| sticker
`sort`	added \| name \| subscribers (дефолт) \| growth_7d \| growth_30d
`verified`	1 — только подтверждённые
`curated`	дефолт 1 (индексируемые); curated=0 расширяет выборку
`limit`	дефолт 50, максимум 100
`page`	0–200

Ответ: { category, name, icon, page, limit, hasMore, count, results[] }. Кэш: 5 минут.

GET /api/trends

Лидеры роста подписчиков за период (ранжирование по темпу, момент-семантика).

Параметр	Значение
`period`	1d \| 7d (дефолт) \| 30d; невалидное значение → 7d
`type`	bot \| channel \| chat \| sticker
`curated`	1 — только индексируемые
`minSubs`	минимум подписчиков сейчас (0–100 млн)
`limit`	дефолт 50, максимум 100

Ответ: { period, count, results[] }; запись — slug, name, entity_type, cat, catSlug, verified, subscribers, growth, growth_pct, growth_7d, growth_30d. Семантика роста: growth — абсолютная дельта подписчиков за период; growth_pct, growth_7d, growth_30d — проценты. Фильтры честности зашиты: baseline ≥50 подписчиков, отсечение аномалий (>1000% за период — скачки данных агрегаторов, не рост), дедуп слагов. Кэш: 10 минут.

GET /search.json — датасет-экспорт

Полный индексируемый срез каталога как JSON-массив, постранично (5 000 записей, до 10 000 через ?limit=; навигация — заголовки X-Total-Count и Link rel=first/next). Поля, лицензия CC BY 4.0 и готовые строки цитирования — на странице датасета.

Виджеты

/embed/{slug}/ — встраиваемый iframe-виджет статистики канала (сниппет — на странице канала, кнопка «Встроить статистику на сайт»);
/badge/{slug}.svg — компактный SVG-бейдж (имя, подписчики, знак проверки);
/og/{slug}.svg — OG-изображение страницы канала (1200×630).

Ограничения — честно

CORS не настроен: браузерный fetch с чужого домена упрётся в same-origin. Забирайте данные server-to-server.
Версионирования и SLA нет: API отражает текущий каталог; формат может уточняться (эта страница — источник истины).
Rate-limit не заявлен: ответы кэшируются (см. кэш у каждого эндпоинта) — уважайте кэш и не обходите его случайными параметрами.
Тренды за 30 дней наполняются по мере накопления ряда — пустой ответ на period=30d для части каналов легитимен.
Глубокая пагинация: /api/bots/search — только верх выдачи (поисковый эндпоинт, не перечисление; полный обход — через /search.json); /api/categories — настоящий постраничный доступ, page ≤ 200.

Для AI-агентов есть машиночитаемая сводка каталога: /llms.txt. Происхождение и проверка данных — методология. Вопросы — leadmanager81@yandex.ru.

Связанные страницы: Датасет и цитирование · Статистика · Методология · Каталог.