Programiści

API wydarzeń dla Twojej strony

Osadź publiczne wydarzenia swojego zespołu na własnej stronie internetowej – prostym zapytaniem HTTP, bez konta i bez klucza API.

Najważniejsze na początek

•Publicznie dostępne, nie wymaga uwierzytelniania.
•CORS jest włączony, punkt końcowy działa bezpośrednio z przeglądarki.
•Odpowiedzi są buforowane przez 5 minut, limit zapytań to 60 na minutę.
•Udostępniane są tylko dane, które w ustawieniach strony zostały zatwierdzone do publicznego wyświetlania.
•Przy użyciu publicznym obowiązkowa jest informacja „Powered by Chorilo” z linkiem do naszej strony.

Powered by Chorilo — informacja na Twojej stronie

Jeśli używasz API na publicznej stronie, dodaj w widocznym miejscu informację „Powered by Chorilo” z linkiem do https://www.chorilo.com. Dyskretny wiersz w stopce w zupełności wystarczy.

Wymiana jest uczciwa: automatycznie osadzasz swoje wydarzenia w innych systemach i nie musisz ich podwójnie prowadzić. Każde zapytanie do API obciąża jednak nasze serwery i generuje koszty infrastruktury – im więcej odwiedzających ma Twoja strona, tym więcej zasobów to zajmuje. W zamian Chorilo zyskuje dzięki tej małej informacji nieco uwagi, która pomaga nam docierać do nowych chórów.

HTML

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

Podgląd

Punkt końcowy

Jeden punkt końcowy GET zwraca nadchodzące wydarzenia Twojego zespołu. Zastąp slugiem URL swojej publicznej strony Chorilo.

Gdzie znajdę swój slug?

Otwórz w Chorilo ustawienia swojej publicznej strony. Slug to unikalna część adresu URL, na przykład „moj-chor” w https://www.chorilo.com/w/moj-chor.

GET

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

Kontrola widoczności

API respektuje ustawienia widoczności Twojej publicznej strony. Wszystko, co jest ukryte na stronie, jest zablokowane także w API – nawet jeśli zostanie wyraźnie zażądane.

Przełącznik główny: Jeśli show_events jest wyłączone, API zwraca pustą listę.

Typy wydarzeń: Zwracane są tylko zatwierdzone typy. Zapytanie o zablokowane typy (na przykład types[]=concert przy wyłączonym wyświetlaniu koncertów) jest po cichu filtrowane.

Ustawienie	Dotyczy typu
show_events	Przełącznik główny (wyłącza wszystko)
show_rehearsals	`rehearsal`
show_concerts	`concert`, `church_service`
show_other_events	`event`
show_event_descriptions	Steruje polem description w odpowiedzi

Parametry zapytania

Wszystkie parametry są opcjonalne. Bez parametrów punkt końcowy zwraca najbliższe wydarzenia zgodnie z ustawieniami domyślnymi Twojej strony.

Nazwa	Typ	Domyślnie	Opis
limit	integer	5	Liczba zwracanych wydarzeń. Minimum 1, maksimum 100.
from	ISO 8601	teraz	Moment rozpoczęcia zakresu. Minione wydarzenia nie są domyślnie zwracane.
to	ISO 8601	—	Moment zakończenia zakresu.
types[]	array	wszystkie dozwolone	Jeden lub kilka typów: rehearsal, concert, event. Zablokowane typy są po cichu filtrowane.
lang	string (2)	—	Dwuliterowy kod języka (de, en, fr, nl, es, sv, it, sl). Jest obecnie zwracany jako echo w metadanych odpowiedzi.

Limit zapytań i buforowanie

Punkt końcowy jest ograniczony do 60 zapytań na minutę na adres IP. Po przekroczeniu limitu serwer odpowiada kodem HTTP 429.

Odpowiedzi są buforowane po stronie serwera przez 5 minut (dla każdej kombinacji parametrów). Nowe wydarzenia mogą pojawiać się z niewielkim opóźnieniem.

Limit zapytań

60 / min

na adres IP

Bufor serwera

5 min

dla każdej kombinacji parametrów

Format odpowiedzi

Odpowiedź jest obiektem JSON. Każde wydarzenie zawiera tylko pola publiczne – wewnętrzne opisy, dane uczestników ani inne wrażliwe informacje nigdy nie są zwracane.

events[] — Lista wydarzeń z polami id, title, type, location, start_time, end_time, has_ticket_sale, opcjonalnie ticket_sale_url (przy aktywnej sprzedaży biletów) i opcjonalnie description.
ensemble_name — Wyświetlana nazwa Twojego zespołu.
theme_color — Kod koloru szesnastkowego z ustawień strony.
language — Kod języka Twojej strony.

Pole description zawiera wyłącznie opis publiczny. Wewnętrzny opis wydarzenia nigdy nie jest częścią odpowiedzi.

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": "Coroczny koncert letni w ogrodzie domu kultury.",
      "has_ticket_sale": true,
      "ticket_sale_url": "https://www.chorilo.com/shop/tickets/42"
    }
  ],
  "ensemble_name": "Musterchor",
  "theme_color": "#6366f1",
  "language": "de"
}

Przykłady

Tak wywołasz API z różnych języków. Przykład pobiera do 10 nadchodzących koncertów i innych wydarzeń.

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

Kody statusu

Kod	Znaczenie
200	Powodzenie, wydarzenia w tablicy events.
404	Nie znaleziono strony z tym slugiem.
422	Nieprawidłowe parametry zapytania (na przykład nieznany typ lub to przed from).
429	Przekroczono limit zapytań, spróbuj ponownie za minutę.

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.

Pytania?

W sprawie pytań technicznych dotyczących API skontaktuj się z: support@chorilo.com