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

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

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

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

Только Prematch

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

Для топ-матчей Live используйте topmatches:

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

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

Для запроса нужен sportId. Его можно получить через метод menu или sports.

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

Запрос

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

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

Package: YOUR_API_KEY

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

Параметр full

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Иконки

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

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

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

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

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

Отличие от topmatches

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

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

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

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

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

• Русский язык
• Английский язык

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

• Русский язык
• Английский язык

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

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

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

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

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