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

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

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

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

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

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-матчей и только в двух случаях:

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

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

Структура stat_list

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

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

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

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

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

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

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

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

{
  "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 передаются строками, даже когда внутри находится число:

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

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

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

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

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

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

id и name

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

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

ru → Атаки
en → Attacks

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

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

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

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

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

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

{
  "stat_list": []
}

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

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

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

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

В ответе любого субматча поле 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. Не продолжайте показывать исчезнувший показатель как актуальный.

Частоту запроса определяет метод, из которого получается матч. Рекомендованные интервалы описаны в документе «Рекомендации по обновлению данных».

stat_list_extra

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

{
  "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-матч, русский язык
• Live-матч, английский язык
• Live-субматч «Угловые»

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

• Модель данных: матч
• Единый справочник полей
• events — список матчей
• event — конкретный матч