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

Changelog

История изменений REST + WebSocket API Sport Events. Семантика версий — SemVer.

v2.0.23 (текущая)​

Новый букмекер Betboom (oddsBk)​

  • Добавлен четвёртый букмекер — Betboom (БетБум) (slug betboom) в oddsBk и hasBkOdds. Параметр bookmaker_ids теперь принимает melbet, pari, marathon, betboom (через запятую).
  • Match.hasBkOdds теперь включает ключ betboom: { "melbet": true|false, "pari": true|false, "marathon": true|false, "betboom": true|false }. Наличие коэффициентов у букмекеров независимо.
  • Match.oddsBk может содержать ключ betboom с теми же схемами (BookmakerOddsData / BkOddsMarket / BkOddsStake / BkOddsLine), что и melbet/pari/marathon, — единые слаги рынков и исходов (result → w1/x/w2, total → over/under, handicap → handicap_1/handicap_2).
  • Betboom доступен для всех семи видов спорта — football, ice-hockey, basketball, tennis, table-tennis, volleyball, esports. Набор рынков (зависит от вида спорта): исход (1×2 — для видов с ничьей), фора, тотал.
  • Рынки по таймам (футбол): для football Betboom дополнительно отдаёт те же рынки на 1-й и 2-й тайм — отдельными ключами markets с каноническими слагами 1st_half_result / 1st_half_handicap / 1st_half_total и 2nd_half_* (имена вида «1st Half: Total»). Структура рынка — как у полноматчевых.
  • Подробнее — Concepts → Bookmaker Odds.

v2.0.22​

Курсорная пагинация списка матчей​

  • Параметр cursor= в GET /v2/{sport}/matches — полный обход больших выборок (например, диапазона дат за месяц) без ограничения в 100 страниц и без замедления на глубине: время ответа каждого батча не зависит от того, насколько далеко вы продвинулись.
    • первый запрос — с пустым значением (cursor=), дальше подставляйте nextCursor из каждого ответа, повторяя остальные параметры фильтра без изменений; nextCursor: null — выборка исчерпана;
    • ответ в этом режиме — {matches, nextCursor} (без totalMatches); размер батча — page_size (1–500, по умолчанию 500), порядок — sort=asc|desc;
    • сочетается со всеми фильтрами списка (date, date_from/date_to, status, tournament_id, team_id, exclude_amateur, fields=/view=, with_bk_odds и др.); несовместим с page, ids и q (400);
    • классическая пагинация page/page_size работает как раньше; в документации явно зафиксирован её потолок — page не больше 100 (большие значения приводятся к 100). Для выгрузок глубже — курсорный режим.

WebSocket: уведомление об удалении матча​

  • Новый тип сообщения match_deleted — приходит подписчикам матча и спорт-канала, если матч удалён из ленты данных (например, встреча убрана или пересоздана источником расписания): {"type": "match_deleted", "matchId": 12345678, "sportSlug": "football", "timestamp": 1783420000000}. Получив его, прекратите ожидать обновления по этому матчу (snapshot/delta больше не придут) и при необходимости отпишитесь от топика. Подробности — в описании сообщений WebSocket.

Улучшение текстового поиска матчей​

  • Поиск ?q= теперь заметно сильнее приоритизирует матчи, ближайшие к текущему моменту: по названию команды сначала находятся её сегодняшние/ближайшие и недавние матчи, а не встречи многолетней давности. Точные исторические запросы (например, два названия команд) работают как раньше.
  • Поиск стал быстрым и лёгким режимом: ответ — всегда компактные карточки матчей (без составов, статистики, событий и базовых коэффициентов), максимум 25 результатов (limit 1–25, по умолчанию 20). Параметры fields, view и with_pregame в режиме поиска игнорируются; with_bk_odds поддерживается. Полную карточку найденного матча запрашивайте по ID: GET /v2/{sport}/matches/{id}.

v2.0.21​

Квота ключа и заголовки лимитов​

  • Новый эндпоинт GET /v2/account/usage — самодиагностика API-ключа: тарифный план, дневной лимит и его остаток, момент сброса квоты (resetAt, миллисекунды) и список доступных видов спорта. Запрос к этому эндпоинту не расходует дневную квоту и остаётся доступным даже после исчерпания лимита — удобно диагностировать причину 429.
  • Заголовки X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset — теперь во всех ответах API для тарифов с дневным лимитом: лимит, остаток на сегодня и момент сброса квоты (миллисекунды). Тела ответов не менялись.

Таймзона фильтров по дате​

  • Параметр tz= (IANA, например Europe/London, Asia/Tokyo) в GET /v2/{sport}/matches, /matches/{date}/tournaments и /matches/{yearMonth}/calendar — границы дня/месяца в фильтрах date, date_from/date_to, в дефолтной выборке «матчи на сегодня» и в календарных агрегациях считаются в указанной таймзоне. Без параметра — Europe/Moscow, как раньше. Поля выдачи (например, dateEvent) не меняются.

v2.0.20​

Текстовый поиск матчей​

  • Параметр q= в GET /v2/{sport}/matches — поиск матчей по названиям команд и турнира на русском или английском (в теннисе/настольном теннисе — включая участников пар). Устойчив к опечаткам и частичному вводу: ?q=реаль мадрид, ?q=real madr.
    • результаты отсортированы по релевантности; при равной релевантности выше матчи, ближайшие к текущему моменту (ближайшая и недавние встречи — раньше матчей далёкого прошлого); явный sort=asc|desc переключает на сортировку по времени начала;
    • limit — размер ответа в режиме поиска (1–50, по умолчанию 20); page/page_size игнорируются;
    • сочетается с остальными фильтрами списка (status, tournament_id, season_id, category_ids, team_id, team_id_1/team_id_2, round, exclude_amateur, has_bk_odds, date, date_from/date_to), при этом диапазон дат в режиме поиска не ограничен 31 днём;
    • форма ответа прежняя — {totalMatches, matches}, элементы поддерживают fields=/view= и with_bk_odds.

v2.0.19​

Текущая таблица турнира​

  • Новый эндпоинт GET /v2/{sport}/tournament/{tournamentId}/standings — шорткат «актуальная турнирная таблица» без ручного перебора сезонов: сезоны просматриваются от новейшего к старым, отдаётся таблица первого сезона с непустыми standings (свежий сезон ещё без таблиц пропускается автоматически). В ответе — бриф турнира, сезон (с признаком isCurrent) и таблицы в том же формате StandingsTable, что и в деталях сезона. Для кубковых турниров без таблиц — 404 конвертом.

Турнир: титулы, лучший игрок, цвета​

Аддитивные поля в GET /v2/{sport}/tournament/{tournamentId} (а также в /tournaments и /search — форматтер общий):

  • titleHolder + titleHolderTitles — действующий обладатель титула (компактная карточка команды) и число его титулов;
  • mostTitles + mostTitlesTeams — рекорд по титулам и команды-рекордсмены;
  • playerOfTheTournament — лучший игрок турнира (компактная карточка), где данные доступны;
  • colors — фирменные цвета турнира (primary/secondary);
  • элементы linkedTournaments / upperDivisions / lowerDivisions теперь содержат помимо id/name ещё slug, translations, image, colors и категорию (страну/регион) — прежние поля не менялись.

Сводка сезона​

  • Поле info в GET /v2/{sport}/tournament/{tournamentId}/seasons/{seasonId} — агрегированные показатели сезона: голы, победы хозяев/гостей, ничьи, карточки, число участников, страны-хозяйки и команды-новички (компактные карточки с переводами). Состав показателей зависит от вида спорта и типа турнира; null — данных нет.

v2.0.18​

Матчи игрока​

  • Новый эндпоинт GET /v2/{sport}/players/{playerId}/matches — последние завершённые матчи игрока, новые сначала (история результатов + персональная статистика для прогнозов на игроков / player props):
    • по умолчанию — все матчи, где игрок выходил в составе, независимо от команды: клубные и за сборную (например, свежие матчи чемпионата мира попадут в историю игрока клуба); каждый такой элемент — played=true;
    • в каждом элементе: компактная карточка матча (турнир, сезон, раунд, команды с переводами, счёт, исход) + участие игрока: позиция, номер, капитанство, выход на замену и плоский объект показателей statistics (ключи и переводы — в словаре статистики);
    • командный режим — team_id=<id> (конкретная команда) или current_team=true (текущий клуб игрока): все последние матчи этой команды, включая те, где игрок не выходил (played=false, statistics=null); фильтр played_only=true оставляет только сыгранные;
    • limit (1–20, по умолчанию 10), фильтры tournament_id= и season_id=;
    • персональная статистика в составах доступна для football, ice-hockey и basketball; для видов спорта без составов (теннис, настольный теннис, волейбол, киберспорт) используйте командный режим — история матчей команды/пары игрока с played=false.

Профиль игрока: рыночный блок и позиции​

Аддитивные поля в GET /v2/{sport}/players/{playerId}/profile:

  • market — оценочная трансферная стоимость (proposedMarketValue + proposedMarketValueRaw с валютой) и срок контракта contractUntilTimestamp (миллисекунды); null — данных нет;
  • preferredFoot — рабочая нога (football);
  • positionsDetailed — детализированные коды позиций игрока, например ["LW", "RW"] (football).

v2.0.17​

Командные эндпоинты: профиль, форма, состав, трансферы, турниры​

Пять новых эндпоинтов раскрывают данные команды, которые раньше не отдавались через API:

  • GET /v2/{sport}/teams/{teamId}/profile — расширенный профиль команды: главный тренер, домашний стадион (город, вместимость), фирменные цвета, дата основания, основной турнир. Для тенниса и настольного тенниса («команда» = спортсмен) — дополнительно ranking (позиция в официальном рейтинге ATP/WTA) и блок playerTeamInfo (стиль игры, призовые, антропометрия, текущий рейтинг).
  • GET /v2/{sport}/teams/{teamId}/form?limit=5 — форма команды по последним завершённым матчам (до 10): последовательность W/D/L, счётчики побед/ничьих/поражений и матчи с соперником и счётом. Счёт — с позиции команды («голы команды:голы соперника»). Парные матчи (теннис/настольный теннис) учитываются: команда ищется и среди участников пар.
  • GET /v2/{sport}/teams/{teamId}/squad — состав команды: карточки игроков (позиция, номер, дата рождения, рост), отдельные списки легионеров и сборников, а также тренерский штаб — эти данные доступны только здесь.
  • GET /v2/{sport}/teams/{teamId}/transfers — переходы игроков команды (transfersIn/transfersOut): карточка игрока, команды «откуда»/«куда», тип перехода с переводами (трансфер, аренда, свободный агент, ...), сумма и дата. Аналог истории переходов в профиле игрока — в разрезе команды.
  • GET /v2/{sport}/teams/{teamId}/tournaments — турниры, в которых участвует команда, с категорией (страна/регион) и фирменными цветами.

Все ответы включают русские переводы имён и названий; таймстемпы — в миллисекундах; ошибки — в конверте {code, error, message}.

v2.0.16​

Лидерборды сезона​

  • Новый эндпоинт GET /v2/{sport}/tournament/{tournamentId}/seasons/{seasonId}/leaders — лидерборд сезона по любому показателю сезонной статистики: бомбардиры (sort_by=goals), ассистенты, рейтинг, сэйвы, xG и ещё сотни ключей (словарь — /v2/SeasonStatisticsDict.json, см. Сезонная статистика).
    • entity=players|teams — лидеры среди игроков (по умолчанию) или команд;
    • sort_by=<ключ> (обязателен), order=desc|asc, limit (≤100), offset (≤500) — пагинация глубоких лидербордов;
    • stats=<csv> — какие показатели вернуть в строках (по умолчанию все), type= — разрез сезона (overall, regularSeason, home, ...);
    • в строках — краткие карточки игрока/команды с переводами и rank с учётом смещения.
  • Доступность: игроки — football, basketball, ice-hockey, volleyball; команды — те же + tennis (команда = игрок).

Очные встречи (H2H)​

  • Новый эндпоинт GET /v2/{sport}/h2h?team_id_1=&team_id_2= — готовая сводка head-to-head двух команд:
    • summary — счёт побед/ничьих по последним очным встречам (окно до 50 матчей): team1Wins/team2Wins привязаны к порядку параметров и учитывают фактическую сторону команды в каждом матче;
    • matches — последние завершённые очные встречи (новые сначала, limit до 50) в компактной форме lite (настраивается fields/view, поддерживает with_bk_odds);
    • работает и для парных матчей (теннис/настольный теннис): участники ищутся внутри пар.
  • «Сырой» список очных встреч со всеми фильтрами по-прежнему доступен через GET /v2/{sport}/matches?team_id_1=&team_id_2= — описания параметров теперь ссылаются на /h2h и обратно.

WebSocket: коэффициенты букмекеров в реальном времени (opt-in)​

  • Новый параметр подписки withBkOdds: true (в subscribe-сообщении, для type: "match" и type: "sport") — включает коэффициенты букмекеров в поток. Подписка без флага работает ровно как раньше — существующие интеграции ничего не заметят.
  • С флагом match_snapshot включает oddsBk — коэффициенты всех подключённых букмекеров (melbet, pari, marathon), как REST-ответ матча по ID с with_bk_odds=true.
  • С флагом приходят дельты коэффициентов: при изменении кэфов у букмекера — match_delta с блоком changes.updated.oddsBk.<bookmaker> целиком. Дельта отправляется только при реальном изменении значений — сравниваются сами кэфы/рынки, а не таймстемпы фида.
  • ⚠️ Блок oddsBk.<bookmaker> применяется заменой целиком, не deep-merge (рынок может исчезнуть из блока при закрытии линии) — см. Snapshot vs Delta.
  • Повторный subscribe на тот же топик с другим withBkOdds обновляет флаг без переподписки. REST-выдача не менялась.

v2.0.15​

Матч-аналитика, live-эндпоинт, диапазоны дат и лёгкие ответы​

  • Новые поля матча (в ответе матча по ID):
    • pregame — предматчевый контекст: очные встречи (h2h.teamDuel/h2h.managerDuel), активные серии команд (teamStreaks.general/teamStreaks.head2head, например «No losses: 4», «Both teams scoring: 6/7») и форма команд (form — позиция в таблице, последние результаты W/D/L, средний рейтинг);
    • bestPlayers — лучшие игроки матча с показателями (playerOfTheMatch, home[], away[]) — football, ice-hockey, basketball;
    • attendance — посещаемость матча; winner/winnerCode — исход матча (home/away/draw) — во всех ответах матчей.
  • Новые эндпоинты матч-аналитики:
    • GET /v2/{sport}/matches/{matchId}/shotmap — карта ударов: xG/xGOT каждого удара, координаты, часть тела, игровая ситуация (football); координаты и типы бросков (ice-hockey);
    • GET /v2/{sport}/matches/{matchId}/momentum — график давления по минутам (football, basketball, ice-hockey) или по геймам с отметками брейков (tennis);
    • GET /v2/{sport}/matches/{matchId}/average-positions — средние позиции игроков на поле + замены.
  • Новый эндпоинт GET /v2/{sport}/matches/live — все идущие сейчас матчи вида спорта одним запросом (REST-альтернатива WebSocket; удобно для ботов).
  • Новый эндпоинт GET /v2/{sport}/teams/{teamId}/matches?last=5&next=5 — последние и ближайшие матчи команды одним запросом; поддерживает tournament_id, fields/view, with_pregame, with_bk_odds.
  • Новые параметры списка матчей GET /v2/{sport}/matches:
    • date_from+date_to — диапазон дат до 31 дня (раньше — только один день);
    • status теперь принимает несколько значений через запятую (например inprogress,finished);
    • sort=asc|desc — порядок по времени начала (asc — «ближайшие сначала»);
    • round — матчи конкретного тура (вместе с tournament_id/season_id);
    • fields — выбор полей ответа (лёгкие списки: меньше трафика, быстрее ответы);
    • view=lite|odds — готовые пресеты: компактный матч / компактный матч с коэффициентами (массовая выгрузка коэффициентов за день одним запросом);
    • with_pregame=true — блок pregame каждому матчу списка (контекст всех матчей дня одним запросом — удобно для аналитики и прогнозов).
  • Задокументированы существовавшие возможности: параметры team_id_1+team_id_2 (очные встречи двух команд в /matches) и статический словарь /v2/BkOddsDict.json.
  • Исправление: списки матчей теперь единообразно включают liveEvents у всех элементов (раньше поле отсутствовало у части элементов). В будущем релизе события планируется убрать из списков (останутся в матче по ID и /events) — следите за changelog.

v2.0.14​

One-shot эндпоинты последней статистики​

  • Новые эндпоинты GET /v2/{sport}/players/{playerId}/statistics/latest и GET /v2/{sport}/teams/{teamId}/statistics/latest — последняя актуальная сезонная статистика одним запросом, без предварительного запроса списка сезонов: турнир — первый по релевантности (или ?tournament_id=), сезон — новейший с уже собранными данными (с автоматическим откатом к предыдущему в начале сезона), тип — автоматически overall → regularSeason → mainDraw → первый доступный (или ?type= — тогда последний сезон, где этот тип есть).
  • Показатели — плоским объектом statistics; выбранные турнир/сезон/тип видны в полях tournament/season/type/availableTypes; у игроков — команда сезона и highlighted-ранги.
  • Подробнее — Сезонная статистика → Быстрый доступ.

v2.0.13​

Сезонная статистика игроков и команд + профиль игрока​

  • Новые эндпоинты сезонной статистики — агрегированные показатели за сезон турнира:
    • GET /v2/{sport}/players/{playerId}/statistics/seasons и GET /v2/{sport}/teams/{teamId}/statistics/seasons — список турниров/сезонов с доступными типами статистики;
    • GET /v2/{sport}/players/{playerId}/statistics?tournament_id=&season_id=[&type=] и GET /v2/{sport}/teams/{teamId}/statistics?... — сами показатели по типам (overall, regularSeason, playoffs, home, away, mainDraw, …), с highlighted-рангами показателей в турнире и командой игрока в контексте сезона.
  • Доступность: игроки — football, basketball, ice-hockey, volleyball (volleyball — в основном крупные международные турниры); команды — football, basketball, ice-hockey, tennis, volleyball (в теннисе команда = игрок; volleyball — в основном сборные). У esports и table-tennis сезонной статистики нет.
  • Новый статический эндпоинт /v2/SeasonStatisticsDict.json — словарь ~470 ключей сезонной статистики с переводами (RU/ES) и тематическими группами; не требует авторизации. Ключи совпадают буква-в-букву с объектом statistics ответов.
  • Новый эндпоинт GET /v2/{sport}/players/{playerId}/profile — профиль игрока: характеристики (сильные/слабые стороны, football), атрибуты по годам (football), статистика за сборную (football), история трансферов с расшифрованными типами (football, basketball).
  • Новое поле hasSeasonStatistics в объектах Player (/players) и Team (/teams) — есть ли у сущности сезонная статистика.
  • Новая страница Сезонная статистика — описание эндпоинтов, типов статистики, доступности по видам спорта и интерактивный справочник ключей.

v2.0.12​

Новый букмекер Marathon (oddsBk)​

  • Добавлен третий букмекер — Marathon (Марафон) (slug marathon) в oddsBk и hasBkOdds. Параметр bookmaker_ids теперь принимает melbet, pari, marathon (через запятую).
  • Match.hasBkOdds теперь включает ключ marathon: { "melbet": true|false, "pari": true|false, "marathon": true|false }. Наличие коэффициентов у букмекеров независимо.
  • Match.oddsBk может содержать ключ marathon с теми же схемами (BookmakerOddsData / BkOddsMarket / BkOddsStake / BkOddsLine), что и melbet/pari, — единые слаги рынков и исходов (result → w1/x/w2, total → over/under, handicap → handicap_1/handicap_2, double_chance → 1x/12/x2).
  • Marathon доступен для всех семи видов спорта — football, ice-hockey, basketball, tennis, table-tennis, volleyball, esports (включая настольный теннис, который Pari не поддерживает). Набор рынков (зависит от вида спорта): исход, двойной шанс, фора, тотал, индивидуальные тоталы команд, «обе забьют», тотал чёт/нечёт.
  • Уточнение имени рынка result: для трёхисходного варианта (1×2, с ничьей) имя теперь «Исход» / "Result"; вариант «Исход (2 исхода)» / "Result (2 way)" остаётся только для видов без ничьей. Слаги и структура ответа не изменились; применимо к Marathon и Pari.
  • Подробнее — Concepts → Bookmaker Odds.

v2.0.11​

Словарь статистики матча и игроков​

  • Новый статический эндпоинт /v2/StatisticsDict.json — словарь ключей статистики матча и игроков для всех видов спорта с переводами на русский и испанский. Не требует авторизации; удобно подгрузить один раз и кэшировать.
  • Документированы Match.matchStatistics (новые схемы MatchStatisticsPeriod / MatchStatisticsGroup / MatchStatisticsItem) и lineup.players[].statistics (индивидуальная статистика игрока в матче — для football, ice-hockey, basketball). Сама выдача не изменилась — оба поля и раньше отдавались «как есть», теперь у них есть схема и словарь.
  • Новая страница Словарь статистики — поиск по ключам с названиями и переводами (RU/ES), отдельно командная статистика и статистика игроков, по каждому виду спорта. В хоккее часть ключей записана с заглавной буквы (Shots, Hits, …) — сопоставляйте с учётом регистра.

v2.0.10​

Новый букмекер Pari (oddsBk)​

  • Добавлен второй букмекер — Pari (slug pari) в oddsBk и hasBkOdds. Параметр bookmaker_ids теперь принимает melbet, pari (через запятую).
  • Match.hasBkOdds теперь включает ключ pari: { "melbet": true|false, "pari": true|false }. Наличие коэффициентов у букмекеров независимо.
  • Match.oddsBk может содержать ключ pari с теми же схемами (BookmakerOddsData / BkOddsMarket / BkOddsStake / BkOddsLine), что и melbet. Оба букмекера используют единые слаги рынков и исходов (result → w1/x/w2, total → over/under, handicap → handicap_1/handicap_2, double_chance → 1x/12/x2).
  • Pari доступен для football, ice-hockey, basketball, tennis, volleyball, esports (настольный теннис не поддерживается); рынки — исход, двойной шанс, фора, тотал.
  • Подробнее — Concepts → Bookmaker Odds.

v2.0.9​

Составы (lineups)​

  • Новое поле lineup.missingPlayers — травмы и дисквалификации (отсутствующие игроки). Каждый элемент: player (id, имя, позиция, игровой номер, translations.ru, изображение), type (missing / doubtful), reason (код + кодовое имя + RU/ES), description (уточнение причины с RU/ES, либо null) и expectedEndDateMs (дата возвращения, либо null). Доступно для командных видов с составами: football, ice-hockey, basketball, volleyball; карточные причины (коды 11/12/13) — только для футбола.
  • Новая схема: MissingPlayer. Полный справочник причин и уточнений — Словарь причин.

Детали сезона: турнирные таблицы и сетки плей-офф​

  • Эндпоинт GET /v2/{sportSlug}/tournament/{tournamentId}/seasons/{seasonId} теперь возвращает расширенный объект SeasonDetails (раньше — краткий Season). Список сезонов и вложенный Season в Tournament остаются краткими.
  • Новое поле SeasonDetails.standings — турнирные таблицы: массив таблиц (лига или группы); строка содержит расширенный объект команды (id, name, shortName, image, country, teamColors, translations.ru), position, сыгранные/победы/ничьи/поражения, забито/пропущено, goalDifference + сырой scoreDiffFormatted, points, promotion. Доступно во всех видах спорта; пусто, если у сезона нет таблиц.
  • Новое поле SeasonDetails.cupTrees — сетки плей-офф: дерево → раунды → пары (ties) → участники, с матчами [{ id, leg }], перенумерованными blockId, счётом/пенальти и пометкой матча за 3-е место. Доступно во всех видах спорта; пусто, если у сезона нет плей-офф.
  • Новые схемы: SeasonDetails, StandingsTable, StandingsRow, StandingsTeam, Promotion, TeamColors, CupTree, CupTreeRound, CupTreeTie, CupTreeParticipant, CupTeam.
  • Подробнее — Concepts → Структура данных, API Reference → Детали сезона.

Документация и портал разработчика​

  • Новый портал разработчика на docs.api-sport.ru.
  • Спецификация OpenAPI обновлена до 3.1.0 (с 3.0.3) — корректные null-типы и описания рядом с $ref.
  • Метаданные x-sports на свойствах схем — указывают, для каких видов спорта применимо поле; их использует Sport Schema Explorer.
  • Sport Schema Explorer — интерактивное дерево полей Match / SeasonDetails / Team / Player с переключателем по 7 видам спорта (подсветка спорт-специфичных полей). См. Структура данных.

v2.0.8​

Букмекерские коэффициенты (Bookmaker Odds)​

  • Новый query-параметр has_bk_odds=true на /v2/{sportSlug}/matches — фильтр: оставить только матчи с букмекерскими коэффициентами. Можно комбинировать с bookmaker_ids.
  • Новый query-параметр with_bk_odds=true на /v2/{sportSlug}/matches и /v2/{sportSlug}/matches/{matchId} — добавляет в Match поле oddsBk с детальными рынками и исходами.
  • Новый query-параметр bookmaker_ids (CSV, доступно: melbet) — фильтрует букмекерские данные по указанным букмекерам. Применяется к has_bk_odds и/или with_bk_odds.
  • Новое поле Match.hasBkOdds — { "melbet": true|false }. Присутствует всегда в ответе матча.
  • Новое поле Match.oddsBk — детальная структура с рынками, исходами, линиями, аргументами. Присутствует только при with_bk_odds=true.
  • Новые схемы: BookmakerOdds, BookmakerOddsData, BkOddsMarket, BkOddsStake, BkOddsLine, BkTranslatedName. Подробнее — Concepts → Bookmaker Odds.

v2.0.7​

Переводы (Русский язык)​

  • Переведено на русский ≈99 % имён игроков, команд, турниров, сезонов, менеджеров, мест проведения и городов (поле translations.ru / translation.ru у соответствующих сущностей). Точечные корректировки добавляются по мере необходимости.

Календарь матчей​

  • Новый эндпоинт /v2/{sportSlug}/matches/{yearMonth}/calendar (operationId: getCalendarByMonth) — сводка по дням за месяц.
    • Параметры: yearMonth (path, YYYY-MM), exclude_amateur, tournament_id, season_id, category_ids, team_id.
    • Ответ: { month, totalDays, days: [{ date, totalTournaments, totalMatches }] }. Возвращает все дни месяца, включая пустые с нулями. Один агрегационный запрос.
    • Рецепт — Recipes → Календарь за месяц.

Расширение /matches/{date}/tournaments​

  • В эндпоинт getTournamentsByDate добавлены query-параметры tournament_id, season_id, category_ids, team_id — фильтрация агрегации турниров.

Полнотекстовый поиск​

  • Новый эндпоинт /v2/{sportSlug}/search (operationId: search) — мультиисточник по players / teams / tournaments в одном запросе.
    • Параметры: q (required, мин. 1 символ), type (CSV из player,team,tournament), limit (1–50, default 20), offset (0–500, default 0), country (ISO Alpha-2).
    • Ответ: SearchResponse с группами players, teams, tournaments (SearchResultGroup { total, items[] }).
    • Особенности: мультиязычность (en + ru), ранжирование по популярности, prefix matching.
    • Подробнее — Concepts → Search, Recipes → Search.
  • Новый параметр q в существующих списках /players, /teams, /tournaments — полнотекстовый поиск в рамках одного типа сущности с тем же limit/offset.
  • Новый эндпоинт /v2/{sportSlug}/tournaments (operationId: getTournaments) — список турниров с фильтрами q / ids, limit, offset. Ответ: { totalTournaments, tournaments[] }.

v2.0.6​

Расширенные данные для тенниса​

  • Новый sport-specific объект Match.tennis: TennisData для tennis-матчей в /v2/{sportSlug}/matches и /v2/{sportSlug}/matches/{matchId}.
    • bestOf (3 или 5), groundType (Hardcourt outdoor, Hardcourt indoor, Clay, Grass), firstToServe (home/away), homePlayerSeed/awayPlayerSeed.
    • sets[] — по каждому сету: setNumber, homeGames, awayGames, winner, durationSeconds, tiebreak (если был — { homePoints, awayPoints }).
    • momentum[] — momentum-график по геймам: set, game, value (-100..+100), breakOccurred.
    • pointByPoint[] — только при запросе одного матча (getMatchById). Каждый розыгрыш: тип (ace, doubleFault, winner, loser, error), сервер, счёт в гейме (0/15/30/40/A).
    • Схемы: TennisData, TennisSet, TennisTiebreak, TennisMomentumItem, TennisPointByPointSet, TennisGame, TennisGameScore, TennisPoint.
  • Новое поле Score.point — текущее очко в теннисном гейме live-матча: "0", "15", "30", "40", "A".
  • Подробнее — Sport-specific → Tennis.

v2.0.5​

Расширенные данные для киберспорта​

  • Новый sport-specific объект Match.esports: EsportsData для esports-матчей в /v2/{sportSlug}/matches и /v2/{sportSlug}/matches/{matchId}.
  • Поддерживаемые дисциплины: CS2 (Counter-Strike 2), Dota 2, League of Legends.
  • esports содержит:
    • bestOf — формат серии.
    • games[] — массив игр серии. По каждой игре: счёт, статус, длительность, карта (CS2), homeTeamStartingSide (T/CT для CS2, Radiant/Dire для Dota 2, Blue/Red для LoL), индивидуальная статистика игроков (KDA, ADR, KAST, headshots — CS2; goldPerMin, xpPerMin, denies, lastHits, netWorth, heroLevel — Dota 2; goldEarned, level, minionsKilled, role — LoL), играемые герои/чемпионы, забаненные герои/чемпионы (Dota 2 / LoL), детализация раундов (CS2: T/CT, исход elimination/defuse/explosion/timeout).
    • Командная статистика: towers/barracks (Dota 2), dragons/inhibitors/baron (LoL), firstBlood.
  • Схемы: EsportsData, EsportsGame, EsportsPlayer, EsportsTeamStatistics, EsportsRounds, EsportsRound, EsportsBans, EsportsCharacter.
  • Подробнее — Sport-specific → Esports.

v2.0.4​

Турниры по дате​

  • Новый эндпоинт /v2/{sportSlug}/matches/{date}/tournaments (operationId: getTournamentsByDate) — список уникальных турниров за дату с количеством матчей и statusBreakdown по всем девяти статусам матча (notstarted, inprogress, finished, canceled, postponed, interrupted, suspended, delayed, willcontinue).

Новые параметры фильтрации​

  • exclude_amateur=true на /v2/{sportSlug}/matches и /v2/{sportSlug}/matches/{date}/tournaments — скрывает любительские матчи и низшие лиги. Рекомендуется включать по умолчанию. В одной из будущих версий планируется сделать значением по умолчанию.
  • page и page_size на /v2/{sportSlug}/matches — offset-based пагинация. page 1–100, page_size 1–500. Если параметры не переданы — поведение не меняется (обратная совместимость, до 6000 матчей streaming-режимом). Подробнее — Concepts → Pagination.

v2.0.3​

Новый вид спорта​

  • 🏐 Волейбол (sportSlug: volleyball). Базовая структура Match без отдельного sport-specific объекта; sport-specific поля будут добавляться со временем.

WebSocket API​

  • Запущен WebSocket-канал для real-time обновлений матчей.
  • URL: wss://ws.api.api-sport.ru.
  • Авторизация — через query-параметр ?apiKey=.
  • Поддерживаются подписки на весь спорт (sport:{sportSlug}) и на отдельный матч (match:{sportSlug}:{matchId}).
  • Сообщения: connected, subscribed, unsubscribed, match_snapshot, match_delta (поле changes с added / updated / flatChanges), pong, error.
  • Схемы: WebSocketSubscribeMessage, WebSocketUnsubscribeMessage, WebSocketPingMessage, WebSocketConnectedResponse, WebSocketSubscribedResponse, WebSocketMatchSnapshotResponse, WebSocketMatchDeltaResponse, WebSocketErrorResponse.
  • Подробнее — WebSocket → Overview.

v2.0.2​

Match.referee​

  • Новое поле Match.referee — арбитр матча (имя, страна, статистика жёлтых/красных/жёлто-красных карточек и количество судейских матчей в сезоне).
  • На данный момент данные есть только для football; для других видов спорта поле может быть пустым. В будущем планируется расширение на другие виды.
  • Схема: Referee.

v2.0.1​

Live-данные матча​

  • Новое поле Match.currentMatchMinute — текущая минута live-матча.
  • Новое поле Match.liveEvents в /v2/{sportSlug}/matches/{matchId} — массив live-событий матча (голы, карточки, замены, пенальти, VAR-решения и т. д.).
  • Новое поле Match.matchStatistics в /v2/{sportSlug}/matches и /v2/{sportSlug}/matches/{matchId} — массив групп статистики (для футбола — наиболее богатый набор: ballPossession, totalShotsOnGoal, cornerKicks, fouls, и т. д.).

Фильтрация по нескольким турнирам​

  • tournament_id в /v2/{sportSlug}/matches теперь принимает CSV-список ID турниров (tournament_id=7,17,23), а не одно значение.

v2.0.0​

Базовая платформа​

  • defaultTournaments — поле в ответе эндпоинтов /v2/{sportSlug}/categories и /v2/{sportSlug}/categories/{categoryId} (рядом с categories; это не поле Match). Объект { ru: DefaultTournament[], en: DefaultTournament[] } для отображения популярных турниров пользователю. Схемы: DefaultTournament, DefaultTournaments.
  • Match.oddsBase — базовые рынки коэффициентов (1×2, тотал голов, азиатский гандикап и др.) с текущими и начальными коэффициентами, направлением изменения и статусом рынка. Схемы: OddsMarket, OddsChoice.
  • Match.highlights — массив видеохайлайтов матча: title, url (обычно YouTube), image (превью). Схема: Highlight.

Это канонический список изменений API. По фактам API (схемы, поля, параметры) источник правды — OpenAPI-спецификация.

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