Démarrage rapide de l’API Gianna

L’API /liturgy/v1 expose en lecture seule les données liturgiques catholiques : calendrier, propres de la messe, Office et saints des rites romain ordinaire, romain de 1962 (messe latine traditionnelle) et dominicain. Elle est gratuite avec un compte Gianna. Pour le modèle de données complet, voir Liturgie ; cette page permet de commencer les appels.

1. Créer une clé

Créez une clé dans Paramètres, Accès développeur. Elle n’est affichée qu’une fois et ne peut pas être récupérée ensuite. Vous pouvez aussi en créer une depuis une session web connectée avec votre 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_…" }

Conservez la valeur gianna_…. Chaque appel de données la présente comme jeton porteur : Authorization: Bearer gianna_…. Les données liturgiques et d’églises exigent seulement un compte. Les appels au foyer exigent un abonnement actif ou en essai ; agir sur un foyer dont l’abonnement a expiré renvoie 403.

Les personnes, institutions et charges sont aussi accessibles par /registry/v1/people, /registry/v1/sees et /registry/v1/offices. Leur document OpenAPI décrit les champs et ressources liées. Les lectures exigent reference:read. Les conservateurs et administrateurs peuvent ajouter et modifier ces notices avec une clé liée au compte disposant de household:write ; ce travail de référence n’exige aucun abonnement payant. Voir Entretenir les personnes et les charges pour les modifications et imports.

2. Un jour liturgique

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

Le chemin est /calendars/{cal}/days/{date}, où cal vaut ordinary, traditional ou dominican, et date est au format ISO YYYY-MM-DD. Le latin est toujours présent ; ajoutez Accept-Language: en pour obtenir aussi le texte anglais.

3. Rechercher des saints

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

Les résultats arrivent dans une enveloppe de collection (results, query, page) ; passez ?page=N pour parcourir les pages.

4. Prières et Écriture

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_…'

Le texte est renvoyé exactement tel que publié, avec sa source.

5. Horaires des messes et confessions

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_…'

Chaque horaire porte source_url, scraped_at et confidence. Une recherche par nom d’une église encore inconnue de Gianna renvoie status: "checking" et lance la recherche des sources ; réessayez plus tard. La clé exige directory:read.

6. Votre foyer

Avec household:read et, pour les modifications, 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 envoie les rappels elle-même. Envoyez un Idempotency-Key avec chaque POST pour éviter qu’une nouvelle tentative crée un second rappel ; la même clé et le même corps rejouent la première réponse pendant 24 heures. Les modifications apparaissent immédiatement dans l’application.

Choisir une édition biblique

Les lectures utilisent par défaut l’édition du domaine public de chaque langue. Pour en choisir une, passez ?editions=<id>[,<id>], au plus une par langue. Identifiants actuels : vulgate (la), douay (en), cpdv (en). La liste active se trouve à /liturgy/v1/translations. Les identifiants inconnus reviennent à la valeur par défaut, avec un avertissement de collection. Le choix résolu est répété comme editions dans la réponse. translations est un alias accepté ; editions prévaut si les deux sont envoyés.

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

Limites de requêtes

Les requêtes sont limitées par foyer sur une fenêtre fixe d’une minute. Le dépassement renvoie 429 Too Many Requests, un en-tête Retry-After (secondes avant réinitialisation) et un corps application/problem+json. Attendez ce nombre de secondes puis réessayez.

Contrat complet

Chaque famille publie un document OpenAPI 3.1 public avec des operationId : /liturgy/v1/openapi.json, /directory/v1/openapi.json et /household/v1/openapi.json. /.well-known/api-catalog les liste tous. Les erreurs utilisent application/problem+json.

Flux de calendriers

Les flux de fêtes n’exigent aucune clé. Abonnez-vous depuis toute application de calendrier :

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

Voir Calendriers des fêtes catholiques pour les liens directs.