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

Что такое дополнительный матч

Дополнительный матч, или субматч, — это отдельная линия внутри основного спортивного события. У субматча есть собственный game_id и собственный набор групп ставок и коэффициентов.

Примеры субматчей:

• первый или второй тайм;
• угловые;
• угловые первого или второго тайма;
• жёлтые карточки;
• фолы и офсайды;
• удары по воротам и в створ ворот;
• статистика игроков;
• другие дополнительные рынки матча.

В документации термины «дополнительный матч» и «субматч» обозначают одну и ту же сущность из массива sub_games.

Основной матч и субматч

Основной матч и его субматчи связаны полями game_id и game_mid.

У основного матча game_id и game_mid обычно совпадают, а game_dop_name остаётся пустым:

{
  "game_id": 746146992,
  "game_mid": 746146992,
  "game_dop_name": ""
}

У субматча собственный game_id, а game_mid указывает на основной матч:

{
  "game_id": 746147010,
  "game_mid": 746146992,
  "game_dop_name": "Угловые"
}

В этом примере:

• 746147010 — ID субматча «Угловые»;
• 746146992 — ID основного матча;
• запрос коэффициентов на угловые выполняется по game_id субматча 746147010.

Не заменяйте game_id субматча значением game_mid: эти поля решают разные задачи.

Где получается список субматчей

Список дополнительных матчей нужно получать только из поля sub_games подробного ответа event для основного матча.

events
  ↓ game_id основного матча
event основного матча
  ↓ sub_games[].game_id
event выбранного субматча
  ↓ game_oc_list
полный список его ставок и коэффициентов

В списке матчей events поле sub_games не используется и возвращается пустым:

{
  "sub_games": []
}

В topmatches?full=true и toplist?full=true список субматчей также не предоставляется.

Структура sub_games

sub_games — массив ссылок на доступные дополнительные матчи:

{
  "sub_games": [
    {
      "game_id": 746147013,
      "game_num": 150080,
      "game_name": "2-й тайм"
    },
    {
      "game_id": 746147010,
      "game_num": 205978,
      "game_name": "Угловые"
    },
    {
      "game_id": 746147314,
      "game_num": 178621,
      "game_name": "Желтые карточки"
    }
  ]
}

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

Для запроса используйте только game_id. Не формируйте ID субматча самостоятельно и не используйте вместо него game_num.

Что находится внутри sub_games

Элемент sub_games содержит только ссылку и название субматча. В нём нет:

• коэффициентов;
• групп ставок;
• полного объекта матча;
• отдельной статистики;
• списка дочерних субматчей.

Чтобы получить ставки и коэффициенты, выполните отдельный запрос event по game_id выбранного дополнительного матча.

Запрос дополнительного матча

Основной Live-матч вернул ссылку на субматч «Угловые»:

{
  "game_id": 746147010,
  "game_num": 205978,
  "game_name": "Угловые"
}

Запрос субматча выполняется тем же методом event:

curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/event/746147010/group/live/ru' \
  --header 'Package: YOUR_API_KEY'

Сокращённый фрагмент ответа:

{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "game_id": 746147010,
    "game_mid": 746146992,
    "game_dop_name": "Угловые",
    "game_desk": "Тайм",
    "game_oc_counter": 175,
    "sub_games": []
  }
}

Полный список ставок субматча находится в body.game_oc_list. Он имеет такую же структуру group, как список ставок основного матча.

Сохранённый полный ответ: субматч «Угловые», Live, русский язык.

Live и Prematch

Дополнительные матчи могут возвращаться как в Live, так и в Prematch. Запрашивайте субматч в том же типе линии, из которого был получен его game_id:

sub_games из Live     → event/{gameId}/group/live/{lang}
sub_games из Prematch → event/{gameId}/group/line/{lang}

Prematch- и Live-версии матчей имеют разные ID. Не переносите game_id основного матча или субматча из line в live.

Состав sub_games также может различаться между Prematch и Live. Используйте только актуальный список из текущего ответа API.

Названия и типы субматчей

В списке sub_games название находится в game_name:

{
  "game_name": "Угловые"
}

После запроса дополнительного матча его тип возвращается в game_dop_name:

{
  "game_dop_name": "Угловые"
}

Поле game_desk может дополнительно обозначать игровой отрезок, например Тайм, Сет или Четверть. Оно не заменяет game_id и не используется как постоянный ID типа субматча.

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

Коэффициенты субматча

Субматч является отдельным объектом спортивной линии и имеет собственные:

• game_id;
• game_oc_counter;
• группы в game_oc_list;
• исходы и коэффициенты;
• значения oc_pointer.

Коэффициенты в game_oc_list относятся только к выбранному субматчу. Они не содержат ставки основного матча или других дополнительных матчей.

Например, если запрошен субматч «Угловые, 1-й тайм», ответ содержит коэффициенты только на угловые первого тайма:

• не на все события первого тайма;
• не на все угловые основного матча;
• не на основной матч целиком.

Чтобы получить коэффициенты на все угловые матча, нужно отдельно открыть субматч «Угловые». Для коэффициентов основного матча нужно запросить event по game_id основного матча.

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

Подробное описание структуры ставок: «Коэффициенты и группы ставок».

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

Поле stat_list внутри ответа субматча относится к основному матчу целиком. Оно не содержит отдельную статистику выбранного дополнительного матча.

Например, при запросе «Угловые, 1-й тайм» или «1-й тайм» в stat_list всё равно передаются основные показатели главного матча. Не фильтруйте статистику по game_dop_name.

Подробные правила описаны в документе «Статистика матча».

Когда субматч недоступен

Список дополнительных матчей может изменяться. Если нужного элемента больше нет в актуальном sub_games, не продолжайте показывать его как доступный.

При запросе устаревшего game_id API может вернуть:

{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game id finished"
  }
}

После такого ответа прекратите обновлять прежний ID. Сообщение не объясняет точную причину исчезновения дополнительного матча.

Групповые матчи и event_plan

event_plan и sub_games — разные структуры.

event_plan предназначен для групповых матчей. В основном объекте такого события стороны могут называться обобщённо, например «Хозяева — Гости». Поле event_plan раскрывает состав этих сторон и перечисляет все реальные команды, которые участвуют в групповом матче.

Каждый объект массива связывает одну команду со стороны хозяев с соответствующей командой со стороны гостей. Полный массив содержит все такие пары и тем самым показывает полный список команд обеих сторон.

Например, sub_games может содержать отдельный рынок «Угловые» или «1-й тайм», а event_plan для группового матча «Хозяева — Гости» содержит пары конкретных команд:

Хозяева                         Гости
Anzoategui          →           Trujillanos
Caracas             →           Carabobo

Заполненный event_plan можно получить только через конкретный event. В списке events поле возвращается как [].

Поля объекта event_plan

Сокращённый пример состава группового матча:

{
  "event_plan": [
    {
      "opp_1_name": "Anzoategui",
      "opp_2_name": "Trujillanos",
      "opp_1_id": 6354451,
      "opp_2_id": 2792,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "b85e2e3631e4b873b1d74975e6dd4e93.png",
      "opp_2_icon": "2792.png",
      "game_start": 1787342400
    },
    {
      "opp_1_name": "Caracas",
      "opp_2_name": "Carabobo",
      "opp_1_id": 2776,
      "opp_2_id": 29081,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "6309ee8475d59f87fff70fd08858e36f.png",
      "opp_2_icon": "56b11c23ac71e2f6934a7e0feb46dd5e.png",
      "game_start": 1787353200
    }
  ]
}

Элементы event_plan не являются ссылками на субматчи: в них нет отдельного game_id для запроса event. Используйте их для отображения полного состава команд на стороне хозяев и гостей и расписания пар внутри группового матча.

Для иконки участника удалите расширение из opp_1_icon или opp_2_icon и подставьте оставшееся имя в URL:

https://cdn.sportapi.net/opp/v1/color/{iconName}.webp

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

1. Получайте sub_games только из подробного ответа основного матча event.
2. Для открытия субматча используйте его собственный game_id.
3. Запрашивайте дополнительный матч в том же типе линии: live или line.
4. Не используйте устаревшее поле game_num.
5. Не ожидайте коэффициенты непосредственно внутри sub_games.
6. Связывайте субматч с основным матчем через game_mid.
7. Не интерпретируйте статистику субматча как отдельную статистику его рынка.
8. Не смешивайте дополнительные матчи из sub_games с составом группового матча в event_plan.
9. Обновляйте список субматчей по актуальному ответу API.

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

• Основной Live-матч с 13 субматчами
• Основной Prematch с 24 субматчами
• Подробный ответ субматча «Угловые»

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

• Модель данных: матч
• Модель данных: статистика матча
• Коэффициенты и группы ставок
• event — конкретный матч
• Единый справочник полей