---
id: live-statistics
title: 'Модель данных: статистика матча'
description: Описание структуры Live-статистики матча, включая атаки, владение мячом, удары и другие показатели.
version: v1
language: ru
---

# Модель данных: статистика матча


## Что находится в `stat_list`

Поле `stat_list` содержит фактические показатели матча: атаки, владение мячом, удары,
карточки, угловые и другие доступные данные.

`stat_list` предоставляет только основные текущие показатели Live-матча. Это не
подробная статистика для расширенного анализа команд, игроков и турниров.

Статистика не является списком ставок и не содержит коэффициентов. Доступные ставки
на статистические события находятся отдельно в `game_oc_list` или в субматчах из
`sub_games`.

```text
stat_list    → фактические показатели матча
game_oc_list → группы ставок и коэффициенты
sub_games    → ссылки на дополнительные матчи и рынки
```

## Границы статистики Sport Line API

Sport Line API передаёт краткую статистику, необходимую для отображения основных
показателей матча во время Live. В зависимости от доступности данных это могут быть:

- атаки и опасные атаки;
- владение мячом;
- удары;
- угловые;
- карточки;
- xG;
- другие основные показатели, фактически полученные в `stat_list`.

Sport Line API не предоставляет через `stat_list` подробную статистику для максимальной
аналитики. Здесь нет полного набора данных, включающего:

- подробную историю событий матча;
- расширенный анализ команд;
- статистику и анализ игроков;
- личные встречи команд — H2H;
- историю предыдущих матчей команд;
- будущие матчи и расписание команд;
- другие расширенные аналитические данные.

Для таких данных создаётся отдельный API подробной спортивной статистики. Сейчас этот
API находится в разработке и не является частью Sport Line API.

Поэтому `stat_list` следует использовать как краткую Live-статистику текущего матча, а
не как источник полной истории или расширенной спортивной аналитики.

## В каких методах возвращается статистика

Статистика предоставляется только для Live-матчей и только в двух случаях:

| Метод | Что возвращается |
|---|---|
| [`events`](../api-reference/events.md) с типом `live` | Основная статистика внутри каждого матча в списке |
| [`event`](../api-reference/event.md) с типом `live` | Основная статистика конкретного матча |

В Prematch статистика не предоставляется. Другие методы Sport Line API не следует
использовать для её получения. Если в техническом объекте встречается пустое поле
`stat_list: []`, оно не означает наличие статистики.

Наличие матча в Live не гарантирует наличие статистики. В сохранённом списке Live
статистика была заполнена у 16 из 39 матчей. Это значение относится только к моменту
получения примера и не является постоянной долей покрытия.

## Структура `stat_list`

`stat_list` — массив объектов статистических показателей:

```text
матч
└── stat_list[]
    └── показатель статистики
        ├── id
        ├── name
        ├── opp1
        └── opp2
```

| Поле | Тип | Описание |
|---|---|---|
| `id` | number | Технический ID показателя статистики |
| `name` | string | Название показателя на языке запроса |
| `opp1` | string | Значение первой команды или участника |
| `opp2` | string | Значение второй команды или участника |

В проверенных ответах дополнительные поля внутри объектов `stat_list` не встречались.

## Соответствие команд

Значения статистики относятся к сторонам матча:

| Статистика | Команда или участник матча |
|---|---|
| `opp1` | `opp_1_name`, идентификатор — `opp_1_id` |
| `opp2` | `opp_2_name`, идентификатор — `opp_2_id` |

Не определяйте сторону по положению команды в интерфейсе. Если команды визуально
переставляются местами, значения статистики нужно переставлять вместе с ними.

## Пример статистики Live-матча

Фрагмент сохранённого ответа матча `746146992`:

```json
{
  "stat_list": [
    {
      "id": 93,
      "name": "xG",
      "opp1": "1.45",
      "opp2": "0.03"
    },
    {
      "id": 45,
      "name": "Атаки",
      "opp1": "61",
      "opp2": "54"
    },
    {
      "id": 58,
      "name": "Опасные атаки",
      "opp1": "44",
      "opp2": "19"
    },
    {
      "id": 29,
      "name": "Владение мячом %",
      "opp1": "65",
      "opp2": "35"
    }
  ]
}
```

У этого матча первая команда — «Арсенал», вторая — «Ковентри Сити». Поэтому значение
владения мячом `65` относится к «Арсеналу», а `35` — к «Ковентри Сити».

## Формат значений `opp1` и `opp2`

В JSON поля `opp1` и `opp2` передаются строками, даже когда внутри находится число:

```json
{
  "name": "Атаки",
  "opp1": "61",
  "opp2": "54"
}
```

Десятичное значение также передаётся строкой:

```json
{
  "name": "xG",
  "opp1": "1.45",
  "opp2": "0.03"
}
```

Для процентных показателей знак `%` находится в названии, а значения возвращаются без
знака процента:

```json
{
  "name": "Владение мячом %",
  "opp1": "65",
  "opp2": "35"
}
```

Для обычного отображения значения можно использовать как строки. Преобразуйте их в
числа только для известных показателей, если клиенту нужны вычисления, сравнение или
диаграммы. Не выполняйте числовое преобразование всех возможных значений автоматически:
состав и формат статистики зависят от вида спорта и поставщика данных.

## `id` и `name`

Для программного сопоставления показателей используйте `id`. Поле `name` локализуется
в соответствии с языком запроса и предназначено для отображения.

Например, показатель `id: 45` возвращается как:

```text
ru → Атаки
en → Attacks
```

Не используйте `name` как постоянный технический идентификатор и не связывайте ответы
на разных языках по тексту названия.

## Подтверждённые показатели футбольного матча

В сохранённых русских и английских ответах футбольных Live-матчей встретились следующие
ID. Таблица описывает только фактически найденные показатели и не является полным
справочником для всех видов спорта.

| `id` | Русское название | Английское название |
|---:|---|---|
| `26` | Желтые карточки | Yellow cards |
| `29` | Владение мячом % | Possession % |
| `45` | Атаки | Attacks |
| `47` | Сейвы | Saves |
| `58` | Опасные атаки | Dangerous attacks |
| `59` | Удары в створ | Shots on target |
| `60` | Удары в сторону ворот | Shots off target |
| `70` | Угловые | Corner |
| `71` | Красные карточки | Red card |
| `72` | Пенальти | Penalty |
| `92` | Замены | Substitutions |
| `93` | xG | xG |
| `94` | Ключевые передачи | Key Passes |
| `95` | Точность передач % | Passing Accuracy % |
| `96` | Кроссы | Crosses |

Набор показателей зависит от вида спорта, конкретного матча и доступности данных. Не
создавайте обязательный список, в котором каждый Live-матч должен содержать все ID из
этой таблицы.

## Пустая и отсутствующая статистика

Пустой массив означает, что в текущем ответе статистические показатели не переданы:

```json
{
  "stat_list": []
}
```

Это не означает, что все показатели равны нулю. Причинами могут быть отсутствие
статистического покрытия, текущий этап матча или тип линии.

Различайте следующие ситуации:

| Состояние | Значение |
|---|---|
| `stat_list` заполнен | Отображайте фактически полученные показатели |
| `stat_list: []` | Статистика сейчас не передана |
| Поле `stat_list` отсутствует | Выбранный метод или формат ответа не предоставляет это поле |
| Показатель отсутствует в заполненном списке | Значение конкретного показателя неизвестно; это не ноль |
| `opp1: "0"` или `opp2: "0"` | API явно передал нулевое значение |

Не сохраняйте старое значение как актуальное, если при следующем обновлении показатель
перестал возвращаться.

## Статистика в субматчах

В ответе любого субматча поле `stat_list` содержит статистику основного матча, а не
отдельную статистику выбранного субматча.

Например, это правило сохраняется при переходе в субматчи:

- «Угловые»;
- «Угловые, 1-й тайм»;
- «1-й тайм»;
- карточки, фолы и другие дополнительные разделы матча.

Даже если пользователь открыл субматч «Угловые, 1-й тайм», в `stat_list` передаются
основные показатели всего матча: xG, атаки, владение мячом, удары, карточки и другие
доступные значения.

Не связывайте содержимое `stat_list` с названием `game_dop_name` и не фильтруйте
статистику на основании типа субматча. Для определения основного матча используйте
`game_mid`.

## Обновление статистики

Статистика Live-матча меняется в ходе игры. При каждом получении нового ответа:

1. Сопоставляйте показатели по `id`.
2. Обновляйте значения `opp1` и `opp2`.
3. Используйте полученное `name` для выбранного языка.
4. Добавляйте новые показатели, появившиеся в ответе.
5. Не продолжайте показывать исчезнувший показатель как актуальный.

Частоту запроса определяет метод, из которого получается матч. Рекомендованные интервалы
описаны в документе
[«Рекомендации по обновлению данных»](../getting-started/update-guidelines.md).

## `stat_list_extra`

Поле `stat_list_extra` не является продолжением `stat_list`. Сейчас это зарезервированное
тестовое поле, которое не используется в клиентской интеграции.

```json
{
  "stat_list_extra": []
}
```

Не объединяйте `stat_list_extra` со статистикой матча и не стройте обязательную логику
на его содержимом.

## Практические правила интеграции

1. Используйте `id` как технический идентификатор показателя.
2. Показывайте локализованное значение `name`, полученное от API.
3. Связывайте `opp1` с первой стороной матча, а `opp2` — со второй.
4. Поддерживайте строковый JSON-тип значений.
5. Не считайте пустой список или отсутствующий показатель нулевым значением.
6. Не ожидайте одинаковый набор статистики у всех видов спорта и матчей.
7. При обновлении заменяйте статистику актуальными данными ответа.
8. Не смешивайте `stat_list` со ставками из `game_oc_list` и `sub_games`.

## Проверочные ответы

- [Live-матч, русский язык](../examples/json-responses/event.game-746146992.group.live.ru.json)
- [Live-матч, английский язык](../examples/json-responses/event.game-746146992.group.live.en.json)
- [Live-субматч «Угловые»](../examples/json-responses/event.subgame-746147010.corners.group.live.ru.json)

## Связанные документы

- [Модель данных: матч](match.md)
- [Единый справочник полей](field-reference.md)
- [`events` — список матчей](../api-reference/events.md)
- [`event` — конкретный матч](../api-reference/event.md)
