¿Cómo incrustar el widget de análisis xG en el sitio web?

¿Qué son las analíticas xG en el fútbol y por qué incrustar el widget xG en el sitio web?

xG (goles esperados) es una métrica que muestra cuántos momentos peligrosos creó un equipo y cuántos goles debería marcar en función de la calidad de los disparos, en lugar del marcador real. debería haber El cálculo tiene en cuenta el tipo de disparo, la distancia a la portería, el ángulo, la posición de los defensores, el tipo de pase y muchos otros factores. Como resultado, xG describe la ventaja real del juego mucho mejor que un marcador de 1:0 o 2:2 en el tablero.

El widget xG incrustable hace que cualquier sitio web de fútbol sea notablemente más profesional. El usuario ve no solo los números de posesión y disparos, sino también un gráfico visual de goles esperados a lo largo del partido, comparación del xG del equipo y distribución de la calidad de los momentos. Este enfoque es utilizado por los principales medios deportivos y plataformas analíticas para explicar con más profundidad, por qué el equipo ganó o perdió.

Al conectar datos a través de la API de eventos deportivos, por ejemplo, desde el servicio API-sport para desarrolladores y empresas, puede construir automáticamente sus widgets xG para cualquier partido: desde ligas principales hasta torneos locales. Esto permite:

• aumentar la participación de la audiencia a través de analíticas más profundas;
• aumentar el tiempo en el sitio y la profundidad de las vistas de la página del partido;
• apoyar contenido para predicciones y apuestas basadas en métricas objetivas;
• fortalecer la marca del sitio al demostrar un enfoque experto en estadísticas.

A diferencia de las imágenes estáticas, el widget xG basado en la API puede actualizarse casi en tiempo real, adaptarse al diseño del sitio y escalar fácilmente a cientos de partidos simultáneamente. En este artículo, discutiremos qué datos se necesitan para xG, cómo obtenerlos a través de la API y cómo integrar paso a paso su propio widget en el sitio.

¿Qué datos proporciona la API de eventos deportivos para las analíticas xG?

El modelo xG clásico se basa en información detallada sobre los tiros a puerta y episodios del juego. En la API para eventos de fútbol, disponible a través de la ruta base /v2/fútbol/ en el dominio 2. api.api-sport.ru, ya hay una cantidad significativa de estadísticas que se pueden utilizar como base para análisis xG simplificados o extendidos.

En primer lugar, los endpoints /v2/fútbol/partidos и /v2/fútbol/partidos/{matchId} devuelven un objeto estadísticasDelPartido. Agrupa métricas clave por períodos de partido (TODOS, 1RA, 2DA): totalDisparosALaPortería, disparosALaPortería, totalDisparosDentroDelÁrea, totalTirosFueraDelÁrea, granOportunidadCreada, granOportunidadMarcada, granOportunidadFallada, así como parámetros adicionales para ataques, tiros, duelos, etc. Estos indicadores permiten evaluar la calidad de las oportunidades creadas incluso sin las coordenadas cuadro por cuadro de cada tiro.

En segundo lugar, a través de /v2/fútbol/partidos/{matchId}/eventos obtienes una cronología de episodios clave del juego: goles, penales, tarjetas, sustituciones y otros eventos. Al correlacionar eventos con estadísticas agregadas, es posible construir líneas de tiempo xG y mostrar en qué segmentos del partido el equipo creó las oportunidades más peligrosas.

Para proyectos avanzados, los datos del partido se pueden combinar con información sobre torneos, equipos y jugadores disponibles en las secciones /v2/fútbol/equipos, /v2/fútbol/jugadores, así como utilizar las cuotas de los bookmakers del campo oddsBase del partido. La combinación de análisis xG y datos de apuestas permite construir modelos más precisos del valor de las cuotas y crear productos únicos en la intersección de estadísticas y apuestas.

Requisitos para el sitio web y claves de acceso para conectarse a la API xG.

Para incrustar el widget xG basado en datos de la API, tu sitio no requiere ninguna infraestructura especial. Cualquier motor moderno (WordPress, solución personalizada en PHP/Node.js, frameworks como Laravel o Django) será suficiente, siempre que puedas agregar tu propio JavaScript y hacer solicitudes HTTP a la API externa desde el servidor.

Es importante señalar que la autorización en la API de Eventos Deportivos ocurre a través del encabezado Autorización con tu clave API. Por razones de seguridad, no se recomienda codificar la clave directamente en JavaScript del lado del cliente, ya que puede verse en el código fuente de la página. Es más confiable organizar un proxy backend simple: el frontend llama a tu servidor, y el servidor llama a la API https://api.api-sport.ru, añadiendo el encabezado de autorización.

Puedes obtener una clave personal en la cuenta personal de API-SPORT. Después de registrarte y seleccionar un plan, verás el valor de la clave API y podrás usarla en los encabezados de las solicitudes. Un modo de prueba o un plan limitado suele estar disponible para el desarrollo: esto es suficiente para depurar el widget, configurar la caché y verificar la carga en el sitio durante solicitudes masivas.

Desde la perspectiva del frontend, es recomendable asegurar el soporte HTTPS, el correcto funcionamiento de CORS (si estás haciendo solicitudes directas desde el navegador) y configurar la caché de respuestas de API en tu servidor. La caché puede establecerse por al menos 15–60 segundos para el modo en vivo para reducir el número de solicitudes y acelerar la carga del widget xG en la página.

Guía paso a paso: cómo incrustar el widget de analíticas xG en el sitio web a través de la API.

La integración del widget xG se puede desglosar cómodamente en varios pasos lógicos. Primero, determinas en qué páginas y en qué formato deseas mostrar xG: puede ser un bloque en la tarjeta del partido, una sección separada «Análisis Avanzado» o una inserción en el material que analiza el juego. En esta etapa, piensas en el tipo de visualización: total xG por equipos, gráfico de xG por minutos o una opción combinada.

A continuación, necesitas obtener el ID del partido para las solicitudes de API. Se puede tomar de la base de datos interna, de la respuesta del endpoint /v2/fútbol/partidos?fecha=YYYY-MM-DD o de la integración con otro de tus módulos (por ejemplo, la línea de apuestas o el calendario de transmisiones). Sabiendo idPartido, solicitas detalles del partido a través de /v2/fútbol/partidos/{matchId} y, si es necesario, eventos a través de /v2/fútbol/partidos/{matchId}/eventos.

En el lado del servidor, implementas la función de cálculo de xG. En el caso más simple, puedes usar estadísticas agregadas: asignar pesos para tiros desde dentro y fuera del área penal, para grandes oportunidades, para penales. Una fórmula simplificada puede servir como punto de partida, y puede ser refinada a medida que se acumulan datos. El resultado del cálculo son valores numéricos de xG para cada equipo y, opcionalmente, un array de puntos para el gráfico de tiempo.

El paso final es renderizar el widget en el frontend. El servidor devuelve un JSON con valores de xG pre-calculados a la página, y el código JavaScript construye gráficos (barras, líneas, «barra de progreso», etc.) en el estilo deseado basado en ello. Esta división de responsabilidades te permite mantener la clave API segura mientras gestionas de manera flexible la lógica y el diseño de la analítica xG.

Ejemplos de solicitudes de API y código para mostrar el widget xG en la página.

A continuación se muestra un ejemplo simplificado de la integración: una solicitud a la API de Eventos Deportivos, extrayendo estadísticas y calculando xG en el servidor o frontend. Primero, obtendremos información detallada sobre un partido específico por su ID. El ejemplo utiliza JavaScript con una solicitud a través de obtener. En un proyecto real, es mejor colocar un código similar en el servidor.

fetch('https://api.api-sport.ru/v2/football/matches/14570728', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
})
  .then(response => response.json())
  .then(match => {
    const statsAll = match.matchStatistics.find(s => s.period === 'ALL');
    const shotsGroup = statsAll.groups.find(g => g.groupName === 'Shots');
    const insideBox = shotsGroup.statisticsItems.find(i => i.key === 'totalShotsInsideBox').homeValue;
    const outsideBox = shotsGroup.statisticsItems.find(i => i.key === 'totalShotsOutsideBox').homeValue;
    const bigChances = statsAll.groups
      .find(g => g.groupName === 'Attack')
      .statisticsItems.find(i => i.key === 'bigChanceCreated').homeValue;
    // Пример простой модели xG для хозяев
    const xgHome = insideBox * 0.15 + outsideBox * 0.05 + bigChances * 0.35;
    console.log('xG домашней команды:', xgHome.toFixed(2));
  })
  .catch(console.error);

Este es solo un ejemplo de demostración: los pesos (0.15, 0.05, 0.35) se dan solo para ilustración y no son un modelo de producción listo. En una solución en vivo, puedes usar una fórmula de xG más compleja que tenga en cuenta parámetros adicionales de estadísticasDelPartido y eventos del partido. Es importante que la API ya proporcione datos estructurados que puedan ser procesados fácilmente de manera programática.

Después de calcular xG en el backend, es conveniente enviar solo JSON limpio con el resultado al frontend. Aquí hay un ejemplo de un proxy PHP simple que obtiene datos del partido de la API, calcula xG y lo devuelve en un formato listo para renderizar en el widget:

<?php
$matchId = (int)($_GET['matchId'] ?? 0);
$apiKey  = 'YOUR_API_KEY';
$ch = curl_init('https://api.api-sport.ru/v2/football/matches/' . $matchId);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: ' . $apiKey,
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
$match = json_decode($response, true);
$statsAll = null;
foreach ($match['matchStatistics'] as $periodStats) {
    if ($periodStats['period'] === 'ALL') {
        $statsAll = $periodStats;
        break;
    }
}
$shotsGroup = array_values(array_filter($statsAll['groups'], fn($g) => $g['groupName'] === 'Shots'))[0];
$attackGroup = array_values(array_filter($statsAll['groups'], fn($g) => $g['groupName'] === 'Attack'))[0];
$findItem = function($items, $key) {
    foreach ($items as $item) {
        if ($item['key'] === $key) return $item;
    }
    return null;
};
$insideHome = $findItem($shotsGroup['statisticsItems'], 'totalShotsInsideBox')['homeValue'] ?? 0;
$outsideHome = $findItem($shotsGroup['statisticsItems'], 'totalShotsOutsideBox')['homeValue'] ?? 0;
$bigHome = $findItem($attackGroup['statisticsItems'], 'bigChanceCreated')['homeValue'] ?? 0;
$xgHome = $insideHome * 0.15 + $outsideHome * 0.05 + $bigHome * 0.35;
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'matchId' => $matchId,
    'xg'      => [
        'home' => round($xgHome, 2),
    ],
]);
[/php]
<p>Фронтенд‑часть виджета считывает этот JSON и строит визуализацию — например, две горизонтальные шкалы xG для хозяев и гостей или линейный график. Благодаря тому, что вся тяжелая логика расчета и обращение к API сосредоточены на сервере, клиентский код остается легким и быстрым.</p>
</div>
<div class="universal_article">
<h2 id="contents-6">Настройка дизайна и параметров виджета xG‑аналитики под ваш сайт</h2>
<p>После того как базовый функционал xG‑виджета готов, самое время адаптировать его под визуальный стиль вашего ресурса. Для этого обычно достаточно набора CSS‑правил и небольшой конфигурации на JavaScript. Виджет должен естественно вписываться в общий дизайн: использовать те же шрифты, цветовую палитру, радиус скругления и отступы, что и остальные элементы сайта.</p>
<p>Один из распространенных подходов — задавать виджету конфигурацию через объект настроек: вы передаете цвета для домашней и гостевой команды, фон, тип диаграммы (столбцы, линии, прогресс‑бар), а также язык интерфейса. Эти параметры можно хранить в базе и управлять ими из админ‑панели. Ниже приведен упрощенный пример CSS‑стилей для xG‑блока.</p>
[code lang="css"]
.xg-widget {
  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  background: #0b1020;
  color: #ffffff;
  border-radius: 12px;
  padding: 16px 20px;
}
.xg-widget__bar {
  display: flex;
  align-items: center;
  margin-bottom: 8px;
}
.xg-widget__bar-label {
  width: 80px;
  font-size: 13px;
}
.xg-widget__bar-track {
  flex: 1;
  height: 8px;
  background: rgba(255, 255, 255, 0.08);
  border-radius: 999px;
  overflow: hidden;
}
.xg-widget__bar-fill--home {
  height: 100%;
  background: #1dd1a1;
}
.xg-widget__bar-fill--away {
  height: 100%;
  background: #ff9f43;
}

En el lado de JavaScript, simplemente estableces el ancho .xg-widget__bar-fill--local и .xg-widget__bar-fill--fuera proporcional a los valores xG calculados. Así, obtienes un widget ordenado, fácilmente legible y completamente personalizado. Si es necesario, se puede agregar un diseño adaptativo para que en dispositivos móviles los gráficos se apilen en una columna o se simplifiquen a cifras clave.

Si planeas usar análisis xG no solo para fútbol, sino también para otros deportes soportados por la plataforma API-SPORT., tiene sentido extraer estilos y componentes comunes en una biblioteca separada. Luego, agregar nuevos widgets —por ejemplo, para lanzamientos de baloncesto o momentos peligrosos en hockey— requerirá cambios mínimos en el código y no interrumpirá la integridad visual del proyecto.

Limitaciones, velocidad de actualización y costo de uso de la API xG.

Cualquier integración basada en una API externa debe tener en cuenta limitaciones técnicas y comerciales. En el caso del widget xG, esto incluye principalmente límites en el número de solicitudes por unidad de tiempo, restricciones generales de tráfico y almacenamiento en caché razonable. Al diseñar la arquitectura, vale la pena calcular cuántos partidos estarás sirviendo simultáneamente, con qué frecuencia actualizar los datos (por ejemplo, cada 15-30 segundos en modo en vivo) y qué volumen de estadísticas se necesita para cada solicitud.

En términos de velocidad de actualización, la API de Eventos Deportivos está orientada hacia un modo cercano al tiempo real: nuevos eventos y estadísticas aparecen muy rápidamente después de que realmente ocurren en el partido. Para la mayoría de los sitios web, esto es más que suficiente, especialmente al usar almacenamiento en caché del lado del servidor. Además, el equipo de servicio está desarrollando la infraestructura: se planea soporte para conexiones WebSocket en un futuro cercano, lo que permitirá recibir actualizaciones sin solicitudes HTTP constantes y hacer que los gráficos xG sean verdaderamente en streaming.

El costo de uso depende de la tarifa elegida y el volumen de datos: los niveles suelen diferir por el número de solicitudes, el conjunto de deportes disponibles y la profundidad de las estadísticas. Para proyectos pequeños, puedes comenzar con un plan básico y, a medida que la audiencia crezca, cambiar a uno más avanzado. Encontrarás términos detallados y capacidades actuales (incluidos módulos de IA desplegables para análisis inteligentes) en el sitio web. API-SPORT — API de deportes y apuestas.

Se debe prestar especial atención a la integración del widget xG con la API de cuotas de apuestas, disponible a través del campo oddsBase en el objeto del partido. Al correlacionar la dinámica de xG con los cambios en las cuotas, puedes construir paneles de análisis únicos para apostadores y tipsters profesionales. Tal producto aumenta el valor de tu recurso y abre oportunidades adicionales de monetización a través de programas de afiliados y suscripciones premium para estadísticas extendidas.