Перейти к основному содержимому

Методы API Stat

Базовый адрес — https://stat.tapbox.ru/api. Все методы — GET, ключ передаётся в заголовке X-API-Key. Большинство методов канала принимают chat_id — его отдаёт карточка канала.

Каталог и поиск каналов​

Список и подбор каналов​

GET /api/channels

Подбор каналов, чатов и ботов по тематике, региону, размеру аудитории и метрикам.

ПараметрТипОписание
typeстрокаchannel — каналы, chat — чаты, bot — боты. Без параметра — все типы
searchстрокаПоиск по названию, для латинских слов — ещё и по ссылке
morph1Вместе с search: искать ещё и по описанию с учётом словоформ — «Барнаул» найдёт «Барнаула» и «в Барнауле»
categoryстрокаТочное название тематики из списка тематик
regionстрокаТочное название региона из списка регионов
subs_min, subs_maxчислоГраницы числа подписчиков
reach_min, reach_maxчислоГраницы среднего охвата поста за всю историю
err_min, err_maxчислоГраницы ERR, %
ci_min, ci_maxчислоГраницы индекса цитирования
langстрокаЯзык канала, например Русский
verified1Только верифицированные
ownerстрокаpublic — обычные каналы, gos — каналы госорганизаций (слаги id…_gos), biz — бизнес-аккаунты (id…_biz)
exclude_official1Убрать каналы госорганизаций (id…_gos): школы, управляющие компании, администрации
active_daysчислоТолько каналы с публикациями за последние N дней
posts_7d_minчислоМинимум постов за последние 7 дней
reach1Добавить к карточкам охват за период: reach_7d, posts_7d, reach_30d, posts_30d
sortстрокаsubs — подписчики, reach_7d и reach_30d — средний охват поста за последние 7 и 30 полных дней, reach — средний охват за всю историю, err — ERR, ci — индекс цитирования, posts — число постов, recent — недавно добавленные, title — по названию, g_today, g_yest, g_week, g_month — прирост за сегодня, вчера, неделю, месяц. Для ботов: popular, likes
orderстрокаdesc (по умолчанию) или asc
norank1Вместе с search: сортировать по sort, а не по релевантности
limitчисло1–200, по умолчанию 50
pageчислоСтраница, начиная с 1
curl -H "X-API-Key: tbx_ваш_ключ" \
"https://stat.tapbox.ru/api/channels?type=channel&region=Москва&subs_min=10000&sort=err&limit=20"

Ответ: items — массив карточек (поля — как у карточки канала), total — сколько всего подходит под фильтр, page, limit, subs_sum — суммарная аудитория найденного. С reach=1 или сортировкой reach_7d и reach_30d у каждой карточки есть reach_7d, posts_7d, reach_30d и posts_30d.

Топ каналов города по охвату за неделю без госорганизаций — один запрос:

curl -H "X-API-Key: tbx_ваш_ключ" \
"https://stat.tapbox.ru/api/channels?type=channel&region=Алтайский%20край&search=Барнаул&morph=1&norank=1&sort=reach_7d&exclude_official=1&active_days=7&limit=20"

Карточка канала​

GET /api/channels/{handle}

Карточка канала, чата или бота. Вместо {handle} — слаг из ссылки max.ru/…, числовой chat_id или точное название.

curl -H "X-API-Key: tbx_ваш_ключ" "https://stat.tapbox.ru/api/channels/newmedia"
{
"chat_id": -68089202013653,
"handle": "newmedia",
"title": "New Media",
"link": "https://max.ru/newmedia",
"description": "Первый канал о медиа…",
"chat_type": "channel",
"category": "Маркетинг, PR, реклама",
"region": "Россия",
"lang": "Русский",
"participants_count": 11579,
"avg_reach": 4150,
"err_pct": 35.8,
"citation_idx": 237,
"g_today": 0,
"g_yest": -16,
"g_week": -113,
"g_month": -72,
"messages_count": 1696,
"verified": false,
"is_public": true,
"first_post_epoch": 1753356982,
"last_post_epoch": 1789052527
}
ПолеЧто это
participants_countПодписчики
avg_reachСредний охват поста за всю историю канала, без репостов. Охват за последние дни — в /api/channels/reach
err_pctERR — охват поста к числу подписчиков, %
citation_idxИндекс цитирования
g_today, g_yest, g_week, g_monthПрирост подписчиков за сегодня, вчера, 7 и 30 дней
first_post_epoch, last_post_epochПервый и последний пост, секунды Unix

Если канал не найден — 404.

Тематики и регионы​

GET /api/channels/categories и GET /api/channels/regions

Справочники для фильтров category и region: название → количество каналов.

{
"counts": {
"Блоги": 4890,
"Бизнес и стартапы": 3170,
"Новости и СМИ": 6447
}
}

Похожие боты​

GET /api/channels/similar?chat_id=…&limit=15

Боты той же категории. limit — 1–30, по умолчанию 15. Ответ: category и items.

Категории ботов и лайки​

  • GET /api/channels/bot-categories — категории каталога ботов: items с полями name, count, и total.
  • GET /api/channels/likes?chat_id=… — число лайков бота в каталоге: поле count.

Сами боты ищутся через список каналов с type=bot.

Метрики канала​

Все методы этого раздела принимают обязательный параметр chat_id.

МетодЧто возвращает
GET /api/channels/subsПодписчики по дням: items — d (дата), subs
GET /api/channels/errСводка вовлечённости: subs, avg_reach, err, err24 (ERR за первые сутки), err_24h, err_48h, posts, reposts_excluded
GET /api/channels/reachОхват за последние 7 и 30 полных дней по Москве: блоки 7d и 30d — from, to, posts, views_sum, reach_avg, reach_median, top_post (seq, views, when, url, text). Считается по постам с просмотрами, без репостов и удалённых, пересчитывается раз в сутки ночью
GET /api/channels/reach-timelineОхват по дням: items — d, reach (средний охват), err, total (сумма просмотров)
GET /api/channels/posts-summaryСколько публикаций: total, month, week, yesterday и daily — d, c
GET /api/channels/posts-timelineПубликации по дням: items — d, p (посты), r (репосты)
GET /api/channels/posts-heatmapКогда канал публикует: items — d, h (час по Москве), c (количество)
GET /api/channels/posts-hourlyНабор просмотров последних постов по часам: items — seq, url, when, views, hours — h (час жизни поста), cum (просмотров к этому часу). limit — сколько постов
GET /api/channels/historyИстория изменений: title, username, description — массивы value, date
curl -H "X-API-Key: tbx_ваш_ключ" \
"https://stat.tapbox.ru/api/channels/subs?chat_id=-68089202013653"
{
"items": [
{ "d": "2026-09-09", "subs": 11595 },
{ "d": "2026-09-10", "subs": 11579 }
]
}

Публикации​

Лента канала​

GET /api/channels/posts

ПараметрТипОписание
chat_idчислоОбязательный
periodстрока7d и 30d — последние 7 и 30 дней, month — с начала текущего месяца по Москве. Без параметра — вся лента
from, toдатаГраницы периода ГГГГ-ММ-ДД по Москве, to — включительно
dayдатаГГГГ-ММ-ДД — публикации за один день
sortстрокаdate (по умолчанию) или views
limitчисло1–5000, по умолчанию 60
seqстрокаВернуть один пост
summary1Добавить сводку за выбранный период: posts, originals, views_sum, views_avg, views_median
lite1Лёгкий режим: без флага edited, ссылки на источник репоста и общего total, стабильный порядок и постраничный cursor
text_maxчислоОбрезать текст поста до N знаков, у обрезанных — text_cut: true
cursorстрокаСледующая страница в лёгком режиме — значение next_cursor из прошлого ответа
{
"items": [
{
"seq": "116289012815960110",
"url": "https://max.ru/newmedia/…",
"text": "❗️ФАС не будет наказывать…",
"when": "25.03.2026 12:05",
"epoch": 1774429517,
"views": 564889,
"images": [],
"video": false,
"repost_from": "РИА Новости",
"repost_handle": "ria",
"deleted": false,
"edited": false
}
],
"total": 1698
}

В лёгком режиме вместо total приходит next_cursor, если есть следующая страница. С summary=1 в ответе есть объект summary — цифры за период без выкачивания всех постов.

Разбор поста​

  • GET /api/channels/post-views?chat_id=…&seq=… — кривая набора просмотров: views, subscribers, err, posted_at и series — точки ряда.
  • GET /api/channels/post-citations?chat_id=…&seq=… — кто процитировал или репостнул пост: items.

Популярные публикации и рейтинг​

GET /api/posts/top?limit=12 — популярные публикации, как в блоке на главной. limit — 1–50.

GET /api/posts/ranking — рейтинг публикаций, не больше одного поста от канала.

ПараметрОписание
periodtoday (по умолчанию), yesterday, day_before, 7d, week, prev_week, month, prev_month, all
metricviews (по умолчанию) или reposts
category, regionФильтры по тематике и региону канала
limit1–100, по умолчанию 50

Индекс цитирования​

Все методы принимают chat_id.

МетодЧто возвращает
GET /api/channels/citationВходящие (incoming) и исходящие (outgoing) упоминания и репосты: сколько каналов и упоминаний, список до 100 источников
GET /api/channels/citation-breakdownИз чего сложился индекс: total, разбивка по типу упоминания (byType), размеру цитирующих (bySubs), тематике (byCategory) и региону (byRegion)
GET /api/channels/citation-historyИндекс по дням: items — d, ci
GET /api/channels/repost-sourcesЧьи посты канал репостит (sources) и кто репостит его (amplifiers)

Сводка по рынку​

МетодЧто возвращает
GET /api/channels/statsОбъём базы: channels, chats, bots, posts, posts_today, subs, views_total, categories
GET /api/channels/top-channels?metric=reachЛидеры по охвату (metric=reach) или по ERR (metric=err): items — handle, title, value
GET /api/channels/growth-leadersЛидеры прироста подписчиков: items — handle, title, category, participants_count, gain
GET /api/channels/category-growthПрирост по тематикам: items — name, chans (каналов), base, delta, pct
GET /api/channels/best-timeВовлечённость по дням недели и часам по всей базе: items — dow, hr, er, n
GET /api/channels/content-typesДоли типов контента: items — n (тип), v (количество)