# Echoes of Geeks — API publique

> Calendrier francophone des sorties de jeux vidéo, événements gaming et livres.

## Règle essentielle

L’API est strictement en lecture seule. Elle n’accepte que GET et OPTIONS.
Il n’existe aucune route publique permettant de créer, modifier ou supprimer un contenu.

Base : https://calendrier.echoesofgeeks.fr/api/v1
Documentation : https://calendrier.echoesofgeeks.fr/api/
Index des routes : https://calendrier.echoesofgeeks.fr/api/v1/

## Accès recommandé aux LLM

Index compact du catalogue public, toutes dates :
https://calendrier.echoesofgeeks.fr/api/v1/calendar?kind=all&scope=all&view=index&limit=500

Cette URL fixe et directement liée contient tous les jeux, événements et livres publiés.
Pour un contrôle anti-doublon, lire ce catalogue puis comparer le titre,
le type et, pour les livres, les ISBN. La route dynamique `search` est un
complément facultatif lorsque l’environnement autorise son URL exacte.

## Calendrier JSON

- Jeux : https://calendrier.echoesofgeeks.fr/api/v1/calendar?kind=games&limit=100
- Événements : https://calendrier.echoesofgeeks.fr/api/v1/calendar?kind=events&limit=100
- Livres : https://calendrier.echoesofgeeks.fr/api/v1/calendar?kind=books&limit=100
- Tout : https://calendrier.echoesofgeeks.fr/api/v1/calendar?kind=all&limit=100
- Recherche : https://calendrier.echoesofgeeks.fr/api/v1/search?q=TITRE&kind=all
- Lookup HTML stable : https://calendrier.echoesofgeeks.fr/api/v1/lookup.php
- Exemple lié : https://calendrier.echoesofgeeks.fr/api/v1/lookup.php?kind=games&q=Space%20Tales

Si une requête est bloquée, retourne une erreur HTTP ou produit un état
`unverified`, ne jamais l’interpréter comme `exact_match:false`. Une absence
n’est confirmée que lorsque la réponse a été obtenue avec succès.

`calendar` accepte `kind=games|events|books|all`, `from=YYYY-MM-DD`,
`to=YYYY-MM-DD`, `q`, `scope=range|all`, `view=full|index` et
`limit=1..500`.
Avec `q` sans `from` ni `to`, la recherche couvre toutes les dates et classe
d’abord les correspondances trouvées dans le titre. Si `from` ou `to` est
fourni, la recherche reste limitée à la période indiquée.

`search` accepte `q`, `kind=games|events|books|all`,
`mode=exact|contains` et `limit=1..20`. Sans `kind`, la recherche couvre
les jeux, les événements et les livres (`kind=all`).

La recherche des livres reconnaît le titre, le sous-titre, les auteurs,
la maison d’édition, la série, l’ISBN-13 et l’ISBN-10. Les ISBN peuvent
être saisis avec ou sans séparateurs.

## Import IA des événements

L’import est réservé à l’administration. ChatGPT produit uniquement ce JSON :

```json
{
  "events": [
    {
      "name": "Nom officiel de l’événement",
      "start_datetime": "2026-08-19 20:00",
      "end_datetime": "2026-08-19 22:00",
      "timezone": "Europe/Paris",
      "description": "Présentation factuelle en français.",
      "image_url": "https://exemple.com/visuel.jpg",
      "website_url": "https://site-officiel.example/evenement",
      "video_url": "https://www.youtube.com/watch?v=XXXXXXXXXXX",
      "game_titles": ["Nom exact du jeu associé"],
      "is_featured": false
    }
  ]
}
```

Contraintes : URL en HTTPS, début obligatoire, fin facultative et postérieure
au début, fuseau IANA valide, `game_titles` sous forme de tableau et
`is_featured` sous forme de booléen. Une image ou une vidéo YouTube est requise.

## Import IA des livres

```json
{"books":[{"title":"","subtitle":"","authors":[],"release_date":"jj/mm/aaaa","publisher":"","format":"","isbn13":"","isbn10":"","language":"fr","pages":null,"series":"","volume":"","description":"","cover_url":"","status":"upcoming","reliability":"confirmed","source_url":""}]}
```

## Bon usage

1. Lire le catalogue ou utiliser `search` avant toute proposition.
2. Ne jamais prétendre avoir écrit dans l’API.
3. Citer l’URL publique de la fiche retournée.
4. Respecter le cache public et la limite indicative de 60 requêtes par minute.