Сезонная статистика игроков и команд

Сезонная статистика — агрегированные показатели игрока или команды за сезон турнира (голы, передачи, xG, проценты бросков, вбрасывания и т.д.). Получение — в два шага:

Список сезонов — какие турниры/сезоны и какие типы статистики доступны сущности:
- GET /v2/{sport}/players/{playerId}/statistics/seasons
- GET /v2/{sport}/teams/{teamId}/statistics/seasons
Статистика сезона — сами показатели по выбранному турниру и сезону:
- GET /v2/{sport}/players/{playerId}/statistics?tournament_id={id}&season_id={id}[&type={type}]
- GET /v2/{sport}/teams/{teamId}/statistics?tournament_id={id}&season_id={id}[&type={type}]

Без параметра type возвращаются все доступные типы сезона; с параметром — только указанный (если его нет, придёт 404 со списком availableTypes).

Быстрый доступ: /statistics/latest

Если нужна просто «текущая статистика» — есть one-shot эндпоинт без предварительного запроса списка сезонов:

GET /v2/{sport}/players/{playerId}/statistics/latest
GET /v2/{sport}/teams/{teamId}/statistics/latest

Что он возвращает:

Турнир — первый по релевантности (главная лига: НБА, НХЛ и т.п.); можно ограничить параметром ?tournament_id={id}.
Сезон — новейший, за который уже собраны данные. Если сезон только начался и цифр ещё нет, вернётся предыдущий сезон (а без tournament_id — при пустом турнире следующий по списку).
Тип — один «основной», выбирается автоматически: overall → regularSeason → mainDraw → первый доступный. Параметр ?type={type} переопределяет выбор — тогда вернётся последний сезон, где этот тип есть (например, ?type=playoffs — последние цифры плей-офф).

Показатели приходят плоским объектом statistics, а фактически выбранные турнир/сезон/тип всегда видны в ответе (tournament, season, type, availableTypes):

{
  "player": { "id": 861608, "name": "Luka Dončić", "translations": { "ru": "Лука Дончич" }, "image": "…" },
  "tournament": { "id": 132, "name": "NBA", "translations": { "ru": "НБА" }, "image": "…" },
  "season": { "id": 76986, "name": "NBA 25/26", "year": "25/26", "translations": { "ru": null } },
  "type": "regularSeason",
  "availableTypes": ["regularSeason", "playoffs"],
  "team": { "id": 3427, "name": "Los Angeles Lakers", "translations": { "ru": "Лос-Анджелес Лейкерс" }, "image": "…" },
  "highlighted": { "points": { "value": 52, "rankTotal": 63, "rankPerGame": 17 } },
  "statistics": { "appearances": 50, "points": 1620, "assists": 430, "fieldGoalsPercentage": 48.9 },
  "updatedAt": 1751600000000
}

Почему нет «объединения» типов

Проценты и средние (fieldGoalsPercentage, rating, plusMinus) математически не складываются между разрезами. Там, где объединённый вид существует, источник отдаёт его сам — это тип overall, и именно он выбирается первым приоритетом.

Типы статистики

Один сезон может иметь несколько разрезов статистики. Множество значений открытое и зависит от турнира; наблюдаемые значения:

type	Что это
`overall`	Весь сезон целиком
`regularSeason`	Регулярный сезон (лиги с плей-офф: НБА, НХЛ, …)
`playoffs`	Плей-офф
`home` / `away`	Домашние / гостевые матчи
`mainDraw`	Основная сетка (теннис)
`top16`	Топ-16 (евробаскет и т.п.)

Доступность по видам спорта

Спорт	Игроки	Команды
football	✅	✅
basketball	✅	✅
ice-hockey	✅	✅
tennis	— (см. примечание)	✅
volleyball	✅ в основном крупные международные турниры	✅ в основном сборные
table-tennis	—	—
esports	—	—

Теннис и настольный теннис

В теннисе и настольном теннисе «команда» — это игрок (или пара), поэтому сезонная статистика теннисистов доступна через командные эндпоинты /teams/{teamId}/statistics*.

Быстро понять, есть ли у сущности статистика, можно по флагу hasSeasonStatistics в ответах /players и /teams. Список /statistics/seasons при отсутствии данных возвращает 200 с totalTournaments: 0.

Формат ответа

Показатели отдаются «как есть» (raw) плоским объектом ключ → число внутри блока каждого типа:

{
  "player": { "id": 861608, "name": "Luka Dončić", "translations": { "ru": "Лука Дончич" }, "image": "…" },
  "tournament": { "id": 132, "name": "NBA", "translations": { "ru": "НБА" }, "image": "…" },
  "season": { "id": 76986, "name": "NBA 25/26", "year": "25/26", "translations": { "ru": null } },
  "types": ["regularSeason", "playoffs"],
  "statistics": {
    "regularSeason": {
      "team": { "id": 3427, "name": "Los Angeles Lakers", "translations": { "ru": "Лос-Анджелес Лейкерс" }, "image": "…" },
      "highlighted": { "points": { "value": 52, "rankTotal": 63, "rankPerGame": 17 } },
      "statistics": { "appearances": 50, "points": 1620, "assists": 430, "fieldGoalsPercentage": 48.9 }
    }
  },
  "updatedAt": 1751600000000
}

statistics.<type>.team — команда, за которую игрок выступал в этом сезоне (только у игроков).
highlighted — ключевые показатели с местом в турнире (rankTotal, rankPerGame), когда доступны.
updatedAt — время обновления данных (Unix, миллисекунды).
Данные обновляются по завершении матчей; свежесобранный сезон может появиться в списке чуть раньше, чем его статистика (кратковременный 404 — повторите запрос позже).

Профиль игрока

Дополнительные данные игрока — GET /v2/{sport}/players/{playerId}/profile:

characteristics — сильные/слабые стороны и позиции (football);
attributeOverviews — атрибуты (нападение/техника/тактика/оборона/креативность) по годам (football);
nationalTeamStatistics — матчи/голы за сборную и дата дебюта (football);
transferHistory — история переходов с типом, суммой и датами (football, basketball).

Числовые коды характеристик и типов переходов приходят уже расшифрованными (name + translations.ru/es). Блоки, недоступные для вида спорта, отдаются null или пустым массивом.

Словарь ключей

Названия, переводы (RU/ES) и тематические группы всех ключей — в статическом словаре https://api.api-sport.ru/v2/SeasonStatisticsDict.json (не требует авторизации). Ключи словаря совпадают буква-в-букву с ключами объекта statistics. Словарь пополняется по мере появления новых показателей: ключ, которого ещё нет в словаре, отображайте по его английскому имени.

curl https://api.api-sport.ru/v2/SeasonStatisticsDict.json

Справочник показателей