---
id: api-events
title: Метод `events` — список матчей
description: Описание метода events для получения списка матчей выбранного вида спорта, страны или турнира.
version: v1
language: ru
---

# Метод `events` — список матчей


## Для чего нужен метод

Метод `events` возвращает список матчей выбранного вида спорта. При необходимости список
можно ограничить одним турниром.

Ответ содержит:

- информацию о турнире;
- основные данные матчей;
- команды или участников;
- время начала;
- текущий счёт и период для Live;
- краткий набор групп ставок и коэффициентов;
- доступные Live-статистику, видео и ID трекера.

Для получения полного набора ставок одного матча используется метод `event`.

Полное описание всех полей собрано отдельно:
[«Единый справочник полей Sport Line API»](../data-models/field-reference.md).

## Перед запросом

Для запроса нужен `sportId`. Его можно получить через метод [`menu`](menu.md) или
[`sports`](optional-methods/sports.md).

Если нужны матчи конкретного турнира, также потребуется `tournamentId`. Его можно
получить из `menu` или [`tournaments`](optional-methods/tournaments.md).

Не используйте статически записанные `sportId` и `tournamentId` без проверки текущей
навигации. Эти ID должны присутствовать в актуальном `menu` либо быть получены по цепочке
`sports → countries → tournaments` для того же типа `live` или `line`.

API показывает только разделы, в которых сейчас есть матчи. Если завершился или исчез
единственный матч турнира, турнир пропадёт из следующего навигационного ответа. Если это
был единственный матч вида спорта, из ответа исчезнет и сам вид спорта.

Даже при `tournamentId=0` значение `sportId` нужно брать из актуального ответа API.

## Запрос

```http
GET https://YOUR_API_DOMAIN/v1/events/{sportId}/{tournamentId}/{format}/{count}/{type}/{lang}
```

API-ключ необходимо передавать в HTTP-заголовке:

```http
Package: YOUR_API_KEY
```

## Параметры пути

| Параметр | Тип | Обязательный | Описание |
|---|---|---:|---|
| `sportId` | number | да | ID вида спорта |
| `tournamentId` | number | да | ID турнира. Передайте `0`, чтобы получить все матчи всех доступных турниров выбранного спорта |
| `format` | string | да | Для списка матчей `events` используется только `sub`. Он группирует матчи по турнирам |
| `count` | number | да | Изначально задавал количество возвращаемых данных. Ограничение отменено: передавайте `50`, API всё равно вернёт все доступные матчи выбранной выборки |
| `type` | string | да | Тип спортивной линии: `live` или `line` |
| `lang` | string | да | Язык названий. Язык должен поддерживаться API и входить в тариф клиента |

Значения параметра `type`:

| Значение | Какие матчи возвращаются |
|---|---|
| `live` | Матчи, проходящие в реальном времени |
| `line` | Предстоящие Prematch-матчи |

### Параметр `format`

Для списка матчей `events` используется только формат `sub`. Он группирует матчи по
турнирам:

```text
body
└── турнир
    └── events_list
        └── матчи
```

### Параметр `count`

Параметр создавался для ограничения количества возвращаемых данных, но это ограничение
было отменено. Сегмент остался обязательной частью URL для совместимости.

Всегда передавайте `50`. Независимо от этого значения API возвращает все доступные матчи
выбранного спорта или турнира. Параметр нельзя использовать для пагинации или ограничения
размера ответа.

### Необязательный query-параметр

| Параметр | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
| `cybersport` | boolean | `false` | Переключает метод на матчи киберспорта |

Пример:

```http
GET https://YOUR_API_DOMAIN/v1/events/{sportId}/0/sub/50/live/ru?cybersport=true
```

Сохранённые в этой документации полные ответы получены без query-параметров, то есть
при `cybersport=false`.

## Пример запроса Live

В примере запрашиваются все Live-матчи всех доступных футбольных турниров:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/events/1/0/sub/50/live/ru' \
  --header 'Package: YOUR_API_KEY'
```

## Пример запроса Prematch

В примере запрашиваются все Prematch-матчи всех доступных футбольных турниров:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/events/1/0/sub/50/line/ru' \
  --header 'Package: YOUR_API_KEY'
```

Чтобы получить матчи только одного турнира, замените `0` на его `tournamentId`:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/events/1/2916716/sub/50/live/ru' \
  --header 'Package: YOUR_API_KEY'
```

## Сокращённый пример ответа Live

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

```json
{
  "status": 1,
  "page": "/v1/events",
  "body": [
    {
      "tournament_id": 2916716,
      "tournament_name": "Чемпионат России. Молодежное первенство. Дивизион А",
      "events_list": [
        {
          "sgame_id": "6a5a35d05e99bd05c64f543a",
          "stat_id": "69a27d775e99bd05c6eec890",
          "game_id": 746049368,
          "game_start": 1787313600,
          "country_id": 1,
          "country_name": "Россия",
          "tournament_id": 2916716,
          "tournament_name": "Чемпионат России. Молодежное первенство. Дивизион А",
          "opp_1_name": "Акрон-Академия Коноплева (мол)",
          "opp_2_name": "Зенит (мол)",
          "game_oc_counter": 425,
          "game_oc_list": [
            {
              "group_id": 1,
              "group_name": "1X2",
              "columns": 3,
              "oc_list": [
                {
                  "oc_group_name": "1X2",
                  "oc_name": "П2",
                  "oc_rate": 2.505,
                  "oc_size": 0,
                  "oc_pointer": "746049368|1|3|0",
                  "oc_block": false,
                  "op_id": null
                },
                {
                  "oc_group_name": "1X2",
                  "oc_name": "П1",
                  "oc_rate": 2.605,
                  "oc_size": 0,
                  "oc_pointer": "746049368|1|1|0",
                  "oc_block": false,
                  "op_id": null
                },
                {
                  "oc_group_name": "1X2",
                  "oc_name": "Ничья",
                  "oc_rate": 3.49,
                  "oc_size": 0,
                  "oc_pointer": "746049368|1|2|0",
                  "oc_block": false,
                  "op_id": null
                }
              ]
            }
          ],
          "sport_id": 1,
          "sport_name": "Футбол",
          "timer": 2192,
          "score_full": "1:0",
          "score_period": "1:0",
          "stat_list": [
            {
              "id": 45,
              "name": "Атаки",
              "opp1": "29",
              "opp2": "30"
            }
          ],
          "period_name": "1-й тайм",
          "vi": "20064614",
          "zp": null
        }
      ]
    }
  ]
}
```

Это сокращённый фрагмент, а не полный объект матча. Полные ответы доступны в конце
документа.

## Структура ответа

### Верхний уровень

| Поле | Тип | Описание |
|---|---|---|
| `status` | number | Статус выполнения запроса. В успешном ответе возвращается `1` |
| `page` | string | Название метода. Для `events` возвращается `/v1/events` |
| `body` | array | Массив турниров с матчами |

### Объект турнира

| Поле | Тип | Описание |
|---|---|---|
| `tournament_id` | number | ID турнира |
| `tournament_name` | string | Название турнира на выбранном языке |
| `events_list` | array | Массив матчей этого турнира |

## Основные поля матча

| Поле | Тип | Описание |
|---|---|---|
| `game_id` | number | ID матча. Используется для запроса подробного метода `event` |
| `sgame_id` | string | Зарезервированное тестовое поле для статистики матча, команд и игроков. Пока не используется в API |
| `stat_id` | string | Зарезервированное тестовое поле для подробной статистики. Пока не используется в API |
| `game_mid` | number или `null` | ID основного матча. У субматча свой `game_id`, а `game_mid` указывает на главную игру |
| `game_num` | number | Старое неиспользуемое поле. Планируется к удалению из API |
| `game_start` | number | Время начала матча в формате Unix Timestamp, в секундах |
| `sport_id` | number | ID вида спорта |
| `sport_name` | string | Название вида спорта |
| `country_id` | number | ID страны |
| `country_name` | string | Название страны |
| `tournament_id` | number | ID турнира |
| `tournament_name` | string | Название турнира |
| `game_dop_name` | string | Название типа субматча. Например, `Угловые`, `Жёлтые карточки` или `1-й тайм` |
| `game_desk` | string | Тип игрового отрезка: например, `Тайм`, `Сет` или `Четверть` |

`game_id` Prematch-матча не сохраняется при переходе в Live. Для Live формируется новый
`game_id`, поэтому нельзя связывать Prematch- и Live-матчи по этому полю.

Не используйте поля `sgame_id`, `stat_id`, `game_num`, `stat_list_extra` и `game_plan` как
обязательную часть интеграции. Они являются старыми, тестовыми или зарезервированными.
`game_num` планируется удалить из API.

## Команды или участники

| Поле | Тип | Описание |
|---|---|---|
| `opp_1_name` | string | Название первой команды или участника |
| `opp_2_name` | string | Название второй команды или участника |
| `opp_1_id` | number | Основной ID первой команды или участника |
| `opp_2_id` | number | Основной ID второй команды или участника |
| `opp_1_ids` | array of number | ID участников первой стороны, если она состоит из нескольких игроков или команд |
| `opp_2_ids` | array of number | ID участников второй стороны, если она состоит из нескольких игроков или команд |
| `opp_1_icon` | string | Имя файла иконки первой команды или участника |
| `opp_2_icon` | string | Имя файла иконки второй команды или участника |

Массивы `opp_1_ids` и `opp_2_ids` нужны, когда одна сторона матча состоит из нескольких
участников. Например, это могут быть теннисные пары или групповой матч, в котором на
каждой стороне участвует несколько игроков или команд.

### Готовые иконки команд и участников

Для команд и участников можно использовать стандартные иконки SportAPI:

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

Значение `iconName` берётся из `opp_1_icon` или `opp_2_icon`. В реальных ответах имя
может приходить с расширением `.png`. Перед созданием CDN-ссылки исходное расширение
нужно убрать, после чего добавить `.webp` через шаблон URL.

Например:

```text
opp_1_icon: 8bd073a686a067e6732d8d1688a517c0.png
iconName:    8bd073a686a067e6732d8d1688a517c0
```

Готовая ссылка:

[https://cdn.sportapi.net/opp/v1/color/8bd073a686a067e6732d8d1688a517c0.webp](https://cdn.sportapi.net/opp/v1/color/8bd073a686a067e6732d8d1688a517c0.webp)

Для `opp_2_icon` используется то же правило.

## Счёт, период и Live-данные

| Поле | Тип | Описание |
|---|---|---|
| `timer` | number | Текущее значение таймера матча в секундах. Для получения минут разделите на `60`. В Prematch обычно `0` |
| `score_full` | string | Текущий общий счёт |
| `score_period` | string | Счёт текущего периода. Может быть пустой строкой |
| `score_extra` | string | Счёт гейма в теннисе, например `0:15`. В основном используется в теннисе и может встречаться в близких форматах, включая кибертеннис |
| `period_name` | string | Название текущего периода. В Prematch обычно пустая строка |
| `extra_time` | string | Количество добавленных минут. Например, `+10` |
| `finale` | boolean или `null` | Показывает, что матч закончился. Поле доступно не для всех матчей |
| `pitch` | string | ID участника, выполняющего подачу, для соответствующих видов спорта. Может быть пустой строкой |
| `stat_list` | array | Текущая статистика матча |
| `stat_list_extra` | array | Зарезервированное тестовое поле для дополнительного описания матча. Пока не используется |
| `sub_games` | array | В методе `events` не используется и возвращается как `[]`. Список субматчей доступен только в ответе конкретного `event` |
| `event_plan` | array | В методе `events` не используется и возвращается как `[]`. Состав отдельных матчей доступен только в конкретном `event` |
| `game_plan` | любое JSON-значение или `null` | Зарезервированное тестовое поле для описания матча, например стадии турнира или типа корта. Пока не используется |

В Prematch многие Live-поля возвращаются со стандартными значениями: `0`, пустой
строкой, пустым массивом или `null`. Клиент должен корректно обрабатывать все эти
варианты.

### Объект в `stat_list`

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

### Объект в `sub_games`

| Поле | Тип | Описание |
|---|---|---|
| `game_id` | number или `null` | ID субсобытия |
| `game_num` | number или `null` | Номер субсобытия |
| `game_name` | string или `null` | Название субсобытия |

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

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

```json
"sub_games": []
```

Метод `events` не использует `sub_games`: здесь поле возвращается только как `[]`.
Список субматчей доступен при запросе конкретного матча через `event`. Каждый элемент
содержит ID субматча, но не его коэффициенты. Для коэффициентов нужно выполнить отдельный
запрос `event` по `game_id` выбранного субматча.

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

## Ставки и коэффициенты

| Поле матча | Тип | Описание |
|---|---|---|
| `game_oc_counter` | number | Общий счётчик доступных ставок или исходов матча |
| `game_oc_list` | array | Краткий список основных групп и лучших коэффициентов, включённый в список матчей |

Значение `game_oc_counter` может быть значительно больше количества элементов,
фактически находящихся в `game_oc_list`. Для полного набора ставок выбранного матча
используйте метод `event`.

### Краткий список зависит от вида спорта

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

Например:

- в футболе краткий список может содержать группу `1X2` с победой первой команды,
  ничьёй и победой второй команды;
- в баскетболе вместо `1X2` часто возвращаются исходы победы первой и победы второй
  команды;
- в теннисе нет исхода на ничью.

При интеграции необходимо обрабатывать массив динамически:

1. Не привязывать интерфейс только к группе `1X2`.
2. Не ожидать обязательного наличия ничьей.
3. Читать фактические `group_name`, `columns` и `oc_list` из ответа.
4. Не полагаться на одинаковый порядок групп и исходов у разных видов спорта.
5. Для открытия всех доступных исходов выполнять запрос `event` по `game_id` выбранного
   матча.

### Группа ставок в `game_oc_list`

| Поле | Тип | Описание |
|---|---|---|
| `group_id` | number | ID группы ставок |
| `group_name` | string | Название группы |
| `columns` | number | Рекомендуемое количество колонок для отображения |
| `oc_list` | array | Исходы и коэффициенты внутри группы |

### Исход в `oc_list`

| Поле | Тип | Описание |
|---|---|---|
| `oc_group_name` | string | Название группы ставки |
| `oc_name` | string | Название исхода |
| `oc_rate` | number | Текущий коэффициент |
| `oc_size` | string или number | Значение форы, тотала или другого параметра. В реальных ответах встречаются оба типа |
| [`oc_pointer`](https://sportapi.net/ru/docs/coupon/bet-placement/bet-pointer.html) | string | Уникальный код ставки или исхода. Используется при передаче выбранной ставки в отдельную систему приёма и расчёта ставок |
| `oc_block` | boolean | `true` — исход заблокирован и недоступен; `false` — доступен |
| `op_id` | number или `null` | ID игрока или участника для персональных ставок, если он применим |

Коэффициенты и состояние `oc_block` могут измениться при каждом обновлении ответа.

## Видео и Live 3D Tracker

| Поле | Тип | Описание |
|---|---|---|
| `vi` | string или `null` | ID видеотрансляции Live-матча. `null` означает, что ID не предоставлен |
| `zp` | number или `null` | ID Live 3D Tracker. Значение передаётся в трекер как `gameid` |
| `va` | number или `null` | `1` — для матча есть видеотрансляция; `null` — видеотрансляции нет. Значение `0` не используется |

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

Подробнее:

- [Live 3D Tracker в Sport Line API](../additional-services/live-3d-tracker.md);
- [видеотрансляции в Sport Line API](../additional-services/video-streaming.md);
- [полная инструкция по подключению Live 3D Tracker](https://sportapi.net/ru/docs/live-3d-tracker/service-overview.html).

## Отличия Live и Prematch

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

- в Live обновляются таймер, счёт, период и статистика;
- в Prematch эти поля обычно содержат начальные или пустые значения;
- `vi` и `zp` относятся к дополнительным возможностям Live и могут быть `null`;
- коэффициенты и блокировка исходов обновляются независимо для Live и Prematch;
- при переходе матча из Prematch в Live создаётся новый `game_id`.

Live и Prematch необходимо запрашивать и хранить отдельно.

## Снимок сохранённых ответов

Для Live и Prematch использованы футбол (`sportId=1`) и `tournamentId=0`, поэтому каждый
файл содержит все матчи всех доступных футбольных турниров. Формат — `sub`, техническое
значение `count` — `50`.

| Тип линии | Турниры в ответе | Матчи в ответе |
|---|---:|---:|
| Live | 33 | 39 |
| Prematch (`line`) | 427 | 2638 |

Это статистика конкретных ответов от 21 августа 2026 года, а не постоянный состав API.

Полные ответы без сокращений:

- [Live, русский язык](../examples/json-responses/events.sport-1.tournament-0.sub-50.live.ru.json)
- [Prematch, русский язык](../examples/json-responses/events.sport-1.tournament-0.sub-50.line.ru.json)
- [Live, английский язык](../examples/json-responses/events.sport-1.tournament-0.sub-50.live.en.json)
- [Prematch, английский язык](../examples/json-responses/events.sport-1.tournament-0.sub-50.line.en.json)

Файлы содержат только тело ответа API. API-ключ в них не сохраняется.

## Частота обновления

Рекомендуется запрашивать `events`:

- Live — не чаще одного раза в 7 секунд;
- Prematch (`line`) — не чаще одного раза в 30 секунд.

Подробнее: [«Рекомендации по обновлению данных»](../getting-started/update-guidelines.md).

Ошибки ключа, тарифа и параметров описаны в документе
[«Обработка ошибок»](../getting-started/error-handling.md).
