Перейти к основному содержимому

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

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

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

ПолеТипОписание
idintУникальный ID матча.
statusenumnotstarted, inprogress, finished, canceled, postponed, interrupted, suspended, delayed, willcontinue.
statusDescriptionstring?Человекочитаемое расширение статуса (например "1st half", "Finished (OT)", "Postponed"). В спеке объявлено как nullable.
scoreStatusScoreStatusОкончательность счёта завершённого матча: final (true / false / null). В ответе по ID — всегда; в списках — при fields=scoreStatus. См. ниже.
dateEventstringДата матча YYYY-MM-DD.
startTimestampint (ms)UNIX timestamp начала матча в миллисекундах (например 1748426400000). Делите на 1000 для секунд.
currentMatchMinuteint?Текущая минута live-матча. Для inprogress футбола / хоккея.
homeTeam / awayTeamTeamWithLineupКоманды. name, fullName, translation.ru (у команд — единственное число translation, в отличие от translations у игроков/турниров), country, gender (M/F), manager, image, lineup (состав, может быть пустым у индивидуальных видов).
homeScore / awayScoreScoreСчёт. Содержимое зависит от вида спорта — см. Sport-specific.
tournamentTournamentBriefТурнир: id, name, translations.ru.
seasonSeasonBriefСезон: id, name, year.
categoryCategoryBriefКатегория (страна/регион): id, name, image.
roundInfoRoundInfoРаунд: name (строка, напр. "Round of 16", "Final") и round (целое — номер раунда).
venueVenue?Стадион / арена: name, capacity, city.name, country.name.
refereeReferee?Судья. Заполняется в football; для остальных видов обычно отсутствует. См. ниже.
liveEventsLiveEvent[]?Только в /v2/{sportSlug}/matches/{matchId}. В списке матчей не приходит.
matchStatisticsarray?Группы статистики. Набор ключей и групп различается по виду спорта.
oddsBaseOddsMarket[]?Базовые рынки коэффициентов (1×2, тотал, гандикап). Возвращается всегда.
oddsBkBookmakerOdds?Расширенные рынки букмекеров (Melbet, Pari, Marathon, Betboom). Только при with_bk_odds=true.
hasBkOddsobject{ melbet, pari, marathon, betboom: boolean } — наличие коэффициентов. Присутствует всегда.
highlightsHighlight[]?Видеохайлайты: 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.

scoreStatus — окончательный ли счёт​

Статус finished означает, что матч закончился, но не гарантирует, что счёт больше не изменится: явного признака «результат окончательный» у источника данных нет, а в низших и любительских лигах счёт корректируется уже после завершения примерно в 17–25% матчей — в основном в течение 4–72 часов, изредка до недели. В профессиональных лигах и топ-турнирах такие корректировки единичны (≈0,2–0,5%).

Блок scoreStatus отвечает на вопрос «можно ли кэшировать результат»:

{
  "scoreStatus": {
    "final": true
  }
}
ПолеТипОписание
finalbool?true — счёт окончательный; false — матч завершён, но счёт ещё может быть скорректирован; null — матч не завершён (в т.ч. canceled / postponed).

final становится true, когда выполняется любое из условий: матч профессиональной лиги или топ-турнира; результат перепроверен и подтверждён; с момента последнего изменения данных прошло около недели.

Рекомендуемый порядок работы:

  1. Матч завершён и final: true — результат можно кэшировать без ограничений.
  2. Матч завершён и final: false — перепроверяйте такие матчи по ids= (например раз в сутки), пока final не станет true.
  3. final: null — матч ещё не сыгран либо отменён / перенесён; ориентируйтесь на status.

Где присутствует: в GET /v2/{sportSlug}/matches/{matchId} — всегда; в списках (/matches, /matches/live, /teams/{teamId}/matches, /h2h) — при fields=scoreStatus. Без параметра выдача списков не меняется.

WebSocket. Блок scoreStatus в сообщения не входит, формат прежний. Если вы остаётесь подписаны на матч после его завершения, исправленный счёт придёт обычным match_delta с изменёнными homeScore / awayScore (и winner / winnerCode) — так же, как любое обновление по ходу матча.

# Завершённые матчи дня с признаком окончательности счёта
curl -H "Authorization: YOUR_API_KEY" \
  "https://api.api-sport.ru/v2/football/matches?date=2026-09-15&status=finished&fields=id,status,scoreStatus"

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"

См. также​

Последнее обновление