Разработчикам

API мероприятий для вашего сайта

Встройте публичные мероприятия вашего коллектива на собственный сайт — простым HTTP-запросом, без аккаунта и без API-ключа.

Самое важное

•Публичный доступ, аутентификация не нужна.
•CORS включён, эндпоинт работает прямо из браузера.
•Ответы кэшируются на 5 минут, лимит запросов: 60 в минуту.
•Отдаются только те данные, которые вы разрешили показывать публично в настройках сайта.
•При публичном использовании обязательно указание «Powered by Chorilo» со ссылкой на наш сайт.

Powered by Chorilo — пометка на вашей странице

Если вы используете API на публичной странице, добавьте, пожалуйста, на видное место пометку «Powered by Chorilo» со ссылкой на https://www.chorilo.com. Вполне достаточно ненавязчивой строки в подвале.

Обмен честный: вы автоматически встраиваете свои мероприятия в другие системы и не ведёте их дважды. Но каждый запрос к API создаёт у нас нагрузку на сервер и расходы на инфраструктуру: чем больше посетителей на вашем сайте, тем больше ресурсов это занимает. В ответ Chorilo получает благодаря небольшой пометке немного внимания, которое помогает нам находить новые хоры.

HTML

<a href="https://www.chorilo.com" target="_blank" rel="noopener">
  Powered by Chorilo
</a>

Предпросмотр

Эндпоинт

Один GET-эндпоинт возвращает ближайшие мероприятия вашего коллектива. Замените на URL-slug вашего публичного сайта Chorilo.

Где найти мой slug?

Откройте в Chorilo настройки вашего публичного сайта. Slug — это уникальная часть URL, например «mein-chor» в https://www.chorilo.com/w/mein-chor.

GET

https://backend.chorilo.com/api/public-websites/{slug}/embed-events

Управление видимостью

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

Главный переключатель: Если show_events отключён, API возвращает пустой список.

Типы мероприятий: Отдаются только разрешённые типы. Запрос закрытых типов (например, types[]=concert при отключённом показе концертов) молча отфильтровывается.

Настройка	Относится к типу
show_events	Главный переключатель (отключает всё)
show_rehearsals	`rehearsal`
show_concerts	`concert`, `church_service`
show_other_events	`event`
show_event_descriptions	Управляет полем description в ответе

Query-параметры

Все параметры необязательны. Без параметров эндпоинт возвращает ближайшие мероприятия согласно стандартным настройкам вашего сайта.

Имя	Тип	По умолчанию	Описание
limit	integer	5	Количество возвращаемых мероприятий. Минимум 1, максимум 100.
from	ISO 8601	сейчас	Начало периода. Прошедшие мероприятия по умолчанию не отдаются.
to	ISO 8601	—	Конец периода.
types[]	array	все разрешённые	Один или несколько типов: rehearsal, concert, event. Закрытые типы молча отфильтровываются.
lang	string (2)	—	Двухбуквенный код языка (de, en, fr, nl, es, sv, it, sl). Сейчас возвращается как эхо в мета-данных ответа.

Лимит запросов и кэширование

Эндпоинт ограничен 60 запросами в минуту на один IP-адрес. При превышении лимита сервер отвечает HTTP 429.

Ответы кэшируются на сервере на 5 минут (для каждой комбинации параметров). Новые мероприятия могут появляться с небольшой задержкой.

Лимит запросов

60 / min

на один IP-адрес

Серверный кэш

5 min

для каждой комбинации параметров

Формат ответа

Ответ — это JSON-объект. Каждое мероприятие содержит только публичные поля: внутренние описания, данные участников и другая конфиденциальная информация никогда не отдаются.

events[] — Список мероприятий с полями id, title, type, location, start_time, end_time, has_ticket_sale, а также необязательными ticket_sale_url (при активной продаже билетов) и description.
ensemble_name — Отображаемое название вашего коллектива.
theme_color — Hex-код цвета из настроек сайта.
language — Код языка вашего сайта.

Поле description содержит только публичное описание. Внутреннее описание мероприятия никогда не входит в ответ.

JSON

{
  "events": [
    {
      "id": 42,
      "title": "Sommerkonzert",
      "type": "concert",
      "location": "Stadthalle Musterstadt",
      "start_time": "2026-06-14T19:30:00+02:00",
      "end_time": "2026-06-14T21:30:00+02:00",
      "description": "Ежегодный летний концерт в саду городского дома культуры.",
      "has_ticket_sale": true,
      "ticket_sale_url": "https://www.chorilo.com/shop/tickets/42"
    }
  ],
  "ensemble_name": "Musterchor",
  "theme_color": "#6366f1",
  "language": "de"
}

Примеры

Так вызывать API из разных языков. Пример загружает до 10 ближайших концертов и других мероприятий.

curl "https://backend.chorilo.com/api/public-websites/mein-chor/embed-events?limit=10&types[]=concert&types[]=event"

Коды состояния

Код	Значение
200	Успешно, мероприятия в массиве events.
404	Сайт с таким slug не найден.
422	Недопустимые query-параметры (например, неизвестный тип или to раньше from).
429	Лимит запросов превышен, повторите через минуту.

All public endpoints

These are the read-only public endpoints currently exposed. No authentication required. JSON responses only.

Method	Path	Description	Limit
GET	/api/tickets/events	List public concert events	90/min
GET	/api/tickets/events/{eventId}	Single event detail	90/min
GET	/api/public-websites/{slug}	Public ensemble website by slug	90/min
GET	/api/public-websites/{slug}/embed-events	Embeddable concert calendar	60/min
GET	/api/public-websites/{slug}/calendar.ics	Public events as iCal feed for calendar subscriptions	300/min
GET	/api/choir-associations/public	Public association directory	90/min

Rate-limit response headers

Every /api/* response carries rate-limit headers. They are exposed via Access-Control-Expose-Headers for cross-origin agents.

X-RateLimit-Limit — per-window quota
X-RateLimit-Remaining — remaining requests
Retry-After — seconds to wait (HTTP 429 only)

JSON error format (RFC 9457)

All /api/* errors return application/problem+json regardless of Accept header.

{
  "type":     "https://www.chorilo.com/api/errors/not-found",
  "title":    "Resource not found",
  "status":   404,
  "detail":   "...",
  "instance": "/api/tickets/events/99999999"
}

Validation errors (422) include an errors object mapping fields to messages.

Есть вопросы?

По техническим вопросам об API обращайтесь: support@chorilo.com