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

# Метод `toplist` — топ-матчи выбранного вида спорта


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

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

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

## Только Prematch

`toplist` работает только с предстоящими Prematch-матчами. Параметра `type` в URL этого
метода нет, и передать значение `live` невозможно.

Для топ-матчей Live используйте [`topmatches`](topmatches.md):

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

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

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

API-ключ должен предоставлять доступ к выбранному виду спорта.

## Запрос

```http
GET https://YOUR_API_DOMAIN/v1/toplist/{sportId}/{lang}
```

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

```http
Package: YOUR_API_KEY
```

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

| Параметр | Тип | Обязательный | Описание |
|---|---|---:|---|
| `sportId` | number | да | ID вида спорта, полученный из `menu` или `sports` |
| `lang` | string | да | Язык названий. Язык должен поддерживаться API и входить в тариф клиента |

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

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

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

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

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

Сокращённые карточки топ-матчей футбола (`sportId=1`):

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

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

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

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

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

```json
{
  "status": 1,
  "page": "/v1/toplist",
  "body": [
    {
      "sgame_id": "6a35079e5e99bd05c63e9104",
      "stat_id": "6a34c3a75e99bd05c63e703a",
      "game_id": 730328424,
      "game_mid": 730328424,
      "game_start": 1787398200,
      "tournament_name": "Чемпионат Англии. Премьер-лига",
      "opp_1_name": "Халл Сити",
      "opp_2_name": "Манчестер Юнайтед",
      "opp_1_icon": "715c2f5d95d5a5a03bdb4d4e11bbd696.png",
      "opp_2_icon": "1996.png",
      "sport_id": 1,
      "sport_name": "Футбол",
      "score_full": "0:0",
      "period_name": "",
      "timer": 0,
      "va": null,
      "vi": null,
      "zp": null
    }
  ]
}
```

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

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

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

Матчи не группируются по странам или турнирам.

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

| Поле | Тип | Описание |
|---|---|---|
| `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 | Для Prematch возвращается пустая строка |
| `timer` | number | Таймер в секундах. Для Prematch обычно возвращается `0` |
| `va` | number или `null` | Для Prematch обычно `null` |
| `vi` | string или `null` | Для Prematch обычно `null` |
| `zp` | number или `null` | Для Prematch обычно `null` |

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

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

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

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

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

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

## Иконки

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

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

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

```text
https://cdn.sportapi.net/flags/v1/color/{country_id}.webp
```

Иконка турнира формируется по `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
```

## Отличие от `topmatches`

| Метод | Выборка спорта | Live | Prematch |
|---|---|---:|---:|
| `topmatches` | Все доступные виды спорта | да | да |
| `toplist` | Один вид спорта по `sportId` | нет | да |

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

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

Для проверки использован футбол (`sportId=1`). На момент запросов обычный и расширенный
ответы содержали по 10 Prematch-матчей.

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

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

- [Русский язык](../../examples/json-responses/toplist.sport-1.line.ru.json)
- [Английский язык](../../examples/json-responses/toplist.sport-1.line.en.json)

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

- [Русский язык](../../examples/json-responses/toplist.full.sport-1.line.ru.json)
- [Английский язык](../../examples/json-responses/toplist.full.sport-1.line.en.json)

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

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

`toplist` содержит только Prematch-матчи. Рекомендуется запрашивать его не чаще одного
раза в 120 секунд.

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

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