Sport Line API — основные понятия

Этот документ объясняет, как устроена спортивная линия, как связаны её объекты и какие идентификаторы нужно использовать при интеграции.

REST API и актуальность данных

Sport Line API работает через REST API. Каждый запрос возвращает снимок данных на момент запроса.

Чтобы получать обновлённые счета, статусы матчей и коэффициенты, приложение клиента должно повторять запросы. Рекомендуемые интервалы будут описаны в отдельном руководстве.

Подключение через WebSocket находится в разработке и пока не используется в рабочей интеграции.

Prematch и live

Спортивная линия разделена на два типа данных:

Тип линии передаётся в пути запроса. Например, live-меню:

/v1/menu/live/ru

Один и тот же спортивный матч может сначала находиться в prematch-линии, а после начала — в live-линии. Для live-матча формируется новый game_id, который не совпадает с ID из prematch-линии. Считайте их разными событиями API и не связывайте по game_id.

Иерархия спортивной линии

Данные в Sport Line API организованы по следующей схеме:

вид спорта
└── страна
    └── турнир
        └── матч
            ├── рынки и коэффициенты
            └── субсобытия матча
                └── свои рынки и коэффициенты

Метод menu возвращает всю эту структуру до уровня турнира. Список матчей запрашивается отдельно методом events.

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

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

Навигацию нужно строить из актуального ответа

Не запрашивайте виды спорта, страны и турниры по заранее записанным статическим ID, не проверив, что они присутствуют в текущей выдаче. Sport Line API возвращает только те разделы, в которых на момент запроса есть доступные матчи выбранного типа линии.

Рекомендуемая цепочка:

menu для live или line
  ↓ актуальный sportId
  ↓ актуальный countryId
  ↓ актуальный tournamentId
events

Если используется пошаговая навигация, соблюдайте полный порядок:

sports
  ↓ sportId из текущего ответа
countries
  ↓ countryId из текущего ответа
tournaments
  ↓ tournamentId из текущего ответа
events

Нельзя один раз сохранить sportId и tournamentId, а затем считать, что эти разделы всегда присутствуют в line или live. Сам идентификатор может продолжать обозначать тот же спорт или турнир, но его наличие в текущей спортивной линии динамическое.

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

Крикет → страна → лига → матч

Когда матч начнётся и перейдёт в Live, будет отменён или исчезнет из Prematch по другой причине, эта лига больше не вернётся в Prematch-меню. Если в Prematch не останется других матчей по крикету, из ответа также исчезнет сам вид спорта «Крикет».

Для Live действует то же правило: если единственный Live-матч турнира завершился, турнир исчезнет из Live-выдачи; если это был единственный матч вида спорта, исчезнет и вид спорта.

line и live проверяются отдельно. Наличие спорта или турнира в Prematch не означает, что он уже присутствует в Live, и наоборот.

При обновлении навигации:

1. Получите новый актуальный ответ для нужного типа линии.
2. Проверьте, остался ли выбранный спорт в ответе.
3. Проверьте выбранные страну и турнир внутри этого спорта.
4. Если выбранная ветка исчезла, прекратите считать её доступной и предложите пользователю актуальные разделы.
5. Не продолжайте постоянно запрашивать events по ID турнира, которого больше нет в текущей навигации.

Идентификаторы

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

В названиях параметров URL обычно используется форма sportId, а в JSON-ответах — sport_id. Это один и тот же идентификатор, записанный в разных стилях.

Для метода events значение tournamentId = 0 означает: вернуть матчи всех турниров выбранного вида спорта.

game_id, zp и vi — разные идентификаторы

game_id — это ID матча в Sport Line API. Он используется, чтобы запросить подробные данные матча методом event.

zp — это отдельный ID для Live 3D Tracker. Значение поля zp нужно передавать в параметр gameid трекера:

gameid трекера = zp из Sport Line API

Если zp равен null, Live 3D Tracker для данного матча недоступен. Трекер работает только для live-матчей и поддерживаемых видов спорта.

Не передавайте game_id в трекер вместо zp.

vi — это ID видеотрансляции live-матча. Например:

{
  "vi": "DR_3_1783061985"
}

Поля zp и vi находятся в JSON-объекте матча:

Эти значения не заменяют game_id и используются только для подключения соответствующего сервиса.

Методы events и event

Названия этих методов отличаются одной буквой, но они решают разные задачи:

Общий порядок работы:

1. Получить иерархию через menu.
2. Выбрать sportId и tournamentId.
3. Получить список матчей через events.
4. Взять game_id нужного матча.
5. Получить подробные данные через event.

Общий вид путей:

/v1/events/{sportId}/{tournamentId}/{format}/{count}/live/{lang}
/v1/event/{gameId}/{format}/live/{lang}

Тип линии и формат ответа

Тип линии и формат ответа — это разные параметры:

Например, live и sub в методе events означают: вернуть live-матчи, сгруппированные по турнирам.

Форматы

В events используется только sub. В event используется только group.

Формат group рекомендуется для конкретного матча, потому что API уже формирует колонки и сортирует исходы по значениям. Клиенту не нужно самостоятельно перестраивать или повторно сортировать эту структуру.

Формат не изменяет сам матч, его ID или тип линии. Он изменяет только организацию данных в ответе.

Матч, рынок и коэффициент

Объект матча может содержать:

• вид спорта, страну и турнир;
• участников матча;
• время начала;
• текущий счёт, период и таймер;
• рынки и коэффициенты;
• статистику и субсобытия матча;
• идентификаторы Live 3D Tracker и live-видеотрансляции, если они доступны.

Субсобытия матча

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

Субсобытия могут использоваться для ставок на отдельную часть матча или на отдельную статистику. Например:

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

Кроме субсобытий, в game_oc_list могут находиться ставки на показатели отдельных игроков. Такие ставки относятся к рынкам и не обязательно являются отдельными элементами sub_games.

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

В ставках используются два уровня:

рынок (группа) → исход с коэффициентом

Например, рынок может содержать несколько вариантов исхода. Каждый исход имеет своё название, текущее значение коэффициента и признак доступности.

Подробная таблица полей матча, рынка и коэффициента будет находиться в разделе «Модели данных».

Поле counter

В объектах меню может встречаться поле counter. Оно показывает количество доступных матчей внутри соответствующего вида спорта, страны или турнира для выбранного типа линии.

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

Язык ответа

Код языка передаётся в конце пути запроса:

/v1/menu/live/ru

Язык влияет на названия видов спорта, стран, турниров, команд, рынков и других текстовых полей. Идентификаторы объектов от выбранного языка не зависят.

Язык должен поддерживаться Sport Line API и входить в тариф клиента.

Киберспорт

В методах, которые поддерживают киберспортивные данные, используется необязательный query-параметр:

?cybersport=true

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

Общий формат успешного ответа

Большинство успешных ответов имеет общую оболочку:

{
  "status": 1,
  "page": "/v1/menu",
  "body": []
}

Ошибки могут возвращаться в другой структуре с полями error_code и error_message. Подробнее: «Обработка ошибок».

Как использовать эти понятия при интеграции

1. Храните prematch- и live-данные раздельно.
2. Связывайте объекты по ID, а не по названиям.
3. Получайте game_id из events, прежде чем запрашивать event.
4. Для Live 3D Tracker используйте zp, а не game_id.
5. Для live-видеотрансляции используйте vi.
6. Учитывайте, что счёт, таймер, статусы и коэффициенты могут изменяться.
7. Проверяйте ответы API на ошибки и пустые массивы.

Следующий документ: 04-рекомендации-по-обновлению.md.