Структура объекта Match

Match — центральный объект API. Базовая структура единая для всех 7 видов спорта, но есть sport-specific расширения в виде вложенных объектов (Match.tennis, Match.esports) и расхождения в интерпретации общих полей (Score, matchStatistics, liveEvents).

Базовые поля (все спорты)

Поле	Тип	Описание
id	int	Уникальный ID матча.
status	enum	notstarted, inprogress, finished, canceled, postponed, interrupted, suspended, delayed, willcontinue.
statusDescription	string?	Человекочитаемое расширение статуса (например "1st half", "Finished (OT)", "Postponed"). В спеке объявлено как nullable.
dateEvent	string	Дата матча YYYY-MM-DD.
startTimestamp	int (ms)	UNIX timestamp начала матча в миллисекундах (например 1748426400000). Делите на 1000 для секунд.
currentMatchMinute	int?	Текущая минута live-матча. Для inprogress футбола / хоккея.
homeTeam / awayTeam	TeamWithLineup	Команды. name, fullName, translation.ru (у команд — единственное число translation, в отличие от translations у игроков/турниров), country, gender (M/F), manager, image, lineup (состав, может быть пустым у индивидуальных видов).
homeScore / awayScore	Score	Счёт. Содержимое зависит от вида спорта — см. Sport-specific.
tournament	TournamentBrief	Турнир: id, name, translations.ru.
season	SeasonBrief	Сезон: id, name, year.
category	CategoryBrief	Категория (страна/регион): id, name, image.
roundInfo	RoundInfo	Раунд: name (строка, напр. "Round of 16", "Final") и round (целое — номер раунда).
venue	Venue?	Стадион / арена: name, capacity, city.name, country.name.
referee	Referee?	Судья. Заполняется в football; для остальных видов обычно отсутствует. См. ниже.
liveEvents	LiveEvent[]?	Только в /v2/{sportSlug}/matches/{matchId}. В списке матчей не приходит.
matchStatistics	array?	Группы статистики. Набор ключей и групп различается по виду спорта.
oddsBase	OddsMarket[]?	Базовые рынки коэффициентов (1×2, тотал, гандикап). Возвращается всегда.
oddsBk	BookmakerOdds?	Расширенные рынки Melbet. Только при with_bk_odds=true.
hasBkOdds	object	{ melbet: boolean } — наличие коэффициентов. Присутствует всегда.
highlights	Highlight[]?	Видеохайлайты: title, url, image.

Score

{
  current: number,
  period1: number?, period2: number?, period3: number?, period4: number?, period5: number?,
  period1TieBreak: number?, ... period5TieBreak: number?,   // только теннис
  penalties: number?,                                       // футбол: серия пенальти
  point: string?,                                           // теннис live: "0", "15", "30", "40", "A"
  display: string?                                          // человекочитаемое представление
}

Что лежит в periodN — зависит от вида спорта:

• Football: period1 / period2 — голы по таймам, period3 — овертайм, penalties — серия пенальти.
• Ice Hockey: period1–period3 — голы по периодам, period4 — OT, period5 — буллиты.
• Basketball: period1–period4 — очки по четвертям, period5+ — овертаймы.
• Tennis / Table Tennis: period1–period5 — геймы / очки по сетам; periodNTieBreak — счёт тайбрейка в N-м сете.
• Esports (на уровне EsportsGame.homeScore): CS2 — раунды по половинам в period1 / period2; Dota 2 / LoL — current = kills.

Подробнее — на странице конкретного спорта в разделе Sport-specific.

Sport-specific расширения

• Match.tennis: TennisData — только в Tennis API. Сеты, тайбрейки, momentum-график, point-by-point (последнее — только в детальном эндпоинте). См. Sport-specific → Tennis.
• Match.esports: EsportsData — только в Esports API. CS2 / Dota 2 / LoL — разная структура EsportsGame. См. Sport-specific → Esports.

Эти поля размечены метаданными x-sports (Match.tennis → ["tennis"], Match.esports → ["esports"]). По ним Sport Schema Explorer показывает/приглушает поля под выбранный спорт. Физически из единого бандла поля не вырезаются — в API Reference видна полная поверхность ответа для всех видов.

Referee (только football)

referee: {
  id: 13456,               // nullable — может быть null, если арбитр не идентифицирован
  name: "Felix Zwayer",
  translations: { ru: "Феликс Цвайер" },
  country: { name: "Germany" },
  yellowCards: 4.2,        // среднее за матч в текущем сезоне
  redCards: 0.3,
  yellowRedCards: 0.1,     // вторая жёлтая → красная
  games: 28                // судейских матчей в сезоне
}

Поле Referee размечено в спеке как football-специфичное (x-sports: ["football"]). Для остальных видов оно либо отсутствует, либо null. Referee.id в спеке объявлен (integer, nullable), но может быть null — поэтому для надёжной идентификации опирайтесь и на name.

LiveEvent

Доступно только в /v2/{sportSlug}/matches/{matchId} (не в списке).

{
  time: number,            // минута матча
  timeSeconds: number,     // секунды от старта тайма
  type: string,            // goal | card | substitution | inGamePenalty | penaltyShootout | varDecision | injuryTime | period
  class: string?,          // подтип (yellow/red/regular/penalty/...)
  team: "home" | "away",
  player: { id, name, translations.ru },
  playerIn: object?,       // только для substitution
  playerOut: object?,
  reason: string?,
  from: string?,
  homeScore: number,       // снимок счёта на момент события
  awayScore: number
}

Enum type ориентирован на футбол — для других видов спорта возможны иные классы. Полный perevod типов по видам — на странице каждого спорта в Sport-specific.

Получение Match

# Список матчей с фильтрацией
curl -H "Authorization: YOUR_API_KEY" \
  "https://api.api-sport.ru/v2/football/matches?date=2026-05-28&status=inprogress"

# Детальная информация о матче (включая lineup, liveEvents, расширенные matchStatistics)
curl -H "Authorization: YOUR_API_KEY" \
  "https://api.api-sport.ru/v2/football/matches/14570728?with_bk_odds=true"

См. также

• Pagination — page / page_size, streaming vs paginated, ids.
• Search — /search + q в списках.
• Bookmaker Odds — oddsBase vs oddsBk (Melbet).
• Травмы и дисквалификации — словарь причин для lineup.missingPlayers.
• Sport-specific — что специфично для каждого вида спорта.
• WebSocket → Snapshot vs Delta — какие поля Match меняются в match_delta.