Как создать Telegram-бота с xG-аналитикой матча?

Что такое xG в футболе и зачем нужен Telegram-бот с xG-аналитикой

xG (expected goals, ожидаемые голы) — это метрика, которая оценивает вероятность того, что конкретный удар по воротам завершится голом. Для расчета используются десятки факторов: расстояние до ворот, угол удара, тип передачи (прострел, навес, кросс), положение защитников и вратаря, тип удара (головой, ногой), ситуация (пенальти, стандарт, игра с хода) и многое другое. В результате каждая попытка атаки получает значение от 0 до 1, а суммарный xG команды показывает, сколько голов она «должна была» забить исходя из качества моментов.

В отличие от счетчика ударов и владения мячом, xG отвечает на более точный вопрос: кто создавал по-настоящему опасные моменты, а кто просто контролировал мяч без реальной угрозы. Именно поэтому метрика широко используется в профессиональной аналитике, скаутинге, медиа и беттинге. Сравнение фактического счета и xG позволяет увидеть, кому повезло, а кто недобрал свои голы, оценить устойчивость текущих результатов и качество игры команды на дистанции.

Telegram-бот с xG-аналитикой превращает сложную статистику в удобный инструмент, который всегда под рукой у болельщика, аналитика или каппера. Пользователь может в пару кликов узнать, как менялся баланс моментов по ходу матча, кто доминирует по качеству шансов, и в какой момент риск или value в ставках становится максимально интересным. Бот может присылать push-уведомления при резком росте xG, появлении серии опасных атак или несоответствии счета и ожидаемых голов.

Основа такого решения — качественные спортивные данные в режиме live. Через API спортивных событий вы получаете детальную статистику футбольных матчей, включая удары, моменты, владение, дуэли и другие ключевые метрики. На их основе можно построить собственную модель расчета xG и интегрировать ее в Telegram-бота, расширяя функциональность за счет других видов спорта, киберспорта и букмекерских коэффициентов по мере роста проекта.

Выбор API спортивных событий для получения xG-статистики матча

Чтобы Telegram-бот с xG-аналитикой работал стабильно и давал пользователям точные подсказки, нужен надежный источник данных. Критично, чтобы API предоставлял не только счет матча, но и расширенную статистику: удары по воротам и мимо, удары из штрафной и за ее пределами, «большие моменты» (big chances), владение мячом, количество передач и входов в финальную треть. Именно такие показатели содержатся в объекте matchStatistics в Sport Events API и позволяют строить собственные модели ожидаемых голов.

Важный параметр выбора — поддержка live-режима и скорость обновления данных. Для бота, который анализирует xG «на лету», принципиально, чтобы статистика обновлялась по ходу матча, а не только после финального свистка. Эндпоинты /v2/football/matches и /v2/football/matches/{matchId} возвращают не только базовую информацию, но и поля currentMatchMinute, liveEvents и matchStatistics, что позволяет в реальном времени отслеживать ход игры, появление опасных моментов и динамику атакующей активности.

Отдельно стоит обратить внимание на то, как API масштабируется под разные сценарии. Платформа api-sport.ru поддерживает футбол, хоккей, баскетбол, теннис, настольный теннис, киберспорт и другие виды спорта, а также содержит блок данных по букмекерским рынкам (oddsBase). Это значит, что вы можете начать с Telegram-бота по футболу и xG, а затем постепенно расширять функциональность: добавлять аналитику других видов спорта, комбинировать xG с динамикой коэффициентов букмекеров, подключать предстоящие возможности WebSocket и AI-модели без полной переработки архитектуры бота.

Как получить ключи и настроить доступ к API футбольной статистики

Первый шаг к созданию Telegram-бота с xG-аналитикой — получение доступа к Sport Events API. Для этого нужно зарегистрироваться в личном кабинете, создать проект и сгенерировать индивидуальный API-ключ. Ключ используется для авторизации каждого запроса и передается в заголовке Authorization. Такой подход позволяет гибко управлять лимитами, прозрачно отслеживать трафик и при необходимости ограничивать доступ.

После получения ключа вы можете сразу протестировать базовые запросы к футбольному разделу API. Все виды спорта используют единый формат URL с параметром {sportSlug}, поэтому для футбола базовый путь будет таким: https://api.api-sport.ru/v2/football. Чтобы, например, получить список текущих live-матчей с базовой статистикой, достаточно отправить GET-запрос к эндпоинту /matches с параметром status=inprogress и заголовком авторизации.

Пример простого запроса через curl может выглядеть так:

curl -X GET "https://api.api-sport.ru/v2/football/matches?status=inprogress" \
  -H "Authorization: ВАШ_API_КЛЮЧ"

В ответ вы получите JSON-объект с полем totalMatches и массивом matches. Каждый элемент массива содержит идентификатор матча, счет, статус, текущую минуту, а также массив matchStatistics при доступности статистики. Именно эти данные далее будут использоваться для расчета xG внутри вашего сервера или прямо в коде Telegram-бота. Важно корректно обрабатывать коды ошибок (например, 401 при неверном ключе или превышении лимита) и предусмотреть логирование запросов — это упростит отладку и масштабирование проекта.

Как создать и зарегистрировать Telegram-бота для футбольной аналитики

Когда доступ к спортивному API настроен, можно переходить к созданию Telegram-бота. Для регистрации бота в Telegram необходимо обратиться к служебному боту BotFather, выполнить команду создания нового бота, задать имя и уникальное @username. В ответ BotFather выдаст токен формата 123456789:ABCDEF... — его необходимо сохранить и использовать на серверной стороне для работы с Bot API.

Далее выбирается стек технологий для реализации логики. Часто для подобных задач используют Python (библиотеки aiogram, python-telegram-bot) или Node.js (node-telegram-bot-api, telegraf). Язык не принципиален: главное, чтобы выбранный фреймворк позволял удобно обрабатывать команды, callback-кнопки, inline-запросы и работал асинхронно — это особенно полезно при частых обращениях к внешнему API спортивных событий.

Типичный минимальный стек для Python-проекта включает установку клиентской библиотеки Telegram и HTTP-клиента для работы с REST API:

pip install aiogram requests

Рекомендуется хранить токен Telegram-бота и ключ Sport Events API в переменных окружения или в отдельном конфигурационном файле, который не попадает в систему контроля версий. Такой подход повышает безопасность и упрощает перенос бота между тестовой и продакшен-средой. На этом этапе вы можете реализовать простую команду, например /start, чтобы убедиться, что бот отвечает пользователям, и только затем приступить к интеграции xG-аналитики и запросов к API спортивных событий.

Подключение API xG-аналитики к Telegram-боту: пошаговая инструкция

Интеграция xG-аналитики в Telegram-бота строится по понятной цепочке: бот получает команду от пользователя, запрашивает необходимые данные из Sport Events API, рассчитывает xG по выбранной модели и возвращает результат в удобном текстовом или графическом виде. На практике это означает несколько последовательных шагов, которые легко масштабируются по мере роста функциональности.

Сначала бот определяет, какие матчи интересуют пользователя: это может быть определенная лига, команда или просто список всех текущих live-матчей. По запросу, например, /live, бот обращается к эндпоинту /v2/football/matches с фильтром по статусу или турниру. Пользователь выбирает нужный матч, после чего бот запрашивает его детали через /v2/football/matches/{matchId} и получает объект matchStatistics, содержащий группы показателей (Shots, Attack, Passes и др.).

На основе этих статистик можно реализовать упрощенную модель xG. Например, присвоить базовые веса ударам из штрафной и за ее пределами, а также «большим моментам» (big chances). Это не заменяет продвинутую машинную модель, но отлично подходит для первого рабочего прототипа Telegram-бота. Ниже приведен пример функции на Python, которая рассчитывает условный xG, используя поля с ключами totalShotsInsideBox, totalShotsOutsideBox и bigChanceCreated из matchStatistics:

def calculate_simple_xg(match_statistics: list) -> dict:
    """Возвращает примерный xG для хозяев и гостей на основе базовых показателей.
    Ожидается, что на вход передается значение поля matchStatistics из ответа API.
    """
    home_xg = 0.0
    away_xg = 0.0
    # Перебираем периоды и группы статистики
    for period in match_statistics:
        if period.get("period") != "ALL":
            continue
        for group in period.get("groups", []):
            for item in group.get("statisticsItems", []):
                key = item.get("key")
                hv = float(item.get("homeValue", 0) or 0)
                av = float(item.get("awayValue", 0) or 0)
                if key == "totalShotsInsideBox":
                    home_xg += hv * 0.10
                    away_xg += av * 0.10
                elif key == "totalShotsOutsideBox":
                    home_xg += hv * 0.03
                    away_xg += av * 0.03
                elif key == "bigChanceCreated":
                    home_xg += hv * 0.35
                    away_xg += av * 0.35
    return {"home_xg": round(home_xg, 2), "away_xg": round(away_xg, 2)}

После расчета xG бот формирует ответ: показывает счет, текущую минуту, значения xG обеих команд и, при необходимости, текстовый комментарий («хозяева сильно недобирают по голам», «гости доминируют по качеству моментов»). По мере развития проекта вы можете заменить простую формулу на более сложную, обученную на исторических данных, и использовать дополнительные поля из matchStatistics. Актуальный список ключей статистик всегда можно уточнить в документации Sport Events API.

Примеры запросов к API и кода Telegram-бота с xG-аналитикой матча

Рассмотрим, как может выглядеть полный цикл обработки команды пользователя в Telegram-боте: от запроса к API спортивных событий до отправки готового отчета по xG. Для простоты возьмем Python и библиотеку aiogram. Бот будет принимать команду вида /xg <match_id>, запрашивать детали матча по этому идентификатору и возвращать сводку по ожидаемым голам.

import os
import requests
from aiogram import Bot, Dispatcher, executor, types
API_KEY = os.getenv("SPORT_API_KEY")
TELEGRAM_TOKEN = os.getenv("TELEGRAM_TOKEN")
BASE_URL = "https://api.api-sport.ru/v2/football"
bot = Bot(token=TELEGRAM_TOKEN)
dp = Dispatcher(bot)

def get_match(match_id: int) -> dict:
    resp = requests.get(
        f"{BASE_URL}/matches/{match_id}",
        headers={"Authorization": API_KEY},
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()

@dp.message_handler(commands=["xg"])
async def cmd_xg(message: types.Message):
    parts = message.text.split()
    if len(parts) != 2 or not parts[1].isdigit():
        await message.reply("Использование: /xg <match_id>")
        return
    match_id = int(parts[1])
    data = get_match(match_id)
    stats = data.get("matchStatistics", [])
    xg = calculate_simple_xg(stats)
    home = data["homeTeam"]["name"]
    away = data["awayTeam"]["name"]
    minute = data.get("currentMatchMinute")
    text = (
        f"Матч: {home} — {away}"
        f"Минута: {minute}'"
        f"xG хозяев: {xg['home_xg']}"
        f"xG гостей: {xg['away_xg']}"
    )
    await message.reply(text)

Если вы хотите дополнительно учитывать контекст ставок, можно в том же ответе вывести актуальные коэффициенты букмекеров. Для этого достаточно прочитать массив oddsBase из ответа матчевого эндпоинта и найти рынок 1X2. Пример выборки нужного рынка на Python:

def extract_1x2_odds(match: dict) -> dict | None:
    for market in match.get("oddsBase", []):
        if market.get("group") == "1X2":
            choices = {c["name"]: c["decimal"] for c in market.get("choices", [])}
            return {
                "home": choices.get("1"),
                "draw": choices.get("X"),
                "away": choices.get("2"),
            }
    return None

В ответе бота можно сопоставлять xG и текущие коэффициенты: показывать, где рынок недооценивает доминирующую по моментам команду. Такой подход превращает обычный инфо-бот в полноценный аналитический инструмент, который объединяет данные о матче и информацию от букмекерских рынков, доступную через Sport Events API.

Как настроить уведомления в Telegram по xG и другим метрикам матча

Одна из ключевых функций умного спортивного бота — автоматические уведомления без участия пользователя. В контексте xG это могут быть сигналы о резком росте ожидаемых голов у одной из команд, серии опасных атак или серьезном несоответствии счета и качества моментов. Для реализации такой логики бот периодически опрашивает Sport Events API или, по мере появления, подключается к WebSocket-каналу, чтобы получать обновления почти мгновенно.

В варианте с опросом вы настраиваете периодический таск (cron, Celery beat, фоновая задача в asyncio), который раз в N секунд запрашивает актуальные данные по интересующим матчам через /v2/football/matches или /v2/football/matches/{matchId}. После получения matchStatistics вы пересчитываете xG и сравниваете его с предыдущим значением, сохраненным в базе или в памяти приложения. Если рост превышает заданный порог (например, +0.5 xG за короткий промежуток времени) или одна из команд значительно «недобирает» до своих ожидаемых голов, бот отправляет сообщение подписчикам этого матча.

Пример фоновой задачи на Python с использованием asyncio, которая раз в минуту проверяет изменения xG и отправляет уведомления, может выглядеть так:

import asyncio
async def xg_watcher(match_id: int, chat_id: int):
    last_xg = None
    while True:
        match = get_match(match_id)
        stats = match.get("matchStatistics", [])
        xg = calculate_simple_xg(stats)
        current = xg["home_xg"] + xg["away_xg"]
        if last_xg is not None and current - last_xg >= 0.5:
            await bot.send_message(
                chat_id,
                f"Резкий рост xG в матче {match['homeTeam']['name']} — {match['awayTeam']['name']}: {current}",
            )
        last_xg = current
        await asyncio.sleep(60)

По тому же принципу можно настраивать алерты по другим метрикам: скачок количества ударов в створ, резкое изменение владения мячом, рост числа атак в финальной трети или изменение коэффициентов в массивах oddsBase. По мере развития сервиса api-sport.ru вы сможете перенести эту логику с периодического опроса на WebSocket-подключения и дополнять ее AI-моделями, которые будут не только фиксировать события, но и оценивать вероятность гола или камбэка в режиме реального времени.