¿Cómo construir un sistema de detección temprana de dominancia de un equipo?

¿Cómo construir un sistema para la detección temprana de la dominancia del equipo?

Contenidos

¿Qué es la dominancia del equipo en un partido y qué métricas considerar para ello?

La dominancia del equipo en un partido no se trata solo del marcador en el tablero. Un equipo puede ir ganando 1:0 pero jugar de manera defensiva, o puede controlar completamente el juego en 0:0, creando más oportunidades y aplicando presión constante. Para el análisis y las apuestas, es importante el juego, no solo la ventaja en el marcador, por lo que la tarea del sistema es traducir el curso del partido en un conjunto de números objetivos.

A nivel de datos, la dominancia se describe mediante un conjunto de métricas disponibles en la API deportiva. En fútbol y hockey, esto generalmente incluye la posesión del balón/puck, número de tiros e intentos, tiros a puerta, momentos peligrosos, córners, entradas en el tercio final del campo, número de pases y acciones clave. En baloncesto y deportes electrónicos, el enfoque se desplaza hacia el número de ataques, tempo de posesión, tiros efectivos, eliminaciones/objetos en el mapa, etc. A través del endpoint /v2/{sportSlug}/partidos del servicio API de eventos deportivos se pueden obtener estadísticas de partidos agregadas en el campo estadísticasDelPartido y, basándose en ello, construir un índice de dominancia numérico.

Un enfoque práctico es recopilar indicadores clave y combinarlos en una única puntuación, por ejemplo Índice de Dominancia. Para el fútbol, se pueden utilizar características como:

  • posesión del balón (clave posesiónDelBalón);
  • total de tiros y tiros a puerta (totalDisparosALaPortería, disparosALaPortería);
  • grandes oportunidades de gol (granOportunidadCreada, granOportunidadMarcada);
  • entradas en el tercio final y toques en el área penal (entradasEnElTercerCuarto, touchesEnCajaOpuesta);
  • porcentaje de duelos ganados (dueloGanadoPorcentaje);
  • pases precisos y pases largos (pasesPrecisos, balonesLargosPreciso);
  • número de córners (tiros de esquina).

Cada métrica puede asignarse un peso considerando su impacto en goles y resultados. Por ejemplo, un tiro a puerta es más importante que un pase simple, y un evento de gol importante pesa más que la posesión. En la definición temprana de dominio, es crítico considerar no solo valores absolutos sino también la diferencia por equipos, así como el minuto actual del partido (campo minutoDelPartidoActual): una ventaja de 5 tiros en los primeros 15 minutos tiene un significado diferente que la misma ventaja en el minuto 80.

A continuación se muestra un ejemplo simplificado de una función que toma un fragmento estadísticasDelPartido de la respuesta de la API y calcula el índice de dominio para los anfitriones:

def compute_dominance(statistics, side="home"):
    # side: "home" или "away"
    s = {"home": 0.0, "away": 0.0}
    def add_score(key, weight, positive=True):
        for period in statistics:  # ALL, 1ST, 2ND
            for group in period.get("groups", []):
                for item in group.get("statisticsItems", []):
                    if item.get("key") == key:
                        h = item.get("homeValue") or 0
                        a = item.get("awayValue") or 0
                        diff = (h - a) if positive else (a - h)
                        s["home"] += diff * weight
                        s["away"] -= diff * weight
    add_score("ballPossession", 0.5)
    add_score("shotsOnGoal", 1.5)
    add_score("bigChanceCreated", 2.0)
    add_score("cornerKicks", 0.7)
    add_score("duelWonPercent", 0.3)
    return s[side]

En productos reales, los pesos y el conjunto de métricas se seleccionan en función de datos históricos y pruebas A/B, pero el principio sigue siendo el mismo: los datos de la API se traducen en un único índice que permite decidir quién está realmente dominando en un momento específico.

¿Qué APIs de estadísticas deportivas utilizar para analizar la dominancia del equipo?

Para que el sistema de detección temprana de dominio funcione de manera confiable, necesita datos estructurados y oportunos. Estos datos son proporcionados por la API REST del servicio api-sport.pro, que cubre fútbol, hockey, baloncesto, tenis, tenis de mesa, deportes electrónicos y otras disciplinas. Para cada uno de ellos, se encuentran disponibles en el bloque horarios, estados de partidos, puntajes, estadísticas detalladas, eventos en vivo y, lo que es importante para las apuestas, cuotas actuales y de inicio de los corredores de apuestas. oddsBase.

Conjunto básico de puntos finales para analizar el dominio del equipo:

  • GET /v2/deporte — lista de deportes soportados con su slug;
  • GET /v2/{sportSlug}/partidos?estado=enprogreso — lista de partidos en vivo actuales por deporte con campos minutoDelPartidoActual, estadísticasDelPartido, eventosEnVivo, oddsBase;
  • GET /v2/{sportSlug}/partidos/{matchId} — datos detallados sobre un partido específico, incluyendo alineaciones de equipos y estadísticas avanzadas;
  • OBTENER /v2/{sportSlug}/matches/{matchId}/events — una lista cronológica completa de eventos del partido, útil para construir series temporales.

A nivel de cuotas, el bloque oddsBase devuelve mercados con valores actuales y de inicio (decimal, decimalInicial) y un indicador de cambio (cambiar). Una caída brusca en las cuotas de la victoria de un equipo a menudo se correlaciona con su ventaja táctica y de juego, por lo que combinar estadísticas y dinámicas de línea proporciona una señal más precisa de dominio.

A continuación se muestra un ejemplo de una solicitud de API para obtener una lista de todos los partidos de fútbol actuales con estadísticas. La autorización utiliza un encabezado Autorización con una clave que se puede obtener en tu cuenta personal en api-sport.ru:

import requests
API_KEY = "ВАШ_API_КЛЮЧ"
BASE_URL = "https://api.api-sport.ru"
headers = {
    "Authorization": API_KEY,
}
params = {
    "status": "inprogress",  # только лайв-матчи
}
response = requests.get(
    f"{BASE_URL}/v2/football/matches",
    headers=headers,
    params=params,
)
response.raise_for_status()
data = response.json()
for match in data.get("matches", []):
    print(
        match["id"],
        match["homeTeam"]["name"],
        "vs",
        match["awayTeam"]["name"],
        "мин.", match.get("currentMatchMinute"),
    )

Esta llamada se puede adaptar para cualquier deporte simplemente reemplazando fútbol con el deseado sportSlug. Luego, el sistema recupera estadísticasDelPartido, calcula el índice de dominio y, en base a eso, toma decisiones: resaltar el partido al operador, enviar una señal al modelo de apuestas o ajustar límites en la línea.

Cómo recopilar y almacenar datos de APIs de eventos deportivos para análisis en línea.

El sistema de detección temprana de dominio es sensible a retrasos y pérdidas de datos. Es importante no solo calcular correctamente el índice en el momento actual, sino también tener un historial del partido con intervalos de varios segundos o minutos. Para esto, se construye una pequeña capa de recolección y almacenamiento sobre la API REST, que convierte las respuestas /v2/{sportSlug}/partidos и /v2/{sportSlug}/matches/{matchId} en estructuras amigables para el análisis.

Un pipeline típico se ve así:

  • El despachador de partidos solicita periódicamente (por ejemplo, cada 5–10 segundos) la lista actual de partidos en vivo para los deportes requeridos.
  • El servicio de estadísticas recupera datos detallados para cada partido, incluyendo estadísticasDelPartido, eventosEnVivo, oddsBase.
  • Almacenamiento guarda «instantáneas» del partido: minuto, puntuación, estadísticas clave, cuotas. Esto puede ser una base de datos relacional, una base de datos especializada en series temporales (TimescaleDB, ClickHouse), o incluso un almacenamiento en memoria para análisis a corto plazo.
  • Servicio de análisis se suscribe a actualizaciones y recalcula el índice de dominio con cada cambio en las estadísticas.

En próximas actualizaciones, se planea que la API soporte WebSocket, lo que permitirá abandonar el sondeo frecuente y cambiar a la transmisión de eventos. Sin embargo, ya es posible construir un marco confiable sobre REST, adhiriéndose a los límites de frecuencia de solicitudes y optimizando la lista de partidos monitoreados.

A continuación se muestra un ejemplo de un colector simplificado en Python que actualiza periódicamente las estadísticas de todos los partidos de fútbol en vivo y almacena información básica en un diccionario local. En producción, se utiliza una base de datos, caché o corredor de mensajes en lugar de un diccionario.

import time
import requests
API_KEY = "ВАШ_API_КЛЮЧ"
BASE_URL = "https://api.api-sport.ru"
headers = {"Authorization": API_KEY}
state = {}  # match_id -> list of snapshots

def fetch_live_matches():
    resp = requests.get(
        f"{BASE_URL}/v2/football/matches",
        headers=headers,
        params={"status": "inprogress"},
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json().get("matches", [])

def fetch_match_details(match_id):
    resp = requests.get(
        f"{BASE_URL}/v2/football/matches/{match_id}",
        headers=headers,
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()

while True:
    for match in fetch_live_matches():
        mid = match["id"]
        details = fetch_match_details(mid)
        snapshot = {
            "minute": details.get("currentMatchMinute"),
            "homeScore": details["homeScore"]["current"],
            "awayScore": details["awayScore"]["current"],
            "stats": details.get("matchStatistics", []),
            "odds": details.get("oddsBase", []),
        }
        state.setdefault(mid, []).append(snapshot)
    time.sleep(10)  # интервал опроса

Tal marco permite agregar rápidamente cualquier capa analítica: desde heurísticas simples hasta modelos de aprendizaje automático. Es importante pensar en el esquema de almacenamiento con anticipación: qué campos se estadísticasDelPartido almacenan siempre, cuáles se agregan y cuáles se mantienen solo como los últimos valores para minimizar el volumen de datos.

Algoritmos y modelos para la detección temprana de la dominancia del equipo basada en datos en vivo.

Después de que los datos de la API se reciben y almacenan de manera consistente, el siguiente paso es elegir un algoritmo que traduzca las métricas «crudas» en una señal comercial clara: qué equipo es dominante y cuán pronto se puede afirmar esto. Se utilizan aquí tanto reglas simples como modelos de aprendizaje automático entrenados en partidos históricos, extraídos a través /v2/{sportSlug}/partidos de temporadas pasadas.

El nivel básico — índices heurísticos. Combinan posesión, tiros, momentos y otras métricas en una puntuación única (ver el ejemplo de la función compute_dominance arriba). Tales índices son fáciles de interpretar y se ajustan rápidamente para torneos o deportes específicos. El umbral de dominio se puede seleccionar en función de datos históricos: por ejemplo, considerar un equipo dominante si su índice supera el umbral y se mantiene durante más de N minutos.

El siguiente paso — modelos estadísticos y de ML. Basado en partidos de la API, se puede ensamblar un conjunto de datos donde las características serán los valores estadísticasDelPartido y dinámicas de cuotas oddsBase en los primeros 10-20 minutos, y la variable objetivo será la puntuación final o el hecho de que el equipo creó más oportunidades de calidad durante el partido. La regresión logística, el aumento de gradiente o una red neuronal simple se entrenan con estos datos para evaluar la probabilidad de que un lado sea actualmente dominante o será dominante en los próximos minutos.

La hoja de ruta del servicio api-sport.ru anuncia la aparición de herramientas de IA listas sobre datos deportivos. Esto hará que sea aún más fácil conectar modelos preentrenados a sus sistemas, combinándolos con los algoritmos internos del corredor de apuestas y modelos de riesgo.

A continuación se muestra un ejemplo de una regla simple en Python que utiliza el índice de dominancia y el minuto actual del partido para generar una señal temprana:

DOM_THRESHOLD = 3.0
MINUTE_FROM = 10
MINUTE_TO = 35

def early_dominance_signal(match_details):
    minute = match_details.get("currentMatchMinute") or 0
    stats = match_details.get("matchStatistics", [])
    if not (MINUTE_FROM <= minute <= MINUTE_TO):
        return None
    home_score = compute_dominance(stats, side="home")
    away_score = compute_dominance(stats, side="away")
    if home_score - away_score >= DOM_THRESHOLD:
        return {"team": "home", "score": home_score - away_score}
    if away_score - home_score >= DOM_THRESHOLD:
        return {"team": "away", "score": away_score - home_score}
    return None

En producción, tales reglas se complementan con filtros por torneos, etapas, estado del partido y contexto de las cuotas. En la práctica, los mejores resultados provienen de enfoques híbridos: el modelo de ML evalúa la probabilidad de dominancia, mientras que se imponen estrictas restricciones comerciales formuladas como reglas simples.

Cómo configurar un sistema de notificación para la dominancia del equipo basado en datos de API.

La puntuación del índice de dominancia tiene poco uso por sí sola si no conduce a una acción. Un trader, gerente de riesgos o estrategia automatizada necesita una destacada oportuna de los partidos donde uno de los equipos claramente toma la iniciativa. Por lo tanto, se construye un sistema de notificación flexible sobre el núcleo analítico, que reacciona a los cambios en los datos recibidos de /v2/{sportSlug}/partidos и /v2/{sportSlug}/matches/{matchId}.

Arquitectónicamente, se ve así:

  • El servicio de cálculo del índice se suscribe a nuevos «trozos» del partido desde el almacenamiento o los recibe directamente de la API.
  • Con cada recalculo, el bloque de toma de decisiones, se activa, que verifica los umbrales de dominancia, la dinámica de las cuotas oddsBase y condiciones adicionales (el minuto del partido, el torneo, el marcador).
  • Si se cumplen las condiciones, se genera un evento de alerta y se envía al canal correspondiente: interfaz de trader, mensajero, webhook a su sistema interno.

Desde un punto de vista práctico, es importante evitar el «ruido»: no notificar sobre cada fluctuación en las estadísticas, sino reaccionar a la dominancia sostenida. Para esto, se utiliza el suavizado temporal (el índice por encima del umbral durante varios minutos consecutivos) y la consideración del contexto — por ejemplo, no enviar notificaciones al final del partido si la línea ya está cerrada.

A continuación se muestra un ejemplo de código que, sobre la función previamente descrita señal_de_dominancia_temprana genera y procesa eventos de alerta. En un sistema real, en lugar de imprimir y un stub enviar_alerta se utilizan colas de mensajes y servicios de entrega externos.

ALERT_MIN_STREAK = 2  # минимум подряд срабатываний
streaks = {}  # match_id -> {"team": str, "count": int}

def process_match_for_alert(match_details):
    match_id = match_details["id"]
    signal = early_dominance_signal(match_details)
    if not signal:
        streaks.pop(match_id, None)
        return
    prev = streaks.get(match_id)
    if prev and prev["team"] == signal["team"]:
        prev["count"] += 1
    else:
        streaks[match_id] = {"team": signal["team"], "count": 1}
    cur = streaks[match_id]
    if cur["count"] >= ALERT_MIN_STREAK:
        send_alert(match_details, cur["team"], signal["score"])
        streaks.pop(match_id, None)

def send_alert(match_details, team, score_gap):
    home = match_details["homeTeam"]["name"]
    away = match_details["awayTeam"]["name"]
    minute = match_details.get("currentMatchMinute")
    print(
        f"ALERT: доминирование {team} в матче {home} vs {away}, "
        f"мин. {minute}, индекс {score_gap:.2f}",
    )

En la práctica, tal bloque se integra fácilmente en los sistemas de riesgo existentes de una empresa de apuestas o en paneles de análisis. Gracias a los datos estructurados de la API, puedes ajustar de manera flexible los umbrales para diferentes ligas, mercados y límites, y con la aparición del soporte de WebSocket en el futuro, también reducir los retrasos entre el evento en el campo y la señal dentro de tus herramientas internas.

Ejemplo de implementación de un sistema de detección temprana de la dominancia del equipo en Python.

A continuación se muestra un ejemplo coherente en Python que demuestra el ciclo completo: obtener partidos en vivo a través de la API, cargar sus estadísticas detalladas, calcular el índice de dominancia y emitir señales tempranas para cada partido. Esta plantilla se puede utilizar como base para tu propio servicio, envolviéndolo en un trabajador en segundo plano, contenedor Docker o microservicio como parte de tu infraestructura.

El ejemplo se basa en los mismos puntos finales descritos anteriormente: /v2/fútbol/partidos и /v2/fútbol/partidos/{matchId}. Para otros deportes, basta con reemplazar fútbol con el deseado sportSlug. No olvides sustituir una clave API real obtenida en tu cuenta personal en api-sport.ru.

import time
import requests
API_KEY = "ВАШ_API_КЛЮЧ"
BASE_URL = "https://api.api-sport.ru"
SPORT = "football"  # football, basketball, ice-hockey, tennis и т.д.
headers = {"Authorization": API_KEY}

def get_live_matches():
    resp = requests.get(
        f"{BASE_URL}/v2/{SPORT}/matches",
        headers=headers,
        params={"status": "inprogress"},
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json().get("matches", [])

def get_match_details(match_id):
    resp = requests.get(
        f"{BASE_URL}/v2/{SPORT}/matches/{match_id}",
        headers=headers,
        timeout=5,
    )
    resp.raise_for_status()
    return resp.json()

def loop():
    while True:
        matches = get_live_matches()
        if not matches:
            print("Нет лайв-матчей, ожидание...")
            time.sleep(15)
            continue
        for short in matches:
            match_id = short["id"]
            details = get_match_details(match_id)
            signal = early_dominance_signal(details)
            if signal:
                team = "home" if signal["team"] == "home" else "away"
                home = details["homeTeam"]["name"]
                away = details["awayTeam"]["name"]
                minute = details.get("currentMatchMinute")
                print(
                    f"РАННИЙ СИГНАЛ: {home} vs {away}, мин. {minute}, "
                    f"доминирует {team}, индекс {signal['score']:.2f}",
                )
        time.sleep(10)

if __name__ == "__main__":
    loop()

En un producto real, este código se complementa con almacenamiento en caché de respuestas, registro, manejo de errores de red, contabilización de cuotas del campo oddsBase, integración con sistemas de almacenamiento y notificación. Pero incluso este script muestra cuán rápido se puede construir un prototipo funcional de un sistema de detección temprana de dominancia, basándose únicamente en los datos proporcionados por el servicio. API de eventos deportivos.

Publicaciones relacionadas:

API para esports: Dota 2, CS2, LoL API de TENNISI.bet API de Goal.com: utilizando datos sobre partidos y transferencias Las mejores API para partidos de fútbol