---
id: update-guidelines
title: Sport Line API — рекомендации по обновлению данных
description: Рекомендации по частоте запросов и обновлению спортивного меню, матчей, коэффициентов и Live-данных.
version: v1
language: ru
---

# Sport Line API — рекомендации по обновлению данных


## Зачем нужно обновлять данные

Sport Line API работает через REST API. Каждый запрос возвращает актуальный на
этот момент снимок данных.

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

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

## Рекомендуемые интервалы

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

| Данные или методы | Live | Prematch (`line`) |
|---|---:|---:|
| Полное меню: `menu` | не менее 20 секунд | не менее 60 секунд |
| Пошаговая навигация: `sports`, `countries`, `tournaments` | не менее 60 секунд | не менее 120 секунд |
| Список матчей: `events` | не менее 7 секунд | не менее 30 секунд |
| Конкретный матч: `event` | не менее 5 секунд | не менее 30 секунд |
| Топ-матчи: `topmatches` | не менее 30 секунд | не менее 120 секунд |
| Топ-матчи выбранного спорта: `toplist` | не используется | не менее 120 секунд |

Метод выборки Prematch-матчей за период пока не готов для клиентской интеграции и не
должен использоваться до исправления и утверждения контракта.

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

## Меню и список матчей обновляются по-разному

Меню изменяется реже, чем счёты и коэффициенты. Поэтому не нужно запрашивать `menu`
каждые 5 секунд.

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

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

## Не обновляйте таймер запросом каждую секунду

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

1. Получите значение `timer` из API.
2. Обновляйте отображаемый таймер локально в интерфейсе.
3. При следующем плановом запросе синхронизируйте таймер с новым значением API.

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

## Жизненный цикл матча

Матч может перейти из prematch-линии в live-линию. При этом для live-матча
формируется новый `game_id`, который не совпадает с `game_id` этого матча в prematch-линии.

Поэтому не следует связывать prematch- и live-матчи по `game_id`. Sport Line API не возвращает
отдельный статус, по которому можно точно определить, что prematch-матч начался и был
перенесён в live.

Когда матч больше недоступен в текущей линии, запрос `event` по его прежнему `game_id`
может вернуть:

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

Это сообщение не объясняет причину. Матч мог перейти в live с новым `game_id`, быть отменён
или исчезнуть из линии по другой причине. Отдельные статусы для этих случаев API не
возвращает.

Приложение должно:

1. Обновлять prematch- и live-данные отдельно.
2. Не связывать prematch- и live-матчи по `game_id`.
3. Получать актуальные live-матчи из метода `events` с типом `live`.
4. Прекращать запросы `event` по ID, для которого получено `Game id finished`.
5. Не определять по `Game id finished`, был ли матч начат, завершён или отменён.

## Рекомендация по повторным запросам при ошибках

Этот раздел содержит общую рекомендацию для клиентского приложения. Это не требование и не
правило Sport Line API.

При неудачном запросе рекомендуется делать паузу перед повтором.

Для временной сетевой ошибки или ошибки сервера можно постепенно увеличивать задержку:

```text
5 секунд → 10 секунд → 20 секунд → 40 секунд
```

После успешного ответа можно вернуться к обычному интервалу.

Обычно не стоит автоматически повторять ошибки, которые не исчезнут без изменения запроса:

- неверный или просроченный API-ключ;
- недоступный язык;
- вид спорта, не входящий в тариф;
- неверные параметры URL.

Подробнее: [«Обработка ошибок»](error-handling.md).

## Не допускайте наложения запросов

Если предыдущий запрос ещё не завершился, не запускайте второй запрос тех же данных.

Безопасный цикл обновления выглядит так:

```text
отправить запрос
        ↓
дождаться ответа или ошибки
        ↓
обработать данные и обновить интерфейс
        ↓
выждать нужный интервал
        ↓
отправить следующий запрос
```

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

## Короткий чек-лист

1. Соблюдайте рекомендуемые интервалы для каждого метода.
2. Не запрашивайте меню чаще, чем список матчей.
3. Не запрашивайте подробный `event` для каждого матча.
4. Обновляйте prematch- и live-данные отдельно.
5. Не запускайте новый запрос, пока не завершился предыдущий.
6. При временных ошибках рекомендуется увеличивать паузу между повторами.
7. Прекращайте частое обновление завершённых матчей.

Следующий шаг: описание метода `menu`.
