¿Cómo crear un bot de Telegram con análisis xG de partidos?

¿Qué es xG en el fútbol y por qué necesitas un bot de Telegram con análisis de xG?

xG (goles esperados) es una métrica que evalúa la probabilidad de que un tiro específico a puerta resulte en un gol. Utiliza docenas de factores para el cálculo: distancia a la portería, ángulo del tiro, tipo de pase (centro, globito, pase filtrado), posición de los defensores y el portero, tipo de tiro (cabeza, pie), situación (penalti, jugada a balón parado, juego abierto) y mucho más. Como resultado, cada intento de ataque recibe un valor de 0 a 1, y el xG total del equipo muestra cuántos goles «deberían haber» anotado según la calidad de las oportunidades.

A diferencia del contador de tiros y la posesión del balón, el xG responde a una pregunta más precisa: quién creó momentos verdaderamente peligrosos y quién simplemente controló el balón sin una amenaza real. Por eso, la métrica se utiliza ampliamente en análisis profesionales, scouting, medios y apuestas. Comparar el marcador real y el xG permite ver quién tuvo suerte y quién falló sus goles, evaluar la sostenibilidad de los resultados actuales y la calidad del juego del equipo a lo largo del tiempo.

Un bot de Telegram con análisis de xG convierte estadísticas complejas en una herramienta conveniente que siempre está a mano para aficionados, analistas o apostadores. El usuario puede averiguar en un par de clics cómo cambió el balance de oportunidades durante el partido, quién domina en términos de calidad de oportunidades y en qué momento el riesgo o valor en las apuestas se vuelve más interesante. El bot puede enviar notificaciones push cuando hay un aumento brusco en el xG, aparece una serie de ataques peligrosos o hay una discrepancia entre el marcador y los goles esperados.

La base de tal solución es datos deportivos de alta calidad en modo en vivo. A través de API de eventos deportivos obtienes estadísticas detalladas de partidos de fútbol, incluyendo tiros, momentos, posesión, duelos y otras métricas clave. Basado en ellos, puedes construir tu propio modelo de cálculo de xG e integrarlo en un bot de Telegram, ampliando la funcionalidad con otros deportes, esports y cuotas de apuestas a medida que el proyecto crece.

Elegir una API de eventos deportivos para obtener estadísticas de xG de partidos.

Para que el bot de Telegram con análisis de xG funcione de manera confiable y proporcione a los usuarios pistas precisas, se necesita una fuente de datos confiable. Es crítico que la API proporcione no solo el marcador del partido, sino también estadísticas extendidas: tiros a puerta y fuera de puerta, tiros desde dentro y fuera del área penal, «grandes oportunidades», posesión, número de pases y entradas en el tercio final. Tales indicadores se encuentran en el objeto estadísticasDelPartido en la API de Eventos Deportivos y permiten construir tus propios modelos de goles esperados.

Un parámetro de selección importante es el soporte para modo en vivo y la velocidad de actualización de datos. Para un bot que analiza xG «sobre la marcha», es esencial que las estadísticas se actualicen durante el partido, no solo después del pitido final. Los endpoints /v2/fútbol/partidos и /v2/fútbol/partidos/{matchId} devuelven no solo información básica, sino también campos minutoDelPartidoActual, eventosEnVivo и estadísticasDelPartido, que permiten rastrear el curso del juego en tiempo real, la aparición de momentos peligrosos y la dinámica de la actividad ofensiva.

También vale la pena señalar cómo la API se escala bajo diferentes escenarios. La plataforma api-sport.pro soporta fútbol, hockey, baloncesto, tenis, tenis de mesa, esports y otros deportes, y también contiene un bloque de datos sobre mercados de apuestas (oddsBase). Esto significa que puedes comenzar con un bot de Telegram para fútbol y xG, y luego expandir gradualmente la funcionalidad: añadiendo análisis para otros deportes, combinando xG con la dinámica de las cuotas de las casas de apuestas, conectando capacidades futuras de WebSocket y modelos de IA sin una revisión completa de la arquitectura del bot.

Cómo obtener claves y configurar el acceso a la API de estadísticas de fútbol.

El primer paso para crear un bot de Telegram con análisis xG es obtener acceso a la API de Eventos Deportivos. Para hacer esto, necesitas registrarte en la cuenta personal., crear un proyecto y generar una clave API única. La clave se utiliza para autorizar cada solicitud y se pasa en el encabezado Autorización. Este enfoque permite una gestión flexible de límites, seguimiento transparente del tráfico y restringir el acceso si es necesario.

Después de obtener la clave, puedes probar inmediatamente solicitudes básicas a la sección de fútbol de la API. Todos los deportes utilizan un formato de URL unificado con el parámetro {sportSlug}, así que para fútbol, la ruta base será la siguiente: https://api.api-sport.ru/v2/football. Para, por ejemplo, obtener una lista de partidos en vivo actuales con estadísticas básicas, es suficiente enviar una solicitud GET al endpoint /matches con el parámetro estado=enprogreso y el encabezado de autorización.

Un ejemplo de una solicitud simple a través de curl podría verse así:

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

En respuesta, recibirás un objeto JSON con el campo totalMatches y un array partidos. Cada elemento del array contiene el ID del partido, el marcador, el estado, el minuto actual, así como un array estadísticasDelPartido si las estadísticas están disponibles. Estos datos se utilizarán para calcular xG dentro de tu servidor o directamente en el código del bot de Telegram. Es importante manejar correctamente los códigos de error (por ejemplo, 401 por una clave incorrecta o por exceder el límite) y proporcionar un registro de solicitudes; esto simplificará la depuración y escalado del proyecto.

Cómo crear y registrar un bot de Telegram para análisis de fútbol.

Una vez que se configure el acceso a la API deportiva, puedes proceder a crear el bot de Telegram. Para registrar un bot en Telegram, necesitas contactar al bot del servicio BotFather, ejecutar el comando para crear un nuevo bot, establecer un nombre y un @username único. En respuesta, BotFather emitirá un token en el formato 123456789:ABCDEF... — debe ser guardado y utilizado en el lado del servidor para trabajar con la API del Bot.

A continuación, se elige un stack tecnológico para implementar la lógica. A menudo, se utiliza Python para tales tareas (bibliotecas aiogram, python-telegram-bot) o Node.js (node-telegram-bot-api, telegraf). El lenguaje no es crítico: lo principal es que el marco elegido permita un manejo conveniente de comandos, botones de callback, solicitudes en línea y funcione de manera asíncrona; esto es especialmente útil al acceder frecuentemente a la API externa de eventos deportivos.

Un stack mínimo típico para un proyecto en Python incluye la instalación de la biblioteca cliente de Telegram y un cliente HTTP para trabajar con la API REST:

pip install aiogram requests

Se recomienda almacenar el token del bot de Telegram y la clave de la API de Eventos Deportivos en variables de entorno o en un archivo de configuración separado que no entre en el control de versiones. Este enfoque mejora la seguridad y simplifica la transferencia del bot entre los entornos de prueba y producción. En esta etapa, puedes implementar un comando simple, por ejemplo /start, para asegurar que el bot responda a los usuarios, y solo entonces proceder a integrar análisis xG y solicitudes a la API de eventos deportivos.

Conectando la API de análisis de xG al bot de Telegram: instrucciones paso a paso.

La integración de análisis xG en el bot de Telegram se basa en una cadena clara: el bot recibe un comando del usuario, solicita los datos necesarios de la API de Eventos Deportivos, calcula xG basado en el modelo elegido y devuelve el resultado en un formato de texto o gráfico conveniente. En la práctica, esto significa varios pasos secuenciales que son fácilmente escalables a medida que crece la funcionalidad.

Primero, el bot determina qué partidos interesan al usuario: puede ser una liga específica, un equipo o simplemente una lista de todos los partidos en vivo actuales. Por ejemplo, al solicitar, /live, el bot consulta el endpoint /v2/fútbol/partidos con un filtro por estado o torneo. El usuario selecciona el partido deseado, después de lo cual el bot solicita sus detalles a través de /v2/fútbol/partidos/{matchId} y recibe un objeto estadísticasDelPartido, que contiene grupos de métricas (Tiros, Ataque, Pases, etc.).

Basado en estas estadísticas, se puede implementar un modelo xG simplificado. Por ejemplo, asignar pesos base a los tiros desde dentro y fuera del área penal, así como a las «grandes oportunidades». Esto no reemplaza un modelo de máquina avanzado, pero es excelente para el primer prototipo funcional de un bot de Telegram. A continuación se muestra un ejemplo de una función en Python que calcula xG condicional utilizando campos con claves totalDisparosDentroDelÁrea, totalTirosFueraDelÁrea и granOportunidadCreada de estadísticasDelPartido:

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)}

Después de calcular xG, el bot forma una respuesta: muestra el marcador, el minuto actual, los valores de xG de ambos equipos y, si es necesario, un comentario textual («los locales están significativamente por debajo de lo esperado en goles», «los visitantes dominan en la calidad de las oportunidades»). A medida que el proyecto avanza, puedes reemplazar la fórmula simple por una más compleja entrenada con datos históricos y usar campos adicionales de estadísticasDelPartido. La lista actual de estadísticas clave siempre se puede aclarar en la documentación API de Eventos Deportivos.

Ejemplos de solicitudes de API y código de bot de Telegram con análisis de xG de partidos.

Consideremos cómo podría verse un ciclo completo de procesamiento de un comando de usuario en un bot de Telegram: desde la consulta a la API de eventos deportivos hasta el envío de un informe xG listo. Para simplificar, tomemos Python y la biblioteca aiogram. El bot aceptará comandos de la forma /xg, solicitará detalles del partido mediante este identificador y devolverá un resumen de los goles esperados.

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)

Si deseas considerar adicionalmente el contexto de las apuestas, también puedes mostrar las cuotas actuales de los corredores de apuestas en la misma respuesta. Para hacer esto, es suficiente con leer el array oddsBase de la respuesta del endpoint del partido y encontrar el mercado 1X2. Un ejemplo de muestreo del mercado requerido en 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

En la respuesta del bot, puedes comparar xG y las cuotas actuales: mostrando dónde el mercado subestima al equipo que domina en términos de oportunidades. Este enfoque convierte a un bot de información regular en una herramienta analítica completa que combina datos del partido e información de los mercados de apuestas disponibles a través de la API de Eventos Deportivos.

Cómo configurar notificaciones en Telegram para xG y otras métricas de partidos.

Una de las características clave de un bot deportivo inteligente son las notificaciones automáticas sin la intervención del usuario. En el contexto de xG, estas pueden ser señales de un aumento brusco en los goles esperados para uno de los equipos, una serie de ataques peligrosos o una discrepancia seria entre el marcador y la calidad de las oportunidades. Para implementar tal lógica, el bot consulta periódicamente la API de Eventos Deportivos o, a medida que se vuelven disponibles, se conecta a un canal WebSocket para recibir actualizaciones casi al instante.

En la opción de sondeo, configuras una tarea periódica (cron, Celery beat, tarea en segundo plano en asyncio), que solicita datos actuales sobre los partidos de interés cada N segundos a través de /v2/fútbol/partidos or /v2/fútbol/partidos/{matchId}. Después de recibir estadísticasDelPartido recalculas xG y lo comparas con el valor anterior almacenado en la base de datos o en la memoria de la aplicación. Si el aumento supera un umbral especificado (por ejemplo, +0.5 xG en un corto período de tiempo) o uno de los equipos «se queda corto» en sus goles esperados, el bot envía un mensaje a los suscriptores de este partido.

Un ejemplo de una tarea en segundo plano en Python usando asyncio, que verifica cambios en xG cada minuto y envía notificaciones podría verse así:

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)

Las alertas para otras métricas se pueden configurar de la misma manera: un aumento en el número de tiros a puerta, un cambio brusco en la posesión del balón, un aumento en el número de ataques en el tercio final, o cambios en los coeficientes en los arrays. oddsBase. A medida que el servicio se desarrolla api-sport.pro podrás transferir esta lógica de sondeo periódico a conexiones WebSocket y mejorarla con modelos de IA que no solo registren eventos, sino que también evalúen la probabilidad de un gol o un regreso en tiempo real.