Sport Line API — руководство по подключению

Sport Line API предоставляет актуальные спортивные данные для сайта, приложения или другого программного продукта клиента.

Официальный сайт: sportapi.net.

Поддержка в Telegram: @suport_sportapi.

Содержание

1. Что предоставляет Sport Line API
2. Что необходимо для подключения
3. Как выполнить первый запрос
4. Основная последовательность интеграции
5. Prematch и Live
6. Какие данные возвращаются
7. Дополнительные методы
8. Готовые иконки
9. Обновление данных
10. Live 3D Tracker
11. Видеотрансляции
12. Обработка ошибок
13. Примеры интеграции
14. Подробная документация
15. Поддержка

1. Что предоставляет Sport Line API

С помощью Sport Line API Вы можете получать:

• доступные виды спорта;
• страны, турниры и чемпионаты;
• предстоящие матчи Prematch;
• матчи, которые проходят в Live;
• команды или участников матча;
• время начала, текущий счёт, период и таймер;
• краткий список основных коэффициентов в списке матчей;
• полный список групп ставок и коэффициентов выбранного матча;
• субматчи: таймы, угловые, карточки, фолы и другие дополнительные события;
• основные показатели Live-статистики;
• информацию о наличии Live 3D Tracker и видеотрансляции.

Sport Line API работает через REST API. Для получения актуальных данных Ваше приложение выполняет обычные HTTP-запросы.

Подключение через WebSocket находится в разработке и пока недоступно для рабочей интеграции.

2. Что необходимо для подключения

Чтобы подключить Sport Line API, Вам необходимо:

1. Написать менеджеру SportAPI в Telegram и сообщить, что Вы хотите подключить спортивную линию.
2. Получить у менеджера базовый URL API и персональный ключ доступа.
3. Уточнить, какие виды спорта и языки входят в Ваш тариф.
4. Сохранить ключ в защищённых настройках backend-приложения.
5. Передавать ключ в HTTP-заголовке Package при каждом запросе.

Базовый URL может отличаться для разных подключений. Во всех примерах замените https://YOUR_API_DOMAIN на адрес, полученный от менеджера.

Ключ передаётся так:

Package: YOUR_API_KEY

Не добавляйте ключ в URL и не размещайте его в браузерном JavaScript, мобильном приложении, публичном репозитории или сообщениях об ошибках. Рекомендуется выполнять запросы к Sport Line API через backend клиента.

Доступные виды спорта, языки и срок действия определяются тарифом Вашего ключа.

Подробно: «Авторизация и доступ».

3. Как выполнить первый запрос

Для проверки подключения запросите Live-меню:

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

В этом запросе:

• live означает текущие Live-матчи;
• ru означает русский язык ответа;
• Package — HTTP-заголовок с Вашим API-ключом.

Успешный ответ имеет общую оболочку:

{
  "status": 1,
  "page": "/v1/menu",
  "body": [
    {
      "id": 1,
      "name": "Футбол",
      "counter": 53,
      "sub": []
    }
  ]
}

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

Подробно: «Быстрый старт».

4. Основная последовательность интеграции

Для основной интеграции используйте следующую цепочку:

menu → events → event

Шаг 1. Получите актуальное меню

GET /v1/menu/{type}/{lang}

Метод menu за один запрос возвращает доступную структуру:

вид спорта → страна → турнир

Из ответа выберите актуальные sportId и tournamentId.

Подробно: menu — меню спортивной линии.

Шаг 2. Получите список матчей

GET /v1/events/{sportId}/{tournamentId}/sub/50/{type}/{lang}

Для метода events:

• используйте только формат sub;
• передавайте 50 в обязательном сегменте count;
• передайте ID конкретного турнира или tournamentId=0, чтобы получить матчи всех турниров выбранного вида спорта.

Параметр count больше не ограничивает количество результатов. Значение 50 сохранено в URL для совместимости, а API возвращает все доступные матчи выбранной выборки.

Ответ группируется по турнирам:

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

В game_oc_list каждого матча находится краткий список основных коэффициентов. Состав этого списка зависит от вида спорта. Например, в футболе может использоваться группа 1X2, в баскетболе — победа первой или второй команды, а в теннисе нет исхода на ничью.

Не привязывайте интерфейс к одному постоянному набору названий исходов. Читайте фактические группы и коэффициенты из ответа.

Подробно: events — список матчей.

Шаг 3. Получите подробные данные матча

Возьмите game_id выбранного матча из ответа events и выполните запрос:

GET /v1/event/{gameId}/group/{type}/{lang}

Для метода event используется только формат group. API уже:

• распределяет исходы по группам ставок;
• формирует колонки внутри групп;
• сортирует исходы по значениям.

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

Метод event возвращает полный доступный список коэффициентов выбранного матча, его субматчи, Live-статистику и другие подробные данные.

Подробно: event — конкретный матч.

Используйте только актуальные ID

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

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

Перед запросом events проверяйте, что выбранные sportId и tournamentId всё ещё присутствуют в актуальном меню того же типа live или line.

5. Prematch и Live

Sport Line API разделяет данные на два типа:

Prematch- и Live-данные нужно запрашивать и хранить отдельно.

Когда матч переходит из Prematch в Live, для него создаётся новый game_id. Live-ID не совпадает с Prematch-ID, поэтому не связывайте две версии матча по game_id.

Если матч больше недоступен по прежнему ID, метод event может вернуть:

{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game id finished"
  }
}

Это сообщение не объясняет причину. Матч мог перейти в Live с новым ID, быть отменён или исчезнуть из линии по другой причине. После такого ответа прекратите запрашивать старый game_id и обновите актуальное меню и список матчей.

6. Какие данные возвращаются

Матч

Объект матча может содержать:

• game_id — ID матча для метода event;
• game_start — время начала в формате Unix Timestamp, в секундах;
• данные вида спорта, страны и турнира;
• названия и ID команд или участников;
• счёт, период и таймер Live-матча;
• группы ставок и коэффициенты;
• статистику и субматчи;
• поля трекера и видео, если они доступны.

Поле timer передаётся в секундах. Для отображения минут разделите значение на 60 и при необходимости округлите его для интерфейса. Не отправляйте запрос каждую секунду только для обновления таймера: изменяйте отображение локально и синхронизируйте его при следующем плановом запросе.

Подробно: «Модель данных: матч».

Коэффициенты

Структура коэффициентов выглядит так:

game_oc_list
└── группа ставок
    └── oc_list
        └── колонка
            └── исходы и коэффициенты

Основные поля одного исхода:

Если подключена отдельная система приёма и расчёта ставок, именно oc_pointer используется для передачи выбранного исхода в эту систему. Формат передачи описан на странице «Указатель ставки», а следующий запрос — в разделе «Создание купона».

Подробно: «Коэффициенты и группы ставок».

Субматчи

Субматчи — это отдельные события внутри основного матча. Например:

• первый тайм;
• угловые;
• угловые первого тайма;
• жёлтые карточки;
• фолы;
• другие дополнительные линии.

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

Коэффициенты ответа относятся только к выбранному субматчу. Например, при запросе «Угловые первого тайма» API возвращает коэффициенты только на угловые первого тайма, а не на весь матч и не на все угловые матча.

Подробно: «Дополнительные матчи и субматчи».

Live-статистика

Основная Live-статистика находится в stat_list и возвращается только для Live:

• в списке матчей events;
• в подробном ответе конкретного матча event.

Набор показателей зависит от вида спорта и конкретного матча. Это основные текущие характеристики Live-матча, а не отдельное API подробной спортивной аналитики.

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

Подробно: «Статистика матча».

Полная таблица JSON-полей находится в «Едином справочнике полей Sport Line API».

7. Дополнительные методы

Дополнительные методы не являются обязательной частью основной интеграции. Используйте их только в том случае, если соответствующая возможность нужна Вашему проекту.

Основная рекомендуемая цепочка остаётся прежней:

menu → events → event

Обычно лучше использовать menu, потому что он за один запрос возвращает виды спорта, страны и турниры. Цепочка sports → countries → tournaments требует трёх запросов и предназначена для отдельных сценариев интерфейса.

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

?cybersport=true

Не выполняйте все дополнительные запросы автоматически только потому, что они существуют в API.

8. Готовые иконки

SportAPI предоставляет стандартные иконки. Подставьте актуальное значение из ответа API в соответствующий URL:

Для команды или участника используйте opp_1_icon или opp_2_icon. Перед подстановкой в {iconName} уберите исходное расширение файла, если оно присутствует.

9. Обновление данных

Каждый REST-запрос возвращает снимок данных на момент обращения. Чтобы получать изменения счёта, периода, статистики и коэффициентов, повторяйте запросы с рекомендуемым интервалом.

Интервал «не менее 5 секунд» означает, что запрос не нужно отправлять чаще одного раза в 5 секунд. Если менеджер предоставил другие интервалы для Вашего подключения, используйте значения менеджера.

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

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

10. Live 3D Tracker

Live 3D Tracker — это отдельный готовый виджет визуализации Live-матча. Sport Line API не передаёт данные для самостоятельной отрисовки трекера. Он возвращает ID готового виджета в поле zp.

gameid трекера = zp из Sport Line API

Если zp равен null, трекер для этого матча недоступен. Не подставляйте вместо zp значение game_id или другой идентификатор.

Трекер можно показывать только для Live-матча, если:

• zp заполнен;
• вид спорта поддерживается трекером;
• у клиента есть активный ключ трекера;
• домен клиента разрешён для этого ключа;
• вид спорта и язык входят в тариф.

Поддерживаемые виды спорта:

Наличие вида спорта в таблице не гарантирует наличие трекера у каждого матча. Окончательная проверка всегда выполняется по zp.

Готовый виджет подключается прямым iframe или через embed.js.

• Краткое описание связи Sport Line API с трекером
• Полная инструкция по подключению Live 3D Tracker
• Задание для ИИ-агента по интеграции Tracker
• Демонстрация внешнего вида

Демонстрационная страница показывает внешний вид и не использует реальные Live-данные.

11. Видеотрансляции

Sport Line API показывает наличие видеотрансляции Live-матча с помощью двух полей:

Значение va: 0 не используется. Даже если vi содержит только цифры, сохраняйте его как строку.

Показывайте видео только при va: 1 и заполненном vi. Само значение vi не является URL видеопотока или готовым адресом iframe: оно передаётся в отдельный готовый видеовиджет.

Видео доступно только для части Live-матчей. SportAPI не транслирует матчи топовых спортивных лиг. Не обещайте наличие видео для конкретного соревнования или матча до проверки актуальных va и vi.

Подробно: «Видеотрансляции в Sport Line API».

12. Обработка ошибок

Ошибка API обычно возвращается в формате:

{
  "error_code": 100,
  "error_message": "Invalid Package"
}

Проверяйте наличие error_code и error_message, а не только HTTP-статус.

Пустой массив body: [] не всегда является ошибкой. Он может означать, что в текущей выборке сейчас нет доступных данных.

Подробно: «Обработка ошибок».

13. Примеры интеграции

Готовые примеры используют вымышленные ключи и базовые URL:

• cURL
• JavaScript для Node.js
• Python
• PHP

Это лёгкие рабочие примеры интеграции, а не готовые SDK. Они показывают авторизацию, основную цепочку menu → events → event и обработку ответов.

Полные реальные JSON-ответы без API-ключей: «Проверочные ответы Sport Line API».

14. Подробная документация

Начало работы

• Быстрый старт
• Авторизация и доступ
• Основные понятия
• Рекомендации по обновлению
• Обработка ошибок

Основные методы

• menu
• events
• event

Модели данных

• Общий формат ответа
• Матч
• Коэффициенты и группы ставок
• Статистика матча
• Дополнительные матчи и субматчи
• Единый справочник полей

15. Поддержка

Если запрос не работает, отправьте менеджеру:

• URL запроса без API-ключа;
• время выполнения запроса;
• HTTP-статус;
• error_code и error_message;
• используемые тип линии, язык и ID;
• пример кода без секретных данных.

Не отправляйте API-ключ в общий чат или публичную задачу.

• Поддержка SportAPI: @suport_sportapi
• Официальный сайт: sportapi.net