¿Cómo crear una visualización de datos deportivos (mapa de calor, mapa de pases)?

¿Qué es un mapa de calor y un mapa de pases en el análisis deportivo?

Un mapa de calor en el análisis deportivo es un mapa de calor que muestra la concentración de acciones en la cancha o el campo. La escala de colores refleja la densidad de eventos: cuanto más caliente es el área, más a menudo ocurrieron tiros, entradas, pases o toques de balón allí. En un campo de fútbol, esto ayuda a ver literalmente el estilo del equipo: alta presión, juego por las bandas, carga del área penal o control en el centro.

Un mapa de pases es un mapa de pases que muestra la dirección y frecuencia de los pases entre jugadores. Típicamente, el diagrama muestra las posiciones de los futbolistas, líneas entre ellos y el grosor de las líneas relacionado con el número de pases. Tal visualización permite evaluar a través de quién se construye el ataque, cómo funciona el primer pase, cuán activamente se utilizan los laterales y si hay un sesgo hacia una de las zonas.

Ambas visualizaciones son críticas para el scouting, análisis táctico, preparación de partidos y apuestas. Ayudan a tomar decisiones basadas en datos reales en lugar de impresiones subjetivas. Para construir sistemáticamente mapas de calor y mapas de pases sin entrada manual, es necesaria una fuente confiable de estadísticas de eventos: una API de datos deportivos. Este es el tipo de acceso programático a partidos, equipos, jugadores y estadísticas que proporciona la plataforma. API de datos deportivos api-sport.ru, apoyando el fútbol, baloncesto, hockey, tenis, tenis de mesa, esports y otros deportes.

¿Qué APIs de datos deportivos usar para la visualización del fútbol?

Para construir mapas de calor visuales y mapas de pases para el fútbol, tres grupos de datos son importantes: información del partido, estadísticas detalladas y eventos durante el juego. Dentro de la API de Eventos Deportivos en el dominio api.api-sport.ru, esto se implementa a través de la familia de endpoints v2. Te permiten obtener una lista de partidos, información detallada sobre un partido específico, alineaciones de equipos, estadísticas avanzadas e incluso cuotas de casas de apuestas a través del bloque oddsBase.

Las solicitudes básicas se realizan a endpoints del tipo v2 football matches y v2 football matches {matchId}. En la respuesta, recibes un objeto Match con campos torneo, equipos, puntuación, lugar y, lo más importante, un array matchStatistics con desgloses por períodos y grupos de métricas. Contiene métricas clave para la visualización: posesión del balón, tiros totales, tiros a puerta, toques en el área penal, pases en el tercio final, pases precisos y mucho más. Estos datos pueden ser agregados por áreas del campo y utilizados como base para mapas de calor y mapas de pases.

Un endpoint separado v2 football matches {matchId} events devuelve la cronología de liveEvents: goles, tarjetas, sustituciones y otros eventos importantes. A partir de ellos, se forman líneas de tiempo y gráficos combinados. En proyectos avanzados, el flujo de eventos se puede obtener cómodamente en tiempo real a través de WebSocket. El soporte de WebSocket ya está en los planes de desarrollo del servicio. api-sport.ru, que abrirá el camino para mapas de calor en línea y mapas de pases en vivo justo durante el partido. Además, la API de casas de apuestas con cuotas permite superponer la dinámica del mercado sobre la visualización.

¿Cómo obtener datos de partidos a través de API para construir mapas de calor de jugadores?

El primer paso para cualquier mapa de calor es obtener datos precisos del partido. En la API de Eventos Deportivos, esto se hace utilizando el endpoint v2 football matches {matchId}. En la respuesta, recibes un único objeto Match, que ya contiene equipos, alineaciones con la posición de cada jugador en el objeto de alineación, la puntuación actual, el estado del partido y un array matchStatistics con estadísticas detalladas por períodos ALL, 1ST, 2ND.

Para enviar solicitudes a la API, se requiere una clave de autorización. Puede generarse en la sección segura de la plataforma en tu cuenta personal en api-sport.ru. Después de eso, basta con pasar la clave en el encabezado Authorization. A continuación se muestra un ejemplo de obtención de información detallada sobre un partido de fútbol por ID en un navegador o Node.js utilizando fetch.

const API_KEY = 'ВАШ_API_КЛЮЧ';
const matchId = 14570728;
fetch('https://api.api-sport.ru/v2/football/matches/' + matchId, {
  headers: {
    Authorization: API_KEY
  }
})
  .then(r => r.json())
  .then(match => {
    // Общая информация о матче
    console.log(match.homeTeam.name, 'vs', match.awayTeam.name);
    // Пример доступа к статистике по всем периодам
    const allPeriod = match.matchStatistics.find(s => s.period === 'ALL');
    const shotsGroup = allPeriod.groups.find(g => g.groupName === 'Shots');
    console.log('Всего ударов хозяев:', shotsGroup.statisticsItems.find(i => i.key === 'totalShotsOnGoal').homeValue);
  });

En la siguiente etapa, los datos de matchStatistics pueden transformarse en una matriz de actividad por zonas. Para un mapa de calor simple, se utilizan métricas agregadas. Por ejemplo, toques en el área penal touchesInOppBox, pases en el tercio final finalThirdEntries y tiros desde diferentes zonas. Si tu plan incluye además un flujo de eventos con coordenadas de acción, ya puedes construir mapas de calor completos por x e y, dividiendo el campo en una cuadrícula y contando el número de eventos en cada celda.

¿Cómo crear un mapa de calor de tiros y acciones de jugadores utilizando datos de API?

Al crear un mapa de calor de tiros, es importante extraer correctamente las métricas relacionadas con acciones ofensivas de la API. En el objeto matchStatistics, hay grupos Shots y Attack, que contienen métricas totalShotsOnGoal, shotsOnGoal, totalShotsInsideBox, totalShotsOutsideBox, touchesInOppBox, bigChanceCreated y otros. Estos valores ya proporcionan una idea de las zonas y la frecuencia con la que el equipo o un jugador específico crea una amenaza.

Para convertir estadísticas en un mapa de calor, el campo se divide generalmente en una cuadrícula, con cada celda correspondiente a un sector. Si tienes las coordenadas de los disparos y acciones, simplemente cuentas el número de eventos por celda. Al trabajar solo con datos agregados de matchStatistics, puedes modelar la intensidad a través de bandas verticales y horizontales, por ejemplo, evaluando por separado el flanco izquierdo, el flanco derecho y la zona central, así como dividiendo el campo en tercios.

A continuación se muestra un ejemplo en Python que recupera datos del partido a través de la API, extrae métricas clave sobre disparos y prepara la base para visualizar un mapa de calor como una matriz bidimensional. Para un proyecto real, puedes reemplazar la matriz condicional con el resultado del procesamiento de coordenadas.

import requests
API_KEY = 'ВАШ_API_КЛЮЧ'
MATCH_ID = 14570728
url = f'https://api.api-sport.ru/v2/football/matches/{MATCH_ID}'
resp = requests.get(url, headers={'Authorization': API_KEY})
match = resp.json()
all_period = next(s for s in match['matchStatistics'] if s['period'] == 'ALL')
shots_group = next(g for g in all_period['groups'] if g['groupName'] == 'Shots')
shots_total = next(i for i in shots_group['statisticsItems'] if i['key'] == 'totalShotsOnGoal')
inside_box = next(i for i in shots_group['statisticsItems'] if i['key'] == 'totalShotsInsideBox')
outside_box = next(i for i in shots_group['statisticsItems'] if i['key'] == 'totalShotsOutsideBox')
print('Удары всего:', shots_total['homeValue'], shots_total['awayValue'])
print('Из штрафной:', inside_box['homeValue'], inside_box['awayValue'])
print('Из-за пределов:', outside_box['homeValue'], outside_box['awayValue'])
# Заготовка под тепловую матрицу 3х3 по зонам поля
heatmap_matrix = [
    [0, 0, 0],
    [0, 0, 0],
    [0, 0, 0]
]

La matriz resultante se puede dibujar convenientemente utilizando bibliotecas de visualización, coloreando las celdas según la intensidad. Si además conectas tus propios datos de seguimiento o coordenadas de disparo a la API de Sport Events, se pueden combinar en un solo pipeline para construir un mapa de calor detallado de las acciones de cada jugador hasta un punto específico en el campo.

¿Cómo construir un mapa de pases de los pases del equipo basado en la API de eventos?

El mapa de pases ayuda a ver la estructura del juego de balón a través de las conexiones entre jugadores. Condicionalmente, cada jugador es un nodo del gráfico, y los pases entre ellos son aristas, cuyo grosor y color dependen de la frecuencia y precisión de los pases. Para calcular tales conexiones, se necesitan dos capas de datos: la composición del equipo con identificadores de jugadores y eventos que reflejan los pases entre ellos. La primera capa proporciona el endpoint v2 football matches {matchId} a través de los objetos homeTeam, awayTeam y lineup. La segunda capa se forma en base al feed de eventos y estadísticas de matchStatistics.

El endpoint v2 football matches {matchId} events devuelve un array de eventos con LiveEvent durante el partido. Es especialmente útil en combinación con métricas agregadas del grupo de Pases, que incluye accuratePasses, passes, finalThirdEntries, accurateLongBalls, accurateCross. Estos datos te permiten evaluar el volumen y la calidad general de los pases para el equipo, y luego distribuirlos a través de las conexiones de los jugadores si tu plan incluye un flujo de eventos extendido que especifique el pasador y el receptor del pase.

A continuación se muestra un ejemplo en JavaScript que recupera la lista de eventos del partido y prepara la estructura para un gráfico de pases simple. El array de pases asume eventos donde passerId y receiverId ya han sido destacados. Tal estructura se puede obtener ya sea de un plan tarifario avanzado o de tu propio preprocesamiento de datos en bruto.

const API_KEY = 'ВАШ_API_КЛЮЧ';
const matchId = 14570728;
async function loadEvents() {
  const res = await fetch('https://api.api-sport.ru/v2/football/matches/' + matchId + '/events', {
    headers: { Authorization: API_KEY }
  });
  const data = await res.json();
  return data.events;
}
function buildPassingGraph(passes) {
  const links = {};
  passes.forEach(p => {
    const key = p.passerId + '-' + p.receiverId;
    if (!links[key]) {
      links[key] = { from: p.passerId, to: p.receiverId, count: 0 };
    }
    links[key].count += 1;
  });
  return Object.values(links);
}

El array resultante de conexiones se puede pasar a cualquier biblioteca de visualización de gráficos y dibujar como un mapa de pases sobre el esquema del campo. En el futuro, la plataforma api-sport.ru planea desarrollar herramientas en tiempo real basadas en WebSocket y módulos de IA. Esto abrirá la posibilidad de construir mapas de pases con actualizaciones en línea y conocimientos automáticos, como identificar conexiones clave y patrones de juego no convencionales.

Herramientas y bibliotecas para visualizar datos deportivos de APIs (Python, JavaScript)

Después de haber configurado la recuperación de datos a través de la API de Sport Events, el siguiente paso es elegir un stack de visualización. En el ecosistema de Python, las combinaciones populares son pandas más matplotlib o seaborn para gráficos estáticos y plotly para paneles interactivos. Para campos de fútbol, a menudo se utiliza la biblioteca especializada mplsoccer, que simplifica el dibujo de marcas, mapas de calor y mapas de pases en un campo de fútbol estándar.

En el navegador, la herramienta principal para gráficos interactivos complejos sigue siendo D3.js. Para implementaciones más rápidas, Chart.js, ECharts o Highcharts son adecuados, que manejan bien las matrices de calor y los gráficos de cuadrícula. Las aplicaciones cliente se pueden conectar cómodamente a la API a través de fetch o axios, y en tiempo real, los datos se pueden actualizar a través de WebSocket, que se planea agregar a la infraestructura de api-sport.ru. Esto permitirá construir paneles en vivo con un mapa de calor en línea y actualizar mapas de pases sin recargar la página.

A continuación se muestra un ejemplo de código mínimo en Python que recupera datos de partidos de una API y construye un mapa de calor simple basado en un conjunto condicional de coordenadas de disparo utilizando matplotlib. En la práctica, en lugar de la lista de disparos, utilizarás coordenadas reales obtenidas de tu propio seguimiento o de un feed de eventos mejorado.

import requests
import numpy as np
import matplotlib.pyplot as plt
API_KEY = 'ВАШ_API_КЛЮЧ'
MATCH_ID = 14570728
# Получаем матч (например, чтобы отобразить счет и команды в заголовке)
url = f'https://api.api-sport.ru/v2/football/matches/{MATCH_ID}'
match = requests.get(url, headers={'Authorization': API_KEY}).json()
# Условные координаты ударов в нормированной системе 0..1
shots = np.array([
    [0.8, 0.4],
    [0.9, 0.5],
    [0.7, 0.3],
    [0.85, 0.6]
])
heatmap, xedges, yedges = np.histogram2d(shots[:, 0], shots[:, 1], bins=20, range=[[0, 1], [0, 1]])
plt.imshow(heatmap.T, origin='lower', cmap='hot', interpolation='nearest')
plt.title('Heatmap ударов')
plt.xlabel('Длина поля')
plt.ylabel('Ширина поля')
plt.colorbar(label='Интенсивность')
plt.show()

Al combinar tales enfoques con datos de cuotas del bloque oddsBase y futuros módulos de IA en el lado del servicio, se pueden construir paneles analíticos avanzados. Integrarán la imagen táctica en el campo, la dinámica del mercado de apuestas y sugerencias automáticas de modelos, haciendo que la combinación de la API de eventos deportivos y la pila de visualización moderna sea una herramienta poderosa para analistas, medios y proyectos de apuestas.