TopHeats API позволяет показывать на вашем сайте опубликованные соревнования и сохранённые итоговые результаты. Отправляйте запросы методом GET по HTTPS с сервера вашего сайта. Ответы приходят в JSON.
Получите ключ
Запросите ключ у администратора TopHeats. Укажите нужные виды спорта и соревнования. Для этой интеграции нужны разрешения sports, events и results. Администратор задаст права, лимит запросов и срок действия ключа.
Храните ключ на сервере, например в переменной окружения TOPHEATS_API_KEY. Исключите ключ из URL, браузерного JavaScript, репозитория и журналов. В каждом запросе передавайте заголовок Authorization: Bearer <ключ>.
Отправьте первый запрос в Postman
-
Скачайте коллекцию TopHeats API v1. В Postman нажмите Import и выберите скачанный JSON-файл.

-
В боковой панели выберите коллекцию 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.
-
Нажмите Vault и откройте Local Vault. При первом запуске Postman предложит настроить хранилище. Введите
topheats-api-keyв Key и полученный ключ в Value. В Allowed domains укажите домен изbase_url—topheats.ruилиtopheats.com.

-
Откройте List sports и нажмите Send. При ответе
200 OKнайдите нужный вид спорта в массивеdata. Скопируйте егоidи вставьте вsport_idна вкладке Variables.
Если выбираете соревнование через 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 показывает время его формирования. Запускайте обновление по расписанию на своём сервере и каждый раз заново обходите все страницы нужной выборки.
- Соберите свежие данные отдельно от текущей копии. Сопоставляйте соревнования по
id, дивизионы — по ID соревнования и дивизиона, строки результатов — по ID соревнования, дивизиона иathlete.id. Храните ID как строки. - Если данные изменились во время обхода, повторите сверку. Страницы читаются в разное время.
- После успешного полного обхода обновите копию и уберите соревнования, дивизионы и результаты, которые перестали возвращаться в той же выборке. Если запрос завершился ошибкой, сохраните текущую копию и завершите сверку после восстановления доступа.
Диагностика ошибок
Лимит задаётся на ключ и суммируется по всем маршрутам за календарную минуту 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-статусом и кодом ошибки.