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

# Метод `topmatches` — топ-матчи


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

Метод `topmatches` возвращает готовую подборку топ-матчей сразу по всем видам спорта,
доступным API-ключу клиента.

Его удобно использовать для отдельного блока «Топ-матчи» на главной странице. Для
запроса не нужно заранее получать `sportId`, `countryId` или `tournamentId`.

SportAPI самостоятельно формирует состав и порядок подборки. В одном ответе возвращается
до 10 матчей. Критерии попадания матча в подборку через параметры запроса не настраиваются.

Для Live и Prematch формируются отдельные списки.

## Запрос

```http
GET https://YOUR_API_DOMAIN/v1/topmatches/{type}/{lang}
```

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

```http
Package: YOUR_API_KEY
```

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

| Параметр | Тип | Обязательный | Описание |
|---|---|---:|---|
| `type` | string | да | Тип спортивной линии: `live` или `line` |
| `lang` | string | да | Язык названий. Язык должен поддерживаться API и входить в тариф клиента |

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

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

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

`full` — необязательный query-параметр, который определяет детализацию каждого матча.

| Значение | Результат |
|---|---|
| параметр отсутствует или `full=false` | Сокращённая карточка матча без коэффициентов, ID страны и ID турнира |
| `full=true` | Расширенный объект матча с командами, страной, турниром, счётом и кратким списком коэффициентов |

Пример URL с расширенными объектами:

```http
GET https://YOUR_API_DOMAIN/v1/topmatches/live/ru?full=true
```

**Важно:** `full=true` возвращает полный набор полей карточки, но не полный список всех
коэффициентов матча. В `game_oc_list` остаётся краткий набор основных групп и лучших
коэффициентов, аналогичный методу [`events`](../events.md). Чтобы получить все доступные
группы и исходы, выполните запрос [`event`](../event.md) по `game_id`.

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

Сокращённые карточки:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/live/ru' \
  --header 'Package: YOUR_API_KEY'
```

Расширенные объекты:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/live/ru?full=true' \
  --header 'Package: YOUR_API_KEY'
```

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

Сокращённые карточки:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/line/ru' \
  --header 'Package: YOUR_API_KEY'
```

Расширенные объекты:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/line/ru?full=true' \
  --header 'Package: YOUR_API_KEY'
```

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

Ниже показана одна карточка из реального Live-ответа без `full=true`:

```json
{
  "status": 1,
  "page": "/v1/topmathes",
  "body": [
    {
      "sgame_id": "0",
      "stat_id": "0",
      "game_id": 746267958,
      "game_mid": 746267958,
      "game_start": 1787382000,
      "tournament_name": "Mobile Legends. MPL Indonesia",
      "opp_1_name": "Team Liquid ID",
      "opp_2_name": "Evos",
      "opp_1_icon": "2b86bbc5fe28202aaddb53e2fe651a46.png",
      "opp_2_icon": "459077.png",
      "sport_id": 40,
      "sport_name": "КиберСпорт",
      "score_full": "1:0",
      "period_name": "2-я карта",
      "timer": 0,
      "va": 1,
      "vi": "20072803",
      "zp": null
    }
  ]
}
```

Значения взяты из снимка спортивной линии и со временем изменятся.

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

| Поле | Тип | Описание |
|---|---|---|
| `status` | number | Статус выполнения запроса. В успешном ответе возвращается `1` |
| `page` | string | В текущем ответе API возвращается строка `/v1/topmathes` |
| `body` | array | Плоский массив топ-матчей без группировки по видам спорта или турнирам |

В значении `page` сейчас используется `/v1/topmathes` без буквы `c`. Это фактическое
значение ответа API. Сам URL запроса при этом пишется правильно: `/v1/topmatches/...`.
Не используйте поле `page` для формирования следующего URL.

## Поля сокращённой карточки

| Поле | Тип | Описание |
|---|---|---|
| `sgame_id` | string | Зарезервированное тестовое поле. Пока не используется в API |
| `stat_id` | string | Зарезервированное тестовое поле. Пока не используется в API |
| `game_id` | number | ID матча для запроса подробного метода `event` |
| `game_mid` | number или `null` | ID основного матча |
| `game_start` | number | Время начала в формате Unix Timestamp, в секундах |
| `tournament_name` | string | Название турнира на выбранном языке |
| `opp_1_name` | string | Первая команда или участник |
| `opp_2_name` | string | Вторая команда или участник |
| `opp_1_icon` | string | Имя файла иконки первой команды или участника |
| `opp_2_icon` | string | Имя файла иконки второй команды или участника |
| `sport_id` | number | ID вида спорта |
| `sport_name` | string | Название вида спорта на выбранном языке |
| `score_full` | string | Текущий общий счёт. В Prematch обычно возвращается `0:0` |
| `period_name` | string | Текущий период Live-матча. В Prematch возвращается пустая строка |
| `timer` | number | Таймер Live-матча в секундах. Для получения минут разделите на `60`. В Prematch обычно возвращается `0` |
| `va` | number или `null` | `1` — есть видеотрансляция; `null` — трансляции нет |
| `vi` | string или `null` | ID видеотрансляции Live-матча |
| `zp` | number или `null` | ID Live 3D Tracker; передаётся в трекер как `gameid` |

## Ответ с `full=true`

При `full=true` поле `body` остаётся плоским массивом матчей, но каждый элемент содержит
расширенный объект, близкий к объекту матча из `events`:

- ID и название страны;
- ID и название турнира;
- ID команд или участников;
- счёт и период;
- краткий список групп и коэффициентов в `game_oc_list`;
- признаки доступности видео и Live 3D Tracker;
- дополнительные поля объекта матча.

В `topmatches?full=true` поле `game_oc_list` имеет такую же структуру, как в `events`:
`oc_list` внутри группы является обычным массивом исходов. В методе `event` с форматом
`group` структура отличается: там `oc_list` содержит вложенные массивы колонок.

В сохранённых ответах `topmatches?full=true` поля `sub_games` и `event_plan` возвращаются
пустыми массивами. Для получения доступных субматчей или состава сложного события нужно
запросить конкретный матч через метод `event`.

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

## Иконки

Иконка вида спорта формируется по `sport_id`:

```text
https://cdn.sportapi.net/sports/v1/color/{sport_id}.webp
```

При `full=true` иконку турнира можно сформировать по `tournament_id`:

```text
https://cdn.sportapi.net/tournaments/v1/color/{tournament_id}.webp
```

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

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

## Ограничения тарифа

Метод возвращает топ-матчи только тех видов спорта, которые доступны API-ключу клиента.
Один ответ может содержать матчи разных видов спорта.

Если нужно получить обычный список матчей конкретного спорта или турнира, используйте
[`events`](../events.md). Для подробных данных одного матча используйте [`event`](../event.md).

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

На момент запросов каждый Live- и Prematch-ответ содержал по 10 матчей. Это снимок
динамических данных от 22 августа 2026 года, а не постоянный состав подборки.

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

### Сокращённые карточки

- [Live, русский язык](../../examples/json-responses/topmatches.live.ru.json)
- [Prematch, русский язык](../../examples/json-responses/topmatches.line.ru.json)
- [Live, английский язык](../../examples/json-responses/topmatches.live.en.json)
- [Prematch, английский язык](../../examples/json-responses/topmatches.line.en.json)

### Расширенные объекты (`full=true`)

- [Live, русский язык](../../examples/json-responses/topmatches.full.live.ru.json)
- [Prematch, русский язык](../../examples/json-responses/topmatches.full.line.ru.json)
- [Live, английский язык](../../examples/json-responses/topmatches.full.live.en.json)
- [Prematch, английский язык](../../examples/json-responses/topmatches.full.line.en.json)

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

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

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

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

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

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