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

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

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

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

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

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

Запрос

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

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

Package: YOUR_API_KEY

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

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

Параметр full

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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
    }
  ]
}

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

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

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

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

Ответ с 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».

Иконки

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

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

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

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

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

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

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

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

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

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

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

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

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

• Live, русский язык
• Prematch, русский язык
• Live, английский язык
• Prematch, английский язык

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

• Live, русский язык
• Prematch, русский язык
• Live, английский язык
• Prematch, английский язык

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

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

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

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

Подробнее: «Рекомендации по обновлению данных».

Ошибки ключа, тарифа и параметров описаны в документе «Обработка ошибок».