Как делать визуализацию спортивных данных (heatmap, passing map)?

Что такое heatmap и passing map в спортивной аналитике

Heatmap в спортивной аналитике — это тепловая карта, которая показывает концентрацию действий на площадке или поле. Цветовая шкала отражает плотность событий: чем участок горячее, тем чаще там происходили удары, отборы, передачи или касания мяча. На футбольном поле это помогает буквально увидеть стиль команды: высокое давление, игру через фланги, загрузку штрафной или контроль в центре.

Passing map — карта передач, которая отображает направление и частоту пасов между игроками. Обычно на схеме показаны позиции футболистов, линии между ними и толщина линий, связанная с количеством передач. Такая визуализация позволяет оценить, через кого строится атака, как работает первый пас, насколько активно используются фулбеки, есть ли перекос в одну из зон.

Обе визуализации критичны для скаутинга, тактического анализа, подготовки к матчу и беттинга. Они помогают принять решение на основе фактических данных, а не субъективного впечатления. Чтобы строить heatmap и passing map системно, без ручного ввода, необходим надежный источник событийной статистики — API спортивных данных. Именно такой программный доступ к матчам, командам, игрокам и статистике предоставляет платформа API спортивных данных api-sport.ru, поддерживающая футбол, баскетбол, хоккей, теннис, настольный теннис, киберспорт и другие виды спорта.

Какие API спортивных данных использовать для футбольной визуализации

Для построения наглядных heatmap и passing map по футболу важны три группы данных: информация о матчах, детальная статистика и события по ходу игры. В рамках Sport Events API на домене api.api-sport.ru это реализовано через эндпоинты семейства v2. Они позволяют получать список матчей, подробные детали конкретной встречи, составы команд, расширенную статистику и даже коэффициенты букмекеров через блок oddsBase.

Базовые запросы выполняются к эндпоинтам вида v2 football matches и v2 football matches {matchId}. В ответе вы получаете объект Match с полями tournament, teams, score, venue, а главное — массив matchStatistics с разбивкой по периодам и группам показателей. В нем содержатся ключевые метрики для визуализации: владение мячом, общие удары, удары в створ, касания в штрафной, передачи в последнюю треть, точные передачи и многое другое. Эти данные можно агрегировать по зонам поля и использовать как основу для тепловых карт и карт передач.

Отдельный эндпоинт v2 football matches {matchId} events возвращает хронологию liveEvents: голы, карточки, замены и другие важные события. На их основе формируют таймлайны и комбинированные графики. В продвинутых проектах событийный поток удобно получать в режиме реального времени через WebSocket. Поддержка WebSocket уже в планах развития сервиса api-sport.ru, что откроет путь к онлайн тепловым картам и живым passing map прямо во время матча. Дополнительно API букмекеров с коэффициентами позволяет поверх визуализации накладывать динамику рынка ставок.

Как получить данные матча через API для построения тепловой карты игроков

Первый шаг к любой тепловой карте — получение корректных данных матча. В Sport Events API для этого используется эндпоинт v2 football matches {matchId}. В ответе вы получаете единый объект Match, в котором уже есть команды, составы с позицией каждого игрока в объекте lineup, текущий счет, статус встречи и массив matchStatistics с подробной статистикой по периодам ALL, 1ST, 2ND.

Чтобы отправлять запросы к API, понадобится ключ авторизации. Его можно сгенерировать в защищенном разделе платформы в личном кабинете api-sport.ru. После этого достаточно передавать ключ в заголовке Authorization. Ниже пример получения подробной информации о футбольном матче по идентификатору в браузере или Node.js с помощью 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);
  });

На следующем этапе данные из matchStatistics можно превратить в матрицу активности по зонам. Для простой тепловой карты используют агрегированные показатели. Например, касания в штрафной touchesInOppBox, передачи в последнюю треть finalThirdEntries и удары из разных зон. Если в рамках вашего тарифа дополнительно подключен поток событий с координатами действий, можно строить уже полноценные heatmap по x и y, разбивая поле на сетку и считая количество событий в каждой ячейке.

Как сделать heatmap ударов и действий игроков по данным API

При создании тепловой карты ударов важно правильно извлечь из API метрики, связанные с атакующими действиями. В объекте matchStatistics существуют группы Shots и Attack, где содержатся показатели totalShotsOnGoal, shotsOnGoal, totalShotsInsideBox, totalShotsOutsideBox, touchesInOppBox, bigChanceCreated и другие. Эти значения уже дают представление о том, в каких зонах и с какой частотой команда или конкретный игрок создает угрозу.

Чтобы превратить статистику в heatmap, обычно поле делят на сетку, каждая ячейка которой отвечает за сектор. Если у вас есть координаты ударов и действий, вы просто подсчитываете количество событий на ячейку. При работе только с агрегированными данными из matchStatistics можно моделировать интенсивность по вертикальным и горизонтальным полосам, например отдельно оценивать левый фланг, правый фланг и центральную зону, а также делить поле на третьи.

Ниже приведен пример на Python, который забирает данные матча через API, извлекает основные показатели по ударам и подготавливает основу для визуализации тепловой карты в виде двумерной матрицы. Для реального проекта вы можете заменить условную матрицу на результат обработки координат.

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]
]

Готовую матрицу удобно отрисовывать через библиотеки визуализации, окрашивая ячейки в зависимости от интенсивности. Если вы дополнительно подключаете к Sport Events API собственные трекинговые данные или координаты ударов, их можно объединить в одном пайплайне и построить детализированную тепловую карту действий каждого игрока с точностью до конкретной точки на поле.

Как построить passing map передач команды на основе событийного API

Passing map помогает увидеть структуру розыгрыша мяча через связи между футболистами. Условно каждый игрок — это узел графа, а передачи между ними — ребра, толщина и цвет которых зависят от частоты и точности пасов. Для расчета таких связей нужны два слоя данных: состав команды с идентификаторами игроков и события, отражающие передачи между ними. Первый слой предоставляет эндпоинт v2 football matches {matchId} через объекты homeTeam, awayTeam и lineup. Второй слой формируется на основе событийного фида и статистики из matchStatistics.

Эндпоинт v2 football matches {matchId} events возвращает массив events с LiveEvent по ходу встречи. Он особенно полезен в сочетании с агрегированными показателями из группы Passes, в которой есть accuratePasses, passes, finalThirdEntries, accurateLongBalls, accurateCross. Эти данные позволяют оценить общий объем и качество пасов для команды, а далее распределить их по связкам игроков, если в вашем тарифе подключен расширенный событийный поток с указанием исполнителя и получателя передачи.

Ниже приводится пример на JavaScript, который забирает список событий матча и подготавливает структуру для простого графа передач. В массиве passes предполагаются события, в которых уже выделены passerId и receiverId. Такую структуру можно получить либо из продвинутого тарифного плана, либо из собственной предобработки сырых данных.

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

Полученный массив связей можно передать в любую библиотеку визуализации графов и отрисовать passing map поверх схемы поля. В перспективе платформа api-sport.ru планирует развивать инструменты реального времени на базе WebSocket и модулей AI. Это откроет возможность строить карты передач с онлайн обновлением и автоматическими инсайтами, например выявлением ключевых связок и нестандартных паттернов розыгрыша.

Инструменты и библиотеки для визуализации спортивных данных из API (Python, JavaScript)

После того как вы настроили получение данных через Sport Events API, следующий шаг — выбор стека визуализации. В экосистеме Python популярны связки pandas плюс matplotlib или seaborn для статичных графиков и plotly для интерактивных дашбордов. Для футбольных полей часто применяют специализированную библиотеку mplsoccer, которая упрощает отрисовку разметки, тепловых карт и карт передач на стандартном футбольном поле.

В браузере основным инструментом для сложной интерактивной графики остается D3.js. Для более быстрых внедрений подойдут Chart.js, ECharts или Highcharts, которые хорошо справляются с тепловыми матрицами и сеточными графиками. Клиентские приложения удобно соединять с API через fetch или axios, а в реальном времени обновлять данные по WebSocket, который планируется добавить в инфраструктуру api-sport.ru. Это позволит строить живые панели с онлайн heatmap и обновляемыми passing map без перезагрузки страницы.

Ниже приведен пример минимального кода на Python, который получает данные матча из API и строит простую тепловую карту на основе условного набора координат ударов с помощью matplotlib. На практике вместо списка shots вы будете использовать реальные координаты, полученные из собственного трекинга или расширенного событийного фида.

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

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