API

Публичное JSON API для виджетов, сайтов групп и интеграций

Общие сведения

Методы Group API отдают данные в формате JSON. В пути используется slug группы — тот же, что в адресе страницы группы на сайте.

https://esya.ru/api/group/groupSlug/…
  • Ответ всегда JSON (Content-Type: application/json).
  • Параметр groupSlug — публичный идентификатор группы (тот же, что в адресе страницы группы).
  • Публичные GET-методы кэшируются; для актуальных данных при необходимости учитывайте Cache-Control.

Group API

GET /api/group/{groupSlug}/events

Каталог мероприятий

Список публичных мероприятий группы со сводными счётчиками: участники, отзывы, фотографии. Курсорная пагинация по 25 записей. Полные отзывы и фото — в карточке мероприятия.

Параметры

Имя Где Описание
groupSlug path Slug группы.
cursor query Курсор следующей страницы из поля nextCursor предыдущего ответа.
year query Опциональный год (фильтр по дате старта мероприятия).

В ответе: limit, hasMore, nextCursor. Для следующей страницы передайте cursor=nextCursor. В каждом элементе есть поле api со ссылкой на детальную карточку.

GET /api/group/{groupSlug}/events/next

Ближайшее / актуальное мероприятие

Возвращает текущее релевантное мероприятие группы: идущее сейчас, недавно завершённое (до 8 часов) или ближайшее запланированное. В ответе — описание, дистанция, ссылки, карта, тип поездки, сложность, статус, контакты и прогресс по маршруту.

Параметры

Имя Где Описание
groupSlug path Slug группы.

Поля authenticated и canProtocol зависят от авторизации трекера. Пока мероприятие in_progress, кэш ответа отключается.

GET /api/group/{groupSlug}/events/{slug}

Карточка мероприятия

Полные данные мероприятия: описание, маршрут, участники, отзывы и фотографии с CDN (thumb / medium / large).

Параметры

Имя Где Описание
groupSlug path Slug группы.
slug path Slug мероприятия (event).

Возвращает ошибку, если мероприятие не найдено или недоступно в публичном списке.

GET /api/group/{groupSlug}/photos

Последние фотографии

До 100 последних фотографий группы (по дате съёмки или загрузки) со ссылками на CDN и краткими данными мероприятия.

Параметры

Имя Где Описание
groupSlug path Slug группы.

Нужно настроенное S3-хранилище группы. URL изображений: https://i.esya.ru/thumb|medium|large/HASH.webp.

GET /api/group/{groupSlug}/photos/random

Случайные фотографии

До 20 случайных фотографий группы. Можно ограничить выборку годом мероприятия.

Параметры

Имя Где Описание
groupSlug path Slug группы.
year query Опциональный год (фильтр по дате старта мероприятия).

Нужно настроенное S3-хранилище группы. URL изображений: https://i.esya.ru/thumb|medium|large/HASH.webp.

GET /api/group/{groupSlug}/photo

Одна случайная фотография

Одна случайная фотография группы за указанный год — удобно для виджетов и фонов.

Параметры

Имя Где Описание
groupSlug path Slug группы.
year query Год (по умолчанию текущий).

Нужно настроенное S3-хранилище группы. URL изображений: https://i.esya.ru/thumb|medium|large/HASH.webp.

Ошибки

При ошибке API возвращает JSON вида:

{
  "status": "error",
  "message": "…"
}