Sviluppatori

API eventi per il vostro sito web

Integrate gli eventi pubblici del vostro ensemble in qualsiasi sito web — con una semplice richiesta HTTP, senza account e senza chiave API.

L'essenziale

•Accesso pubblico, nessuna autenticazione richiesta.
•CORS è abilitato, l'endpoint funziona direttamente dal browser.
•Le risposte sono cachate per 5 minuti, limite 60 richieste al minuto.
•Vengono restituiti solo i dati che avete abilitato per la visualizzazione pubblica nelle impostazioni del sito.
•Per l'uso pubblico è obbligatorio un avviso 'Powered by Chorilo' con link al nostro sito.

Powered by Chorilo — Attribuzione sul vostro sito

Se utilizzate l'API su una pagina pubblica, aggiungete per favore un avviso visibile 'Powered by Chorilo' con link a https://www.chorilo.com. Una riga discreta nel piè di pagina è più che sufficiente.

Lo scambio è equo: integrate i vostri eventi automaticamente in altri sistemi e non dovete gestirli due volte. Ogni richiesta API genera però anche carico sui nostri server e costi di infrastruttura — più traffico ha la vostra pagina, più risorse consuma dalla nostra parte. In cambio, la piccola menzione dà a Chorilo un po' di visibilità che ci aiuta a raggiungere nuovi cori.

HTML

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

Anteprima

Endpoint

Un unico endpoint GET restituisce i prossimi eventi del vostro ensemble. Sostituite con lo slug URL del vostro sito pubblico Chorilo.

Dove trovo il mio slug?

Aprite le impostazioni del vostro sito pubblico nel backend Chorilo. Lo slug è la parte unica dell'URL, per esempio 'mio-coro' in https://chorilo.com/w/mio-coro.

GET

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

Controllare la visibilità

L'API rispetta le impostazioni di visibilità del vostro sito pubblico. Tutto ciò che è nascosto sul sito è anche bloccato via API — anche quando richiesto esplicitamente.

Interruttore principale: Se show_events è disabilitato, l'API restituisce una lista vuota.

Tipi di eventi: Vengono restituiti solo i tipi abilitati. Una richiesta per tipi bloccati (per esempio types[]=concert con la visualizzazione dei concerti disattivata) viene filtrata silenziosamente.

Impostazione	Interessa il tipo
show_events	Interruttore principale (disattiva tutto)
show_rehearsals	`rehearsal`
show_concerts	`concert`
show_other_events	`event`
show_event_descriptions	Controlla il campo description nella risposta

Parametri di query

Tutti i parametri sono facoltativi. Senza parametri, l'endpoint restituisce i prossimi eventi secondo le impostazioni predefinite del vostro sito.

Nome	Tipo	Predefinito	Descrizione
limit	integer	5	Numero di eventi restituiti. Minimo 1, massimo 100.
from	ISO 8601	adesso	Inizio dell'intervallo di date. Gli eventi passati non vengono restituiti per impostazione predefinita.
to	ISO 8601	—	Fine dell'intervallo di date.
types[]	array	tutti i consentiti	Uno o più tra: rehearsal, concert, event. I tipi bloccati vengono filtrati silenziosamente.
lang	string (2)	—	Codice lingua a due lettere (de, en, fr, nl, es, sv, it, sl). Attualmente restituito come eco nel meta della risposta.

Rate limit & caching

L'endpoint è limitato a 60 richieste al minuto per indirizzo IP. Se il limite viene superato, il server risponde con HTTP 429.

Le risposte sono cachate lato server per 5 minuti (per combinazione di parametri). I nuovi eventi possono quindi apparire con un breve ritardo.

Limite

60 / min

per indirizzo IP

Cache server

5 min

per combinazione di parametri

Formato della risposta

La risposta è un oggetto JSON. Ogni evento contiene solo campi pubblici — descrizioni interne, dati dei partecipanti o altre informazioni sensibili non vengono mai restituiti.

events[] — Elenco degli eventi con id, title, type, location, start_time, end_time, has_ticket_sale, facoltativamente ticket_sale_url (se la vendita biglietti è attiva) e facoltativamente description.
ensemble_name — Nome visualizzato del vostro ensemble.
theme_color — Codice colore esadecimale dalle impostazioni del sito.
language — Codice lingua del vostro sito.

Il campo description contiene esclusivamente la descrizione pubblica. La descrizione interna di un evento non fa mai parte della risposta.

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": "Concerto estivo annuale nel giardino della casa comunale.",
      "has_ticket_sale": true,
      "ticket_sale_url": "https://www.chorilo.com/shop/tickets/42"
    }
  ],
  "ensemble_name": "Musterchor",
  "theme_color": "#6366f1",
  "language": "de"
}

Esempi

Come chiamare l'API da diversi linguaggi. L'esempio carica fino a 10 prossimi concerti e altri eventi.

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

Codici di stato

Codice	Significato
200	Successo, eventi nell'array events.
404	Nessun sito trovato con questo slug.
422	Parametri di query non validi (per esempio tipo sconosciuto o to prima di from).
429	Limite superato, riprovate tra un minuto.

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.

Domande?

Per domande tecniche sull'API contattate: support@chorilo.com