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

Changelog

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

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-спецификация.

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