TeleScout 🛰️

Поиск, скрейпинг и скоринг публичных Telegram-каналов для закупа рекламы — с Telegram API или без него.

Русский · English version →

---

Медиабайеры платят за каталоги вроде TGStat/Telemetr, чтобы находить каналы для рекламы. TeleScout заменяет это self-hosted пайплайном: находит публичные русскоязычные каналы по нишам, скрейпит их публичные метрики, оценивает каждый по шкале 0–100 на пригодность для рекламы и выгружает ранжированную таблицу — через Streamlit-интерфейс, headless-CLI или FastAPI-сервис.

Работает двумя способами: режим Telethon ищет внутри Telegram по API-ключу, а режим Web Discovery находит и квалифицирует каналы вообще без API-ключа — скрейпит публичные каталоги, поисковики и граф упоминаний каналов в постах.

✨ Ключевое

• Объяснимая оценка 0–100 + вовлечённость (ERR) на канал — реальные KPI медиабайинга, с полной раскладкой по компонентам (охват · вовлечённость · частота · свежесть · рекламная нагрузка), а не «магическое число». См. скоринг.
• Два движка поиска — официальный Telegram API (Telethon) и режим без учётных данных, включая волновое расширение по графу упоминаний каналов в постах.
• Мягкая воронка — каналы с нечитаемыми метриками не выбрасываются молча, а попадают в лист Спорные, чтобы ничего ценного не потерять.
• Три интерфейса, один пайплайн — Streamlit UI, CLI telescout и FastAPI-сервис вызывают один сервисный слой и возвращают идентичные ранжированные результаты.
• Аналитика — распределение оценок, scatter «вовлечённость–размер», разрезы по уровням и нишам.
• Полный аудит — каждый запуск пишет параметры, пошаговый лог событий, найденные username, результаты по каналам и авто-сохранённый Excel, плюс SQLite-кэш всех виденных каналов.
• Планка качества — слоистая архитектура, типы везде, 102 теста, ruff + mypy чисто, CI на Python 3.11 и 3.12, Docker, демо одной командой.

📸 Как выглядит

Вкладка «Аналитика» — считается по найденным в запуске каналам:

CLI — telescout demo (офлайн-пример, без сети):

Попробовать без настройки: telescout demo или запустите UI и включите 🧪 Демо-режим (offline). Пример реальной выгрузки Excel/JSON лежит в examples/.

🚀 Быстрый старт

git clone https://github.com/AEX-X/telescout
cd telescout
pip install -e ".[ui,api]"      # добавьте ,telegram для режима Telethon

telescout demo                  # офлайн-пример — без сети и API-ключа
telescout niches                # 70 встроенных пресетов ниш
telescout discover --niche beauty --niche fitness --min-subs 5000 --limit 30 --out beauty.xlsx
telescout analyze @durov @telegram --json out.json
telescout explain @durov        # почему канал получил именно такую оценку

Streamlit UI: streamlit run app.py (или make ui) → http://localhost:8501 API: uvicorn telescout.api:app (или make api) → http://localhost:8000/docs Docker (UI + API): docker compose up --build

Режимы Web Discovery, CLI и API не требуют учётных данных. Только режим Telethon требует Telegram api_id/api_hash (с my.telegram.org) — скопируйте .env.example в .env и заполните.

🧠 Как это работает

flowchart LR
    A["Ключи-семена<br/>telescout/data/presets.yaml"] --> B{Режим}
    B -->|Telethon| C["contacts.search<br/>внутри Telegram"]
    B -->|"Web Discovery<br/>(без API)"| D["Каталоги + поисковики<br/>+ волны по ссылкам в постах"]
    C --> E["Скрейп публичных метрик<br/>со страниц t.me"]
    D --> E
    E --> F["Оценка 0–100<br/>+ вовлечённость"]
    F --> G["Классификация<br/>подошли · спорные · нет"]
    G --> H["Ранжирование и экспорт<br/>XLSX · JSON · SQLite"]

Loading

Самое интересное — Web Discovery. У Telegram нет публичного каталога каналов, поэтому TeleScout строит его сам: стартует от ключей ниши, тянет кандидатов из публичных каталогов и поисковиков, а затем делает волновое расширение — читает публичные страницы постов найденных каналов, собирает все каналы, на которые они ссылаются или которые упоминают, и повторяет несколько волн. Каждый новый username дедуплицируется, фильтруется от мусора (сервисные аккаунты, боты, слишком короткие) и балансируется по источникам, чтобы один шумный источник не доминировал.

📊 Как считается оценка

telescout.scoring превращает сырые метрики в два числа, которыми реально оперирует байер:

• Вовлечённость (ERR) = средние просмотры / подписчики — главная метрика здоровья канала. Здоровые каналы ≈10–40%; очень низкий ERR намекает на мёртвых/ботов, подозрительно высокий — на накрутку просмотров.

• Оценка качества (0–100) = взвешенная смесь пяти компонентов с ренормализацией:

  Компонент	Вес	За что
  Вовлечённость	30%	здоровый ERR (штраф за неправдоподобно высокий)
  Охват	25%	размер аудитории (лог-шкала)
  Активность	20%	ровная частота (≈3–21 пост/нед; штраф за тишину и спам)
  Свежесть	15%	недавние посты
  Чистота	10%	низкая рекламная нагрузка

Каждый компонент возвращается вместе с оценкой, поэтому UI, Excel и API показывают, почему канал так оценён. Неизвестные метрики выпадают, а веса ренормализуются — пробел в скрейпинге снижает уверенность, но не обнуляет оценку несправедливо. Уровни: A / B / C / D.

🏗️ Архитектура

Слоистый пайплайн — UI/CLI/API это тонкие обёртки над одним сервисным слоем. Подробно — в ARCHITECTURE.md.

app.py            Streamlit UI (тонкий)        telescout/pipeline.py   сервисный слой (общий для UI/CLI/API)
telescout/cli.py  Typer CLI                    telescout/scoring.py    вовлечённость + оценка качества
telescout/api.py  FastAPI-сервис               telescout/web_discovery.py  поиск без API + волновое расширение
telescout/charts.py  Plotly-аналитика          telescout/public_web.py     скрейп t.me + парсинг метрик
telescout/http.py    общий HTTP-клиент         telescout/runner.py         движок поиска Telethon
telescout/storage.py SQLite-кэш + история      telescout/classifier.py    мягкая воронка подошли/спорные/нет

⚖️ Ответственное использование

TeleScout читает только публичные данные — публичные страницы t.me и публичную выдачу поисковиков — и предназначен для легального рекламного и маркетингового ресёрча. По умолчанию щадящий режим без агрессивного параллелизма, не ротирует аккаунты, не шлёт сообщения и не вступает в каналы, уважает FloodWait. Для режима Telethon используйте отдельный аккаунт и соблюдайте Условия Telegram и robots-политику источников. Не используйте для спама, скрейпинга приватного контента или харассмента.

🧪 Разработка

pip install -e ".[dev,ui,api,telegram]"
make check        # ruff + mypy + pytest (то же, что в CI)
make test         # pytest с покрытием

102 теста, ruff + mypy чисто, CI на Python 3.11 и 3.12.

🛠️ Стек

Python 3.11+ · Streamlit · FastAPI · Typer · Telethon · BeautifulSoup + requests · pandas + openpyxl · Plotly · SQLite · pytest · ruff · mypy · Docker.

📄 Лицензия

MIT © 2026 AEX-X