Интеграции

Как подключить TopHeats API v1

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

7 мин чтения Обновлено: 05.11.2026

TopHeats API позволяет показывать на вашем сайте опубликованные соревнования и сохранённые итоговые результаты. Отправляйте запросы методом GET по HTTPS с сервера вашего сайта. Ответы приходят в JSON.

Снимок экрана — 2026-11-06 в 01.45.43.png

Получите ключ

Запросите ключ у администратора TopHeats. Укажите нужные виды спорта и соревнования. Для этой интеграции нужны разрешения sports, events и results. Администратор задаст права, лимит запросов и срок действия ключа.

Храните ключ на сервере, например в переменной окружения TOPHEATS_API_KEY. Исключите ключ из URL, браузерного JavaScript, репозитория и журналов. В каждом запросе передавайте заголовок Authorization: Bearer <ключ>.

Отправьте первый запрос в Postman

  1. Скачайте коллекцию TopHeats API v1. В Postman нажмите Import и выберите скачанный JSON-файл.

    Кнопка Import в Postman

  2. В боковой панели выберите коллекцию TopHeats API v1 и откройте вкладку Variables. В столбце Value укажите свои значения.

    • base_url — https://topheats.ru/api/v1 для русской версии статьи и https://topheats.com/api/v1 для английской.
    • event_id — ID вашего соревнования из адреса его страницы. Например, в адресе /events/272 это 272.
    • sport_id — ID вашего вида спорта из ответа на GET {{base_url}}/sports?locale=ru. Заполните его после запроса List sports в шаге 4.
  3. Нажмите Vault и откройте Local Vault. При первом запуске Postman предложит настроить хранилище. Введите topheats-api-key в Key и полученный ключ в Value. В Allowed domains укажите домен из base_url — topheats.ru или topheats.com.

    Кнопка Vault в Postman

    Поля Key, Value и Allowed domains в Local Vault перед указанием домена

  4. Откройте List sports и нажмите Send. При ответе 200 OK найдите нужный вид спорта в массиве data. Скопируйте его id и вставьте в sport_id на вкладке Variables.

    Кнопка Send в запросе List sports

Если выбираете соревнование через List events, возьмите его id из data.items и внесите в event_id. При необходимости включите фильтры from и to на вкладке Params и укажите свой диапазон дат.

Загрузите соревнования и результаты

В примерах используется соревнование TSK Surf Series no.4 '26 на локальном стенде. Чтобы повторить выборку, попросите ключ стенда с разрешениями sports, events и results для вида спорта 10 и доступом только к соревнованию 272.

Для запуска примера в Postman укажите https://topheats.ru/api/v1 в base_url, 10 в sport_id и 272 в event_id. Для секрета topheats-api-key используйте ключ стенда. 

1. Получите виды спорта

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

TOPHEATS_API_URL='http://localhost:3000/api/v1'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/sports?locale=ru"

2. Получите список соревнований

Возьмите id вида спорта из /sports. В примере это 10 (Surfing). Параметры from и to задают включительные границы даты начала соревнования. Здесь они охватывают 17 октября 2026 года по UTC. Параметр locale=ru запрашивает русские названия.

SPORT_ID='10'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events?sport_id=$SPORT_ID&from=2026-10-17T00:00:00Z&to=2026-10-17T23:59:59.999Z&locale=ru&page=1&limit=20"

Читайте соревнования из data.items. Начните с page=1 и увеличивайте page, пока data.page × data.limit < data.total. Сохраняйте те же фильтры и размер страницы. limit может быть от 1 до 100.

3. Откройте карточку соревнования

Возьмите id соревнования из data.items. В примере это 272.

EVENT_ID='272'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events/$EVENT_ID?locale=ru"

Карточка содержит данные соревнования и до 1000 дивизионов в data.divisions. Полный протокол загружайте через /results.

4. Получите итоговые результаты

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events/$EVENT_ID/results?locale=ru&page=1&limit=2&result_page=1&result_limit=1"
  • Дивизионы. Перебирайте page по data.page, data.limit и data.total, как в списке соревнований. В примере четыре дивизиона, по два на страницу. Оставляйте result_page=1 при переходе к следующей странице дивизионов. Максимум — 20 дивизионов на страницу.
  • Спортсмены. У каждого дивизиона своя пагинация в results. Если results.page × results.limit < results.total, запросите следующую result_page с division_id этого дивизиона и page=1. Оставьте тот же result_limit, до 100 спортсменов на страницу. Повторяйте до конца списка спортсменов в этом дивизионе.

На второй странице дивизионов найдите Men's Open с id 803. Следующий запрос вернёт вторую страницу спортсменов этого дивизиона. При result_limit=1 на ней одна строка.

DIVISION_ID='803'

curl --fail-with-body \
  -H "Authorization: Bearer $TOPHEATS_API_KEY" \
  "$TOPHEATS_API_URL/events/$EVENT_ID/results?locale=ru&division_id=$DIVISION_ID&page=1&limit=2&result_page=2&result_limit=1"

Прочитайте результат

API выдаёт сохранённые строки итогового протокола с местом и рангом. В примере result.value содержит 11,06 балла за выступление, а rating_points — 800 рейтинговых очков.

Пример ответа на последний запрос составлен по сохранённому протоколу. Данные спортсмена обезличены. Значения generated_at и request_id приведены для примера.

{
  "data": {
    "event_id": "272",
    "items": [
      {
        "id": "803",
        "name": "Men's Open",
        "gender": "male",
        "age_from": null,
        "age_to": null,
        "discipline": {"id": "101", "name": "Короткая доска"},
        "scoring": {"max_score": null, "lower_is_better": false, "result_mode": "advancement"},
        "results": {
          "items": [
            {"athlete": {"id": "athlete_2", "name": "Спортсмен", "avatar_url": null, "profile_url": null}, "place": 2, "rank": 2, "rating_points": 800, "result": {"value": 11.06, "unit": "points", "display": "11.06", "status": "recorded"}}
          ],
          "total": 13,
          "page": 2,
          "limit": 1
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 2
  },
  "generated_at": "2026-11-05T21:54:51.061Z",
  "request_id": "0123456789abcdef01234567"
}

Для вывода на сайт используйте result.display. В result.unit баллы обозначены как points, секунды — seconds, количество повторений — count. Для результата в ноль баллов API вернёт "value": 0, "display": "0" и "status": "recorded". При отсутствии результата value и display равны null, а статус — no_result.

Настройте регулярное обновление

В каждом ответе generated_at показывает время его формирования. Запускайте обновление по расписанию на своём сервере и каждый раз заново обходите все страницы нужной выборки.

  1. Соберите свежие данные отдельно от текущей копии. Сопоставляйте соревнования по id, дивизионы — по ID соревнования и дивизиона, строки результатов — по ID соревнования, дивизиона и athlete.id. Храните ID как строки.
  2. Если данные изменились во время обхода, повторите сверку. Страницы читаются в разное время.
  3. После успешного полного обхода обновите копию и уберите соревнования, дивизионы и результаты, которые перестали возвращаться в той же выборке. Если запрос завершился ошибкой, сохраните текущую копию и завершите сверку после восстановления доступа.

Диагностика ошибок

Лимит задаётся на ключ и суммируется по всем маршрутам за календарную минуту UTC. При 429 заголовок Retry-After сообщает, сколько секунд осталось до следующей минуты. При временной блокировке ключа (403) он показывает время до разблокировки в секундах.

HTTP и error.code Что проверить
400 invalid_parameter Сверьте имена, значения и формат параметров. Каждый параметр передавайте один раз.
401 invalid_api_key Проверьте заголовок Authorization, значение ключа, срок действия и отзыв.
403 scope_forbidden, sport_forbidden, api_key_blocked Проверьте права ключа на маршрут и вид спорта. При временной блокировке подождите Retry-After секунд.
404 endpoint_not_found, event_not_found, division_not_found Проверьте путь и ID. Соревнование может быть недоступно по этому ключу.
405 method_not_allowed Используйте метод GET.
429 rate_limit_exceeded Подождите Retry-After секунд и повторите запрос.
500 internal_error Повторите запрос позже. Если ошибка сохраняется, передайте request_id администратору TopHeats.

request_id помогает найти конкретный запрос при диагностике. При обращении передайте его вместе с HTTP-статусом и кодом ошибки.

Не нашли ответ?

Напишите нам. Поможем разобраться и дополним документацию вашим вопросом.

Связаться с поддержкой