Guida rapida all’API Gianna

L’API /liturgy/v1 espone in sola lettura dati liturgici cattolici: calendario, propri della Messa, Ufficio e santi dei riti romano ordinario, romano del 1962 (Messa latina tradizionale) e domenicano. È gratuita con un account Gianna. Per il modello completo vedi Liturgia; questa pagina serve a iniziare le chiamate.

1. Creare una chiave

Crea una chiave in Impostazioni, Accesso sviluppatori. Viene mostrata una volta e non è recuperabile. Puoi anche crearla da una sessione web autenticata con il cookie gianna_session:

curl -s https://gianna.chat/api/keys \
  -H 'Content-Type: application/json' \
  -b 'gianna_session=YOUR_SESSION_COOKIE' \
  -d '{"name":"my-script"}'
# → { "id": "...", "name": "my-script", "key": "gianna_…" }

Conserva gianna_…. Ogni chiamata dati lo presenta come token bearer: Authorization: Bearer gianna_…. Liturgia e chiese richiedono soltanto un account. Le chiamate alla famiglia richiedono un abbonamento attivo o in prova; agire su una famiglia con abbonamento scaduto restituisce 403.

Persone, istituzioni e uffici sono disponibili anche tramite /registry/v1/people, /registry/v1/sees e /registry/v1/offices. Il loro documento OpenAPI descrive campi e risorse correlate. Le letture richiedono reference:read. Curatori e amministratori possono aggiungere e modificare schede con una chiave legata all’account dotata di household:write; il lavoro di riferimento non richiede un piano a pagamento. Vedi Gestire persone e uffici per modifiche e importazioni.

2. Un giorno liturgico

curl -s https://gianna.chat/liturgy/v1/calendars/ordinary/days/2026-12-25 \
  -H 'Authorization: Bearer gianna_…'

Il percorso è /calendars/{cal}/days/{date}, dove cal è ordinary, traditional o dominican e date è ISO YYYY-MM-DD. Il latino è sempre presente; aggiungi Accept-Language: en per il testo inglese.

3. Cercare santi

curl -s 'https://gianna.chat/liturgy/v1/saints?q=peter&title=martyr' \
  -H 'Authorization: Bearer gianna_…'

I risultati sono in un involucro di raccolta (results, query, page); usa ?page=N per scorrere le pagine.

4. Preghiere e Scrittura

curl -s https://gianna.chat/liturgy/v1/prayers/hail-mary -H 'Authorization: Bearer gianna_…'
curl -s 'https://gianna.chat/liturgy/v1/scripture?ref=Jn%203:16&editions=douay' \
  -H 'Authorization: Bearer gianna_…'

Il testo viene restituito esattamente come pubblicato, con la fonte.

5. Orari di Messe e confessioni

curl -s 'https://gianna.chat/directory/v1/churches?near=Cambridge' -H 'Authorization: Bearer gianna_…'
curl -s 'https://gianna.chat/directory/v1/churches?q=Our%20Lady&locality=Cambridge' \
  -H 'Authorization: Bearer gianna_…'

Ogni orario porta source_url, scraped_at e confidence. La ricerca per nome di una chiesa ancora sconosciuta restituisce status: "checking" e avvia la ricerca delle fonti; riprova più tardi. La chiave richiede directory:read.

6. La tua famiglia

Con household:read e, per le modifiche, household:write:

curl -s https://gianna.chat/household/v1/tasks -H 'Authorization: Bearer gianna_…'
curl -s https://gianna.chat/household/v1/reminders -H 'Authorization: Bearer gianna_…' \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: 4f1c…' \
  -d '{"body":"Pray the Angelus","at":"2026-12-24T12:00:00Z","recurrence":{"unit":"daily"}}'

Gianna invia i promemoria direttamente. Manda Idempotency-Key con ogni POST per evitare duplicati: stessa chiave e corpo riproducono la prima risposta per 24 ore. Le modifiche appaiono subito nell’app.

Scegliere un’edizione biblica

Le letture usano l’edizione di pubblico dominio predefinita per lingua. Per sceglierne una, passa ?editions=<id>[,<id>], al massimo una per lingua. Identificativi attuali: vulgate (la), douay (en), cpdv (en). L’elenco attivo è a /liturgy/v1/translations. Gli identificativi sconosciuti ricadono sul predefinito con un avviso nella raccolta. La scelta risolta è ripetuta come editions nella risposta. translations è un alias accettato; se entrambi sono presenti prevale editions.

curl -s 'https://gianna.chat/liturgy/v1/calendars/ordinary/days/2026-12-25?editions=douay' \
  -H 'Authorization: Bearer gianna_…'

Limiti di richieste

Le richieste sono limitate per famiglia su una finestra fissa di un minuto. Il superamento restituisce 429 Too Many Requests, l’intestazione Retry-After con i secondi fino al ripristino e un corpo application/problem+json. Attendi quel numero di secondi e riprova.

Contratto completo

Ogni famiglia di API pubblica un documento OpenAPI 3.1 con operationId: /liturgy/v1/openapi.json, /directory/v1/openapi.json e /household/v1/openapi.json. /.well-known/api-catalog li elenca. Gli errori sono application/problem+json.

Feed dei calendari

I feed delle feste non richiedono chiave. Iscriviti da qualsiasi app calendario:

https://gianna.chat/liturgy/v1/calendars/ordinary/feasts.ics?rank=feast&region=general

Vedi Calendari delle feste cattoliche per i collegamenti diretti.