Ontwikkelaars

Evenementen-API voor jullie website

Bed de openbare evenementen van jullie ensemble in op elke website — met een eenvoudige HTTP-aanvraag, zonder account en zonder API-sleutel.

Het belangrijkste

•Openbaar toegankelijk, geen authenticatie vereist.
•CORS is ingeschakeld, het eindpunt werkt direct vanuit de browser.
•Antwoorden worden 5 minuten gecached, limiet 60 verzoeken per minuut.
•Alleen gegevens die jullie in de website-instellingen voor openbare weergave hebben vrijgegeven, worden teruggegeven.
•Bij openbaar gebruik is een 'Powered by Chorilo'-vermelding met link naar onze website verplicht.

Powered by Chorilo — Vermelding op jullie site

Als jullie de API op een openbare pagina gebruiken, voeg dan zichtbaar een 'Powered by Chorilo'-vermelding toe met een link naar https://www.chorilo.com. Een bescheiden regel in de voettekst is ruim voldoende.

De ruil is eerlijk: jullie bedden jullie evenementen automatisch in andere systemen in en hoeven ze niet dubbel te onderhouden. Elke API-aanvraag zorgt echter ook voor belasting op onze servers en infrastructuurkosten — hoe meer bezoekers jullie pagina krijgt, hoe meer middelen dat bij ons kost. In ruil daarvoor geeft de kleine vermelding Chorilo wat zichtbaarheid die ons helpt nieuwe koren te bereiken.

HTML

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

Voorbeeld

Eindpunt

Een enkel GET-eindpunt geeft de komende evenementen van jullie ensemble terug. Vervang door de URL-slug van jullie openbare Chorilo-website.

Waar vind ik mijn slug?

Open de instellingen van jullie openbare website in de Chorilo-backend. De slug is het unieke deel van de URL, bijvoorbeeld 'mijn-koor' in https://chorilo.com/w/mijn-koor.

GET

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

Zichtbaarheid beheren

De API respecteert de zichtbaarheidsinstellingen van jullie openbare website. Alles wat op de website verborgen is, is ook via de API geblokkeerd — zelfs als het expliciet wordt opgevraagd.

Hoofdschakelaar: Als show_events uitgeschakeld is, geeft de API een lege lijst terug.

Evenementtypes: Alleen vrijgegeven types worden teruggegeven. Een verzoek voor geblokkeerde types (bijvoorbeeld types[]=concert terwijl de concertweergave uitstaat) wordt stilzwijgend gefilterd.

Instelling	Betreft type
show_events	Hoofdschakelaar (schakelt alles uit)
show_rehearsals	`rehearsal`
show_concerts	`concert`
show_other_events	`event`
show_event_descriptions	Bepaalt het veld description in de reactie

Queryparameters

Alle parameters zijn optioneel. Zonder parameters geeft het eindpunt de eerstvolgende evenementen terug volgens de standaardinstellingen van jullie website.

Naam	Type	Standaard	Beschrijving
limit	integer	5	Aantal teruggegeven evenementen. Minimum 1, maximum 100.
from	ISO 8601	nu	Startpunt van het datumbereik. Eerdere evenementen worden standaard niet teruggegeven.
to	ISO 8601	—	Eindpunt van het datumbereik.
types[]	array	alle toegestane	Een of meer van: rehearsal, concert, event. Geblokkeerde types worden stil gefilterd.
lang	string (2)	—	Taalcode van twee letters (de, en, fr, nl, es, sv, it, sl). Wordt momenteel als echo in de response-meta teruggegeven.

Rate-limit & caching

Het eindpunt is beperkt tot 60 verzoeken per minuut per IP-adres. Als de limiet wordt overschreden, reageert de server met HTTP 429.

Antwoorden worden server-side 5 minuten gecached (per parametercombinatie). Nieuwe evenementen verschijnen daarom mogelijk met een korte vertraging.

Rate-limit

60 / min

per IP-adres

Server-cache

5 min

per parametercombinatie

Responsformaat

Het antwoord is een JSON-object. Elk evenement bevat alleen openbare velden — interne beschrijvingen, deelnemergegevens of andere gevoelige informatie worden nooit teruggegeven.

events[] — Lijst van evenementen met id, title, type, location, start_time, end_time, has_ticket_sale, optioneel ticket_sale_url (bij actieve ticketverkoop) en optioneel description.
ensemble_name — Weergavenaam van jullie ensemble.
theme_color — Hex-kleurcode uit de website-instellingen.
language — Taalcode van jullie website.

Het veld description bevat uitsluitend de openbare beschrijving. De interne beschrijving van een evenement maakt nooit deel uit van het antwoord.

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": "Jaarlijks zomerconcert in de tuin van het buurthuis.",
      "has_ticket_sale": true,
      "ticket_sale_url": "https://www.chorilo.com/shop/tickets/42"
    }
  ],
  "ensemble_name": "Musterchor",
  "theme_color": "#6366f1",
  "language": "de"
}

Voorbeelden

Zo roep je de API aan vanuit verschillende talen. Het voorbeeld laadt tot 10 komende concerten en andere evenementen.

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

Statuscodes

Code	Betekenis
200	Succesvol, evenementen in de events-array.
404	Geen website gevonden met deze slug.
422	Ongeldige queryparameters (bijvoorbeeld onbekend type of to vóór from).
429	Rate-limit overschreden, probeer het over een minuut opnieuw.

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/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.

Vragen?

Voor technische vragen over de API kunnen jullie contact opnemen met: support@chorilo.com