Как встроить на сайт виджет xG-аналитики?

Что такое xG-аналитика в футболе и зачем встраивать xG‑виджет на сайт

xG (expected goals, ожидаемые голы) — это метрика, показывающая, насколько опасные моменты создала команда и сколько голов она должна была забить по качеству ударов, а не по фактическому счету. Для расчета учитываются тип удара, расстояние до ворот, угол, положение защитников, тип передачи и множество других факторов. В результате xG гораздо лучше описывает реальное игровое преимущество, чем счет 1:0 или 2:2 на табло.

Встраиваемый xG‑виджет делает любой футбольный сайт заметно профессиональнее. Пользователь видит не только цифры по владению и ударам, но и наглядный график ожидаемых голов по ходу матча, сравнение xG команд, распределение качества моментов. Такой подход используют ведущие спортивные медиа и аналитические платформы, чтобы глубже объяснять, почему команда выиграла или проиграла.

Подключив данные через API спортивных событий, например, с сервиса API‑спорт для разработчиков и бизнеса, вы можете автоматически строить свои xG‑виджеты для любого матча: от топ‑лиг до локальных турниров. Это позволяет:

• повысить вовлеченность аудитории за счет более глубокой аналитики;
• увеличить время на сайте и глубину просмотров страниц матчей;
• поддержать контент для прогнозов и беттинга на основе объективных метрик;
• укрепить бренд сайта, показывая экспертный подход к статистике.

В отличие от статических картинок, xG‑виджет на базе API может обновляться почти в реальном времени, подстраиваться под дизайн сайта и легко масштабироваться на сотни матчей одновременно. В этой статье разберем, какие данные нужны для xG, как их получить через API и как шаг за шагом встроить на сайт собственный виджет.

Какие данные дает API спортивных событий для xG‑аналитики

Классическая xG‑модель опирается на детальную информацию об ударах по воротам и игровых эпизодах. В API спортивных событий по футболу, доступном через базовый путь /v2/football/ на домене api.api-sport.ru, уже есть значительная часть статистики, которая может использоваться как основа для упрощенной или расширяемой xG‑аналитики.

Во-первых, эндпоинты /v2/football/matches и /v2/football/matches/{matchId} возвращают объект matchStatistics. В нем по периодам матча (ALL, 1ST, 2ND) сгруппированы ключевые метрики: totalShotsOnGoal, shotsOnGoal, totalShotsInsideBox, totalShotsOutsideBox, bigChanceCreated, bigChanceScored, bigChanceMissed, а также дополнительные параметры по атакам, ударам, единоборствам и т.д. Эти показатели позволяют оценить качество создаваемых моментов даже без покадровых координат каждого удара.

Во-вторых, через /v2/football/matches/{matchId}/events вы получаете хронологию ключевых игровых эпизодов: голы, пенальти, карточки, замены и другие события. Сопоставляя события с агрегированной статистикой, можно строить таймлайны xG и показывать, в какие отрезки матча команда создавала наибольшее количество опасных моментов.

Для продвинутых проектов данные матчей можно комбинировать с информацией о турнирах, командах и игроках, доступной в разделах /v2/football/teams, /v2/football/players, а также использовать коэффициенты букмекеров из поля oddsBase матча. Связка xG‑аналитики и данных о ставках позволяет строить более точные модели ценности коэффициентов и создавать уникальные продукты на стыке статистики и беттинга.

Требования к сайту и ключи доступа для подключения xG‑API

Чтобы встроить xG‑виджет на основе данных API, вашему сайту не требуется какая‑то особая инфраструктура. Подойдет любой современный движок (WordPress, самописное решение на PHP/Node.js, фреймворки типа Laravel или Django), если вы можете добавлять собственный JavaScript и выполнять HTTP‑запросы к внешнему API с сервера.

Важно учитывать, что авторизация в Sport Events API происходит через заголовок Authorization с вашим API‑ключом. По соображениям безопасности не рекомендуется жестко прописывать ключ непосредственно в JavaScript на стороне браузера, так как его можно будет увидеть в исходном коде страницы. Надежнее организовать простой бэкенд‑прокси: фронтенд обращается к вашему серверу, а сервер — к API https://api.api-sport.ru, добавляя заголовок авторизации.

Получить персональный ключ можно в личном кабинете API‑SPORT. После регистрации и выбора тарифа вы увидите значение API‑ключа и сможете использовать его в заголовках запросов. Для разработки обычно доступен тестовый режим или ограниченный тариф: этого достаточно, чтобы отладить виджет, настроить кэширование и проверить нагрузку на сайт при массовых обращениях.

С точки зрения фронтенда желательно обеспечить поддержку HTTPS, корректную работу CORS (если вы все‑таки делаете прямые запросы из браузера) и настроить кэширование ответов API на своем сервере. Кэш можно устанавливать хотя бы на 15–60 секунд для live‑режима, чтобы снизить количество запросов и ускорить загрузку xG‑виджета на странице.

Пошаговая инструкция: как встроить на сайт виджет xG‑аналитики через API

Интеграцию xG‑виджета удобно разбить на несколько логичных шагов. Сначала вы определяете, на каких страницах и в каком формате хотите отображать xG: это может быть блок в карточке матча, отдельный раздел «Расширенная аналитика» или вставка в материал с разбором игры. На этом этапе вы продумываете тип визуализации: суммарный xG по командам, график xG по минутам или комбинированный вариант.

Далее вам нужно получать идентификатор матча для запросов к API. Его можно взять из внутренней базы, из ответа эндпоинта /v2/football/matches?date=YYYY-MM-DD или из интеграции с другим вашим модулем (например, линией ставок или расписанием трансляций). Зная matchId, вы запрашиваете детали матча через /v2/football/matches/{matchId} и, при необходимости, события через /v2/football/matches/{matchId}/events.

На стороне сервера вы реализуете функцию расчета xG. В простейшем варианте можно использовать агрегированную статистику: назначить веса для ударов из штрафной и за ее пределами, для больших моментов (big chances), для пенальти. Упрощенная формула может служить отправной точкой, при этом ее можно совершенствовать по мере накопления данных. Результат расчета — числовые значения xG по каждой команде и, опционально, массив точек для графика по времени.

Финальный шаг — отрисовка виджета на фронтенде. Сервер отдает на страницу JSON с предрасчитанными значениями xG, а JavaScript‑код строит на его основе диаграммы (столбчатые, линейные, «progress bar» и т.п.) в нужном стиле. Такое разделение обязанностей позволяет не раскрывать API‑ключ и в то же время гибко управлять логикой и дизайном xG‑аналитики.

Примеры запросов к API и кода для вывода xG‑виджета на страницу

Ниже приведен упрощенный пример связки: запрос к Sport Events API, извлечение статистики и расчет xG на стороне сервера или фронтенда. Сначала получим подробную информацию о конкретном матче по его идентификатору. В примере используется JavaScript с запросом через fetch. В реальном проекте аналогичный код лучше располагать на сервере.

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

Это лишь демонстрационный пример: веса (0.15, 0.05, 0.35) даны для иллюстрации и не являются готовой продакшн‑моделью. В боевом решении вы можете использовать более сложную xG‑формулу, учитывающую дополнительные параметры из matchStatistics и событий матча. Важно, что API уже предоставляет структурированные данные, которые легко обрабатывать программно.

После расчета xG на бэкенде удобно отдавать на фронтенд только чистый JSON с результатом. Вот пример простого PHP‑прокси, который забирает данные матча из API, считает xG и возвращает их в формате, готовом к отрисовке в виджете:

<?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;
}

На стороне JavaScript вы просто задаете ширину .xg-widget__bar-fill--home и .xg-widget__bar-fill--away пропорционально рассчитанным значениям xG. Таким образом, вы получаете аккуратный, легко читаемый и полностью брендированный виджет. При необходимости можно добавить адаптивную верстку, чтобы на мобильных устройствах диаграммы складывались в колонку или упрощались до ключевых цифр.

Если вы планируете использовать xG‑аналитику не только для футбола, но и для других видов спорта, которые поддерживает платформа API‑SPORT, имеет смысл вынести общие стили и компоненты в отдельную библиотеку. Тогда добавление новых виджетов — например, для бросков в баскетболе или опасных моментов в хоккее — потребует минимальных правок в коде и не нарушит визуальную целостность проекта.

Ограничения, скорость обновления и стоимость использования xG‑API

Любая интеграция на базе внешнего API должна учитывать технические и коммерческие ограничения. В случае с xG‑виджетом это, прежде всего, лимиты на количество запросов в единицу времени, общие ограничения по трафику и разумное кэширование. При проектировании архитектуры стоит сразу просчитать, сколько матчей вы будете одновременно обслуживать, с какой частотой обновлять данные (например, каждые 15–30 секунд для live‑режима) и какой объем статистики нужен для каждого обращения.

По скорости обновления Sport Events API ориентирован на режим, близкий к реальному времени: новые события и статистика появляются очень быстро после их фактического возникновения в матче. Для большинства сайтов этого более чем достаточно, особенно при использовании кэша на стороне сервера. Дополнительно команда сервиса развивает инфраструктуру: в ближайшее время планируется поддержка WebSocket‑подключений, что позволит получать обновления без постоянных HTTP‑запросов и делать xG‑графики по‑настоящему потоковыми.

Стоимость использования зависит от выбранного тарифа и объема данных: обычно различаются уровни по количеству запросов, набору доступных видов спорта и глубине статистики. Для небольших проектов можно стартовать с базового плана, а по мере роста аудитории перейти на более продвинутый. Подробные условия и актуальные возможности (включая разворачиваемые AI‑модули для интеллектуальной аналитики) вы найдете на сайте API‑SPORT — спортивное и букмекерское API.

Отдельного внимания заслуживает интеграция xG‑виджета с API букмекерских коэффициентов, доступных через поле oddsBase в объекте матча. Сопоставляя динамику xG с изменением коэффициентов, вы можете строить уникальные панели аналитики для бетторов и профессиональных капперов. Такой продукт повышает ценность вашего ресурса и открывает дополнительные возможности монетизации за счет партнерских программ и премиальных подписок на расширенную статистику.