- ¿Qué es un widget de estadísticas de partidos y qué datos muestra?
- Cómo elegir una API de eventos deportivos para el widget de estadísticas de partidos.
- Cómo obtener estadísticas de partidos de fútbol a través de la API en JavaScript.
- Estructura de datos del partido de la API y preparación para la visualización en el widget.
- Ejemplo de código JavaScript para un widget de estadísticas de partidos con HTML y CSS.
- Cómo actualizar estadísticas de partidos en tiempo real a través de la API.
- Integrando el widget de estadísticas de partidos en un sitio web y errores comunes al trabajar con la API.
¿Qué es un widget de estadísticas de partidos y qué datos muestra?
El widget de estadísticas de partidos en JavaScript es un bloque interactivo que se incrusta en un sitio web y muestra métricas clave del juego en un formato visual amigable. Este widget funciona sobre la API de eventos deportivos, recupera datos brutos del partido y los transforma en tablas, gráficos, indicadores de posesión y líneas de tiempo de eventos comprensibles.
Basado en la API de Eventos Deportivos, puedes mostrar prácticamente cualquier métrica: puntuación por mitades, minuto actual del partido, alineaciones de equipos, estadísticas detalladas sobre tiros, posesión, duelos, faltas, tarjetas y córners. Además, están disponibles eventos en vivo (goles, sustituciones, tarjetas, VAR), así como bloques extendidos como métricas xG, revisiones de video y resúmenes del partido, si están presentes en la fuente. Para casas de apuestas y servicios analíticos, también es importante que la misma API pueda mostrar cuotas sobre resultados y totales, así como la dinámica de cambios en las líneas.
Un widget de estadísticas bien implementado se convierte en un punto de retención de audiencia: en medios deportivos, aumenta la profundidad de visualización; en el sitio de una casa de apuestas, ayuda al jugador a tomar una decisión de apuesta; y en una comunidad de aficionados o blog, hace que el contenido sea dinámico y «similar a un juego». Al utilizar una API lista como el servicio api-sport.pro, puedes obtener rápidamente datos detallados sobre fútbol, baloncesto, hockey, tenis, tenis de mesa, deportes electrónicos y otros deportes y mostrarlos en una interfaz unificada del widget.
Cómo elegir una API de eventos deportivos para el widget de estadísticas de partidos.
El primer paso para crear un widget estable es elegir un proveedor de datos confiable. Es importante que la API cubra los deportes y torneos necesarios. En la API de Eventos Deportivos, esto se resuelve a través del endpoint /v2/deporte, que devuelve una lista de deportes soportados (fútbol, hockey, baloncesto, tenis, tenis de mesa, deportes electrónicos y otros). Luego, a través de categorías y torneos, seleccionas campeonatos específicos que estarán disponibles en tu widget, utilizando, por ejemplo, métodos /v2/{sportSlug}/categorías и /v2/{sportSlug}/categorías/{categoryId} teniendo en cuenta el campo. torneosPredeterminados.
La profundidad y estructura de las estadísticas son igualmente importantes. Un widget moderno debería ser capaz de mostrar no solo la puntuación, sino también métricas avanzadas. En la API de Eventos Deportivos, el objeto de partido contiene campos estadísticasDelPartido con desgloses por períodos y grupos («Resumen del partido», «Tiros», «Duelos», etc.), así como eventosEnVivo para mostrar la línea de tiempo de eventos. Para proyectos de apuestas, la presencia del campo oddsBase, que devuelve mercados de apuestas y cuotas (incluyendo en vivo), así como el historial de sus cambios, es crítico. Todo esto permite construir tanto widgets simples como avanzados sobre la misma API.
También vale la pena evaluar las características técnicas: estabilidad de disponibilidad, velocidad de respuesta, límites de solicitudes justos, documentación clara y la presencia de ejemplos de código. La plataforma por el API de eventos deportivos api-sport.ru está orientada a desarrolladores: ofrece descripciones detalladas de OpenAPI, expande regularmente el conjunto de deportes y campos, y pronto complementará la interfaz REST con un flujo WebSocket para actualizaciones de estadísticas en tiempo real y herramientas de IA para análisis. Esto simplifica la escalabilidad del proyecto y la adición de nuevos deportes sin reescribir completamente el widget.
Cómo obtener estadísticas de partidos de fútbol a través de la API en JavaScript.
Para comenzar a trabajar con los datos, necesitas una clave API. En el ecosistema de api-sport.ru, se emite en la cuenta personal del desarrollador. Después de registrarte, ve a tu cuenta personal, genera la clave y úsala en el encabezado Autorización para todas las solicitudes a los puntos finales REST. Sin una clave válida, el servidor devolverá un error de autorización y los datos del partido no estarán disponibles.
El escenario básico para obtener estadísticas de partidos de fútbol en JavaScript se ve así: conoces el ID del partido (idPartido) y el deporte (fútbol). A continuación, envías una solicitud GET al método /v2/fútbol/partidos/{matchId} en el host de la API. En respuesta, recibes un objeto partido con todos los campos: estado, puntuación, equipos, detallado estadísticasDelPartido, un array eventosEnVivo, y si es necesario, cuotas oddsBase. A continuación se muestra un ejemplo de una solicitud simple usando obtener en el navegador.
const API_KEY = 'YOUR_API_KEY';
const MATCH_ID = 14570728; // пример ID матча
async function loadMatchStatistics() {
const response = await fetch(
`https://api.api-sport.ru/v2/football/matches/${MATCH_ID}`,
{
headers: {
'Authorization': API_KEY
}
}
);
if (!response.ok) {
throw new Error('Ошибка API: ' + response.status);
}
const match = await response.json();
console.log('Команды:', match.homeTeam.name, '—', match.awayTeam.name);
console.log('Текущий счет:', match.homeScore.current, ':', match.awayScore.current);
console.log('Статистика матча:', match.matchStatistics);
}
loadMatchStatistics().catch(console.error);
En la práctica, llamarás a este código no en la consola, sino dentro de la lógica del widget, pasando el objeto partido a la función de renderizado. Es importante proporcionar manejo de errores (por ejemplo, indisponibilidad del partido o problemas de red), así como verificar el estado del campo estado (por ejemplo, en progreso, completado, no comenzado) y mostrar correctamente el estado del juego en la interfaz.
Estructura de datos del partido de la API y preparación para la visualización en el widget.
La respuesta del punto final /v2/{sportSlug}/matches/{matchId} se construye en torno al objeto partido. Contiene campos básicos (identificador, estado, fechaEvento, inicioTimestamp), información sobre el torneo y la temporada, datos sobre el estadio (lugar), así como objetos de equipo anidados equipoLocal и equipoVisitante con sus nombres, logotipos y, si es necesario, plantillas (alineación). El puntaje actual e interino se almacena en objetos puntajeLocal и puntajeVisitante con campos actual, período1, período2 y similares para otros deportes.
El elemento clave para el widget de estadísticas es un array estadísticasDelPartido. Se divide en períodos (período: TODO, 1RO, 2DO etc.). Dentro de cada período, hay un array grupos, y dentro de él — un array statisticsItems con métricas específicas. Cada elemento contiene el nombre de la métrica (nombre), valores para los equipos locales y visitantes (local, visitante), valores numéricos (costoLocal, costoVisitante) y la clave del servicio clave, lo que facilita mapear la métrica al bloque de UI deseado. A continuación se muestra un fragmento simplificado de la respuesta:
// Фрагмент JSON-ответа матча
{
id: 14570728,
status: 'inprogress',
currentMatchMinute: 30,
homeTeam: { id: 195801, name: 'Montevideo Wanderers Reserve' },
awayTeam: { id: 195800, name: 'Rival Team' },
homeScore: { current: 1, period1: 1, period2: 0 },
awayScore: { current: 0, period1: 0, period2: 0 },
matchStatistics: [
{
period: 'ALL',
groups: [
{
groupName: 'Match overview',
statisticsItems: [
{
name: 'Ball possession',
home: '54%',
away: '46%',
key: 'ballPossession'
}
]
}
]
}
]
}
Antes de mostrar en el widget, tiene sentido normalizar la estructura en un formato más conveniente. Por ejemplo, puedes construir un diccionario por las claves de las estadísticas: { posesionDeBalón: { local: 54, visitante: 46 }, totalTirosALaPortería: { ... } }. Esto simplificará la representación de barras de progreso, gráficos y tablas de comparación. Si planeas mostrar cuotas y reseñas en video, asigna campos del objeto del partido por adelantado oddsBase и momentosDestacados, para cargarlos en pestañas separadas del widget o ventanas emergentes.
Ejemplo de código JavaScript para un widget de estadísticas de partidos con HTML y CSS.
A continuación se muestra un ejemplo simplificado pero funcional de un mini-widget para estadísticas de partidos de fútbol. Incluye marcado HTML básico, CSS mínimo para el estilo y código JavaScript que carga datos de la API de Eventos Deportivos y llena el bloque del widget. En un proyecto real, podrás expandirlo con métricas adicionales y adaptarlo al diseño deseado.
Primero, definamos el contenedor del widget y varios elementos para mostrar equipos, puntajes y un par de métricas clave.
<div id="match-widget">
<div class="mw-header">
<span id="mw-home-team"></span>
<span id="mw-score"></span>
<span id="mw-away-team"></span>
</div>
<div class="mw-meta">
<span id="mw-status"></span>
<span id="mw-minute"></span>
</div>
<div class="mw-stats">
<div class="mw-stat-row">
<span>Владение мячом</span>
<span id="mw-possession-home"></span>
<span id="mw-possession-away"></span>
</div>
<div class="mw-stat-row">
<span>Удары по воротам</span>
<span id="mw-shots-home"></span>
<span id="mw-shots-away"></span>
</div>
</div>
</div>
#match-widget {
max-width: 420px;
border: 1px solid #e0e0e0;
border-radius: 8px;
padding: 12px;
font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}
.mw-header {
display: flex;
justify-content: space-between;
font-weight: 600;
margin-bottom: 8px;
}
.mw-meta {
display: flex;
justify-content: space-between;
font-size: 12px;
color: #777;
margin-bottom: 8px;
}
.mw-stats {
border-top: 1px solid #f0f0f0;
padding-top: 8px;
}
.mw-stat-row {
display: flex;
justify-content: space-between;
font-size: 13px;
margin: 4px 0;
}
.mw-stat-row span:first-child {
flex: 1 1 auto;
}
.mw-stat-row span:nth-child(2),
.mw-stat-row span:nth-child(3) {
width: 40px;
text-align: center;
}
const API_KEY = 'YOUR_API_KEY';
const MATCH_ID = 14570728;
async function fetchMatch() {
const res = await fetch(
`https://api.api-sport.ru/v2/football/matches/${MATCH_ID}`,
{ headers: { 'Authorization': API_KEY } }
);
if (!res.ok) throw new Error('Ошибка API: ' + res.status);
return res.json();
}
function extractStat(match, key) {
const allPeriod = match.matchStatistics?.find(s => s.period === 'ALL');
if (!allPeriod) return null;
for (const group of allPeriod.groups) {
const item = group.statisticsItems.find(i => i.key === key);
if (item) return item;
}
return null;
}
async function renderMatchWidget() {
const match = await fetchMatch();
document.getElementById('mw-home-team').textContent = match.homeTeam.name;
document.getElementById('mw-away-team').textContent = match.awayTeam.name;
document.getElementById('mw-score').textContent =
`${match.homeScore.current} : ${match.awayScore.current}`;
document.getElementById('mw-status').textContent = match.status;
document.getElementById('mw-minute').textContent =
match.currentMatchMinute ? match.currentMatchMinute + "'" : '';
const possession = extractStat(match, 'ballPossession');
const shots = extractStat(match, 'totalShotsOnGoal');
if (possession) {
document.getElementById('mw-possession-home').textContent = possession.home;
document.getElementById('mw-possession-away').textContent = possession.away;
}
if (shots) {
document.getElementById('mw-shots-home').textContent = shots.home;
document.getElementById('mw-shots-away').textContent = shots.away;
}
}
renderMatchWidget().catch(console.error);
Este ejemplo demuestra un enfoque básico para la integración. En producción, agregarás manejo del estado de carga (pantallas de esqueleto), localización de estados, así como soporte para diferentes deportes, utilizando sportSlug y una interfaz de widget unificada construida sobre los campos universales de la API de Eventos Deportivos.
Cómo actualizar estadísticas de partidos en tiempo real a través de la API.
Para deportes en vivo, es importante que el usuario vea los cambios casi instantáneamente. La forma más sencilla de implementar esto en JavaScript es mediante sondeos periódicos de la API. Estableces un intervalo (por ejemplo, cada 15–30 segundos) que vuelve a llamar al endpoint /v2/fútbol/partidos/{matchId}, compara los nuevos datos con lo que ya se ha renderizado y actualiza solo los elementos de interfaz que han cambiado: puntaje, minuto actual, métricas clave de estadísticasDelPartido y la lista eventosEnVivo.
Al usar la plataforma api-sport.pro este enfoque ya proporciona actualizaciones de estadísticas fluidas. Pronto, el servicio complementará la interfaz REST con canales WebSocket, lo que le permitirá abandonar las consultas frecuentes y recibir eventos a través de suscripción en modo push. Su widget podrá escuchar un partido o torneo específico y reaccionar instantáneamente a goles, tarjetas, sustituciones y cambios en las cuotas, sin crear una carga innecesaria en la API y el frontend.
const API_KEY = 'YOUR_API_KEY';
const MATCH_ID = 14570728;
let lastHomeScore = null;
let lastAwayScore = null;
async function updateMatchLoop() {
try {
const res = await fetch(
`https://api.api-sport.ru/v2/football/matches/${MATCH_ID}`,
{ headers: { 'Authorization': API_KEY } }
);
if (!res.ok) throw new Error('Ошибка API: ' + res.status);
const match = await res.json();
if (match.homeScore.current !== lastHomeScore ||
match.awayScore.current !== lastAwayScore) {
lastHomeScore = match.homeScore.current;
lastAwayScore = match.awayScore.current;
// Обновляем счет и анимацию в виджете
document.getElementById('mw-score').textContent =
`${lastHomeScore} : ${lastAwayScore}`;
}
if (match.currentMatchMinute) {
document.getElementById('mw-minute').textContent =
match.currentMatchMinute + "'";
}
// Аналогично можно обновлять matchStatistics и liveEvents
} catch (e) {
console.error(e);
}
}
// Запускаем обновление каждые 20 секунд (значение подберите под свои лимиты)
setInterval(updateMatchLoop, 20000);
updateMatchLoop();
Es importante mantener un equilibrio entre la relevancia y la carga. Considere los límites de tasa y la caché en el lado de la API, no establezca un intervalo de 1–2 segundos sin una necesidad extrema. Con la aparición de WebSocket de api-sport.ru, podrá transitar el widget a una arquitectura con suscripción a eventos, dejando REST para la carga inicial de datos y escenarios de respaldo.
Integrando el widget de estadísticas de partidos en un sitio web y errores comunes al trabajar con la API.
Un widget listo en JavaScript se puede incrustar en casi cualquier sitio web: una página de aterrizaje estática, un CMS como WordPress, un portal de noticias o una vitrina de casas de apuestas. La opción básica de integración es colocar el contenedor HTML del widget en la ubicación deseada de la plantilla y conectar el archivo JS con la lógica para cargar y renderizar estadísticas. Si tiene múltiples páginas con partidos, puede pasar idPartido en el atributo de datos del contenedor o a través de parámetros de URL, de modo que el mismo script sirva a múltiples widgets.
Un error común es usar la clave de API directamente en el código del lado del cliente sin ningún proxy. Para proyectos públicos y de alta carga, es mejor mover todas las solicitudes a la API de Eventos Deportivos al backend (Node.js, PHP, Python) y solo servir datos preparados al frontend desde el servidor. Esto protege la clave de filtraciones y permite una gestión centralizada de la caché, límites y registros. Otro problema típico es ignorar el estado del partido y las zonas horarias: el widget continúa actualizándose después del pitido final o muestra horarios de inicio de partidos incorrectos para usuarios de otras regiones.
Los desarrolladores también a veces no tienen en cuenta las características estructurales estadísticasDelPartido y se atan rígidamente a los nombres textuales de grupos y métricas. Se recomienda confiar en claves estables (clave у statisticsItems) y diseñar la interfaz de manera que cuando aparezcan nuevos indicadores en la API, se puedan agregar fácilmente sin rehacer la lógica. Al completar la integración, pruebe el comportamiento del widget en diferentes estados de partidos (no iniciado, medio tiempo, terminado, pospuesto), en dispositivos móviles y durante la indisponibilidad temporal de la API. Al utilizar datos de Eventos Deportivos de api-sport.ru y una arquitectura ordenada, obtendrá un widget de estadísticas estable, rápido y escalable que se puede expandir a nuevos deportes y torneos.
