oedb-backend/extractors/README_agendadulibre.md

# Scraper Agenda du Libre

Script de scraping pour récupérer les événements de l'agenda du libre (https://www.agendadulibre.org/) et les envoyer à l'API OEDB.

## Fonctionnalités

- 📥 Récupération automatique du fichier iCal depuis l'agenda du libre
- 🔄 Traitement par batch configurable
- 💾 Sauvegarde locale de l'état des événements (JSON)
- 🚫 Évite les doublons (ne renvoie pas les événements déjà traités)
- 📊 Statistiques détaillées et logging
- 🧪 Mode démo et tests inclus

## Installation

1. Installer les dépendances Python :
```bash
pip install -r requirements_agendadulibre.txt
```

2. Rendre les scripts exécutables :
```bash
chmod +x agendadulibre.py
chmod +x test_agendadulibre.py
chmod +x demo_agendadulibre.py
```

## Utilisation

### Scraping complet
```bash
# Utilisation basique (1 événement par batch)
python agendadulibre.py

# Avec options personnalisées
python agendadulibre.py --api-url https://api.openeventdatabase.org --batch-size 5 --verbose
```

### Options disponibles
- `--api-url` : URL de base de l'API OEDB (défaut: https://api.openeventdatabase.org)
- `--batch-size` : Nombre d'événements à traiter par batch (défaut: 1)
- `--verbose` : Mode verbeux pour plus de détails
- `--force-refresh` : Forcer le rechargement du fichier iCal (ignorer le cache)
- `--cache-duration` : Durée de validité du cache en heures (défaut: 1)

### Démonstration
```bash
# Mode démo (ne fait pas d'appels API réels)
python demo_agendadulibre.py
```

### Tests
```bash
# Exécuter les tests
python test_agendadulibre.py
```

## Fichiers générés

- `agendadulibre_events.json` : Base de données locale des événements traités
- `agendadulibre_events.ics` : Cache local du fichier iCal (valide 1h)
- `agendadulibre_scraper.log` : Logs détaillés du scraper

## Système de cache iCal

Le script utilise un système de cache intelligent pour éviter de télécharger le fichier iCal à chaque exécution :

- **Cache valide** : Le fichier iCal est mis en cache localement pendant 1 heure par défaut
- **Rechargement automatique** : Si le cache est expiré, le fichier est automatiquement rechargé
- **Fallback** : En cas d'erreur de téléchargement, le script utilise le cache même s'il est expiré
- **Force refresh** : Option `--force-refresh` pour ignorer le cache et forcer le rechargement

### Avantages du cache
- ⚡ **Performance** : Évite les téléchargements inutiles
- 🔄 **Fiabilité** : Fonctionne même si l'API iCal est temporairement indisponible
- 📊 **Efficacité** : Réduit la charge sur le serveur de l'agenda du libre

## Format des événements

Les événements sont convertis au format OEDB avec les propriétés suivantes :

```json
{
  "properties": {
    "label": "Titre de l'événement",
    "description": "Description de l'événement",
    "what": "culture.geek",
    "where": "Lieu de l'événement",
    "start": "2024-01-01T10:00:00",
    "stop": "2024-01-01T12:00:00",
    "url": "https://www.agendadulibre.org/event/123",
    "source": "agendadulibre.org",
    "last_modified_by": "agendadulibre_scraper"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [0, 0]
  }
}
```

## Gestion des doublons

Le script utilise un système de suivi local pour éviter les doublons :

- Chaque événement reçoit un ID unique basé sur son contenu
- Les événements déjà traités avec succès ne sont pas renvoyés
- Les événements en erreur peuvent être retentés
- Les événements déjà existants (réponse 409) sont marqués comme traités

## Statuts des événements

- `saved` : Événement envoyé avec succès à l'API
- `already_exists` : Événement déjà existant dans l'API (réponse 409)
- `error` : Erreur lors de l'envoi à l'API

## Exemple de sortie

```
2024-01-01 10:00:00 - INFO - 🚀 Démarrage du scraping de l'agenda du libre
2024-01-01 10:00:01 - INFO - Récupération du fichier iCal depuis https://www.agendadulibre.org/events.ics
2024-01-01 10:00:02 - INFO - Fichier iCal récupéré avec succès
2024-01-01 10:00:03 - INFO - Traitement de 15 nouveaux événements par batch de 1
2024-01-01 10:00:04 - INFO - Envoi de l'événement: Conférence Python
2024-01-01 10:00:05 - INFO - ✅ Conférence Python - Créé avec succès
...
2024-01-01 10:00:30 - INFO - 📊 Statistiques finales:
2024-01-01 10:00:30 - INFO -    Total d'événements trouvés: 25
2024-01-01 10:00:30 - INFO -    Nouveaux événements envoyés: 12
2024-01-01 10:00:30 - INFO -    Événements déjà existants: 8
2024-01-01 10:00:30 - INFO -    Erreurs d'API: 2
2024-01-01 10:00:30 - INFO -    Erreurs de parsing: 3
2024-01-01 10:00:30 - INFO -    Événements envoyés cette fois: 12
2024-01-01 10:00:30 - INFO - ✅ Scraping terminé avec succès
```

## Planification

Pour automatiser le scraping, vous pouvez utiliser cron :

```bash
# Exécuter toutes les heures
0 * * * * cd /path/to/extractors && python agendadulibre.py --batch-size 5

# Exécuter tous les jours à 6h
0 6 * * * cd /path/to/extractors && python agendadulibre.py --batch-size 10
```

## Dépannage

### Erreur de connexion à l'API
- Vérifiez que l'API OEDB est démarrée
- Vérifiez l'URL de l'API avec `--api-url`

### Erreur de parsing iCal
- Vérifiez la connectivité internet
- Vérifiez que l'URL iCal est accessible

### Événements non géocodés
- Les événements sont créés avec des coordonnées par défaut [0, 0]
- Un processus de géocodage séparé peut être ajouté si nécessaire