---
id: core-concepts
title: Sport Line API — основные понятия
description: Объяснение основных сущностей спортивной линии и связей между спортом, страной, турниром, матчем и ставками.
version: v1
language: ru
---

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


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

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

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

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

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

## Prematch и live

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

| Значение в URL | Название | Что содержит |
|---|---|---|
| `line` | Prematch-линия | Матчи, которые ещё не начались |
| `live` | Live-линия | Матчи, которые идут сейчас |

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

```text
/v1/menu/live/ru
```

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

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

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

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

| Уровень | Что означает | Основной ID |
|---|---|---|
| Вид спорта | Футбол, баскетбол, теннис и другие виды спорта | `sportId` |
| Страна | Страна, к которой относится турнир | `countryId` |
| Турнир | Лига, кубок или другое соревнование | `tournamentId` |
| Матч | Отдельное спортивное событие | `game_id` |
| Субсобытие матча | Отдельная линия внутри основного матча | `sub_games[].game_id` |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

| Что обозначает | Параметр в описании URL | Поле в JSON |
|---|---|---|
| Вид спорта | `sportId` | `sport_id` |
| Страна | `countryId` | `country_id` |
| Турнир | `tournamentId` | `tournament_id` |
| Матч | `gameId` | `game_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` трекера:

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

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

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

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

```json
{
  "vi": "DR_3_1783061985"
}
```

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

| Поле | Назначение |
|---|---|
| `zp` | ID Live 3D Tracker |
| `vi` | ID live-видеотрансляции |

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

## Методы `events` и `event`

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

| Метод | Назначение |
|---|---|
| `events` | Возвращает список матчей вида спорта или конкретного турнира |
| `event` | Возвращает подробные данные одного матча по `game_id` |

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

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

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

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

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

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

| Понятие | Допустимые значения | За что отвечает |
|---|---|---|
| Тип линии | `line`, `live` | Какие матчи запрашиваются: prematch или live |
| Формат ответа | `sub` для `events`, `group` для `event` | Как будут сгруппированы матчи и коэффициенты в JSON |

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

### Форматы

| Формат | Где доступен | Структура |
|---|---|---|
| `sub` | только `events` | Матчи, сгруппированные по турнирам |
| `group` | только `event` | Коэффициенты, сформированные по группам и колонкам и отсортированные по значениям |

В `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` содержит текущую статистику самого матча. Это фактические показатели, а не
список доступных ставок.

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

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

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

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

## Поле `counter`

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

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

## Язык ответа

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

```text
/v1/menu/live/ru
```

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

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

## Киберспорт

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

```text
?cybersport=true
```

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

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

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

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

| Поле | Значение |
|---|---|
| `status` | Статус выполнения. В успешном ответе обычно равен `1` |
| `page` | Метод API, который сформировал ответ |
| `body` | Данные метода. Тип и структура зависят от метода |

Ошибки могут возвращаться в другой структуре с полями `error_code` и `error_message`.
Подробнее: [«Обработка ошибок»](error-handling.md).

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

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`.
