🇫🇷 data.gouv.fr - Documentation et Librairie Python

Documentation complète et librairie Python pour accéder aux données ouvertes françaises via data.gouv.fr

📖 À propos

Ce repository fournit une documentation complète et une librairie Python pour travailler avec les données publiques françaises de data.gouv.fr.

⚠️ Important : Ce n'est PAS un plugin avec des commandes slash interactives, mais plutôt :

• 📚 Une documentation détaillée de l'API data.gouv.fr et des datasets
• 🐍 Une librairie Python réutilisable (datagouv.py)
• 📊 Des datasets documentés (IQVIA vaccinations, qualité de l'eau, etc.)
• 💡 Des exemples de code prêts à l'emploi
• 🔗 Des liens vers le MCP officiel data.gouv.fr

Pour des commandes interactives dans Claude Code (requêtes SQL, langage naturel), utilisez le MCP officiel data.gouv.fr.

---

✨ Fonctionnalités

• 🔍 Recherche intelligente de datasets via l'API officielle
• 📥 Téléchargement automatique avec mise en cache
• 🧹 Parsing avancé des formats français (CSV ;, dates DD/MM/YYYY, décimales ,)
• 📊 Chargement direct dans pandas DataFrames
• 📚 Documentation complète des datasets les plus utilisés
• 🐍 Librairie Python réutilisable et testée
• 💡 Exemples pratiques pour chaque cas d'usage

🚀 Installation

Cloner le repository

git clone https://github.com/benoitvx/data-gouv-skill.git
cd data-gouv-skill

Installer les dépendances Python

pip install pandas requests openpyxl

Utiliser la librairie

from skills.data-gouv.lib.datagouv import DataGouvAPI

api = DataGouvAPI()
results = api.search_datasets("vaccination")

📚 Documentation

Consulter en ligne

Parcourez la documentation directement sur GitHub :

• SKILL.md - Documentation principale
• GUIDE_CHOIX.md - Choisir entre lib Python et MCP
• Datasets - Documentation détaillée des datasets

🆕 Deux approches disponibles

Notre librairie Python (simple & rapide)

from skills.data-gouv.lib.datagouv import DataGouvAPI
api = DataGouvAPI()
df = api.load_csv(url, cache=True)  # Cache, offline, portable

Idéal pour :

• Scripts automatisés
• Développement local
• Analyse offline
• Notebooks Jupyter

MCP officiel data.gouv.fr (requêtes avancées)

"Dans le dataset IQVIA, trouve les départements où
les vaccinations ont augmenté de plus de 50%"

Idéal pour :

• Requêtes SQL complexes
• Questions en langage naturel
• Création de datasets
• Intégration Claude Desktop/Cursor

📖 Guide complet : GUIDE_CHOIX.md
🔗 MCP officiel : https://github.com/datagouv/datagouv-mcp

📖 Exemple d'utilisation

from skills.data-gouv.lib.datagouv import DataGouvAPI

# Initialiser l'API
api = DataGouvAPI()

# Rechercher des datasets
results = api.search_datasets("vaccination", organization="iqvia-france")
for dataset in results['data']:
    print(f"📊 {dataset['title']}")

# Charger directement un CSV
df = api.load_csv("https://www.data.gouv.fr/fr/datasets/r/resource-id")
print(f"✅ Chargé : {len(df)} lignes")

# Obtenir la dernière ressource d'un dataset
resource = api.get_latest_resource("dataset-id", format="csv")
df = api.load_csv(resource['url'])

📊 Datasets documentés

Le skill inclut une documentation détaillée pour les datasets les plus utilisés :

Santé

IQVIA - Vaccinations anti-grippales

• Suivi hebdomadaire des campagnes de vaccination
• Détails par région, département, âge et type de site
• Données depuis 2019

Qualité de l'eau potable

• Résultats des contrôles sanitaires commune par commune
• Plus de 300,000 analyses par an
• Paramètres microbiologiques, chimiques et physico-chimiques

Administration

• Calendrier scolaire par zone académique
• Code Officiel Géographique (INSEE)
• Population légale des communes

Environnement

• Qualité de l'air
• Production d'énergie renouvelable
• Stations de recharge électrique

🎯 Cas d'usage

Analyser les vaccinations par région

from skills.data-gouv.lib.datagouv import DataGouvAPI
import pandas as pd

api = DataGouvAPI()

# Charger les données de vaccination
results = api.search_datasets("vaccination grippe 2025-2026", organization="iqvia-france")
dataset_id = results['data'][0]['id']
resource = api.get_latest_resource(dataset_id, format='csv')
df = api.load_csv(resource['url'])

# Filtrer par région
df_na = df[df['code_region'] == '75']  # Nouvelle-Aquitaine
total = df_na['nb_doses'].sum()
print(f"💉 Total vaccinations en Nouvelle-Aquitaine : {total:,}")

Vérifier la qualité de l'eau

# Charger les données
dataset_id = "resultats-du-controle-sanitaire-de-leau-distribuee-commune-par-commune"
dataset = api.get_dataset(dataset_id)

# Obtenir les données pour La Rochelle (17300)
# ... (voir documentation complète dans skills/data-gouv/datasets/eau-potable.md)

# Calculer le taux de conformité
taux = (results['conforme'] == 'O').sum() / len(results) * 100
print(f"✅ Taux de conformité : {taux:.1f}%")

Comparer des campagnes de vaccination

# Charger 2 campagnes
df_2025 = api.load_csv(url_2025)
df_2024 = api.load_csv(url_2024)

# Comparer
evolution = ((df_2025['nb_doses'].sum() - df_2024['nb_doses'].sum()) / df_2024['nb_doses'].sum()) * 100
print(f"📈 Évolution : {evolution:+.1f}%")

🗂️ Structure du projet

data-gouv-skill/
├── skills/data-gouv/
│   ├── SKILL.md                 # Documentation principale (point d'entrée)
│   │
│   ├── lib/
│   │   └── datagouv.py         # Librairie Python
│   │
│   ├── datasets/                # Documentation détaillée
│   │   ├── iqvia-vaccination.md
│   │   ├── eau-potable.md
│   │   └── ...
│   │
│   └── examples/                # Exemples de code
│       ├── vaccination_analysis.py
│       ├── water_quality.py
│       └── ...
│
├── scripts/
│   ├── sync-datasets.sh         # Synchroniser les métadonnées
│   └── update-metadata.py       # Mettre à jour la documentation
│
├── README.md                    # Ce fichier
└── LICENSE.md                   # Licence Ouverte 2.0

🔧 API Reference

Classe DataGouvAPI

class DataGouvAPI:
    def __init__(self, cache_dir: Optional[str] = None)

    def search_datasets(
        self, query: str,
        organization: Optional[str] = None,
        tag: Optional[str] = None,
        page_size: int = 20
    ) -> Dict[str, Any]

    def get_dataset(self, dataset_id: str) -> Optional[Dict[str, Any]]

    def get_latest_resource(
        self, dataset_id: str,
        format: str = 'csv'
    ) -> Optional[Dict[str, Any]]

    def download_resource(
        self, resource_url: str,
        cache: bool = True
    ) -> Optional[bytes]

    def load_csv(
        self, resource_url: str,
        sep: Optional[str] = None,
        encoding: Optional[str] = None,
        decimal: str = ','
    ) -> Optional[pd.DataFrame]

Fonctions utilitaires

def quick_search(query: str, limit: int = 5) -> List[Dict[str, Any]]
def load_dataset_csv(dataset_id: str, resource_index: int = 0) -> Optional[pd.DataFrame]

💡 Bonnes pratiques

1. Utiliser le cache

api = DataGouvAPI(cache_dir="~/.cache/datagouv")
df = api.load_csv(url)  # cache automatique

2. Gérer les gros fichiers

# Charger par chunks
chunks = []
for chunk in pd.read_csv(url, chunksize=10000, sep=';'):
    chunk_filtered = chunk[chunk['region'] == 'Nouvelle-Aquitaine']
    chunks.append(chunk_filtered)
df = pd.concat(chunks)

3. Valider les données

df = api.load_csv(url)
if df is not None:
    print(f"✓ {len(df)} lignes, {len(df.columns)} colonnes")
else:
    print(f"✗ Erreur de chargement")

🤝 Contribution

Les contributions sont les bienvenues !

Ajouter un nouveau dataset documenté

1. Créer skills/data-gouv/datasets/nom-dataset.md
2. Suivre le modèle des datasets existants
3. Inclure des exemples de code concrets
4. Soumettre une pull request

Guidelines

• Utiliser le format markdown
• Inclure des exemples de code testés
• Documenter les colonnes importantes
• Ajouter des cas d'usage pratiques

📚 Ressources

Documentation officielle

• data.gouv.fr
• API documentation
• Guide des producteurs

Organisations principales sur data.gouv.fr

• INSEE : Statistiques, population, économie
• Ministère de la Santé : Santé publique, qualité de l'eau
• IQVIA France : Campagnes de vaccination
• Santé Publique France : Surveillance sanitaire
• Ministère de l'Éducation : Données scolaires

📄 Licence

Ce projet est publié sous Licence Ouverte 2.0 (compatible Creative Commons BY).

Vous êtes libre de :

• ✅ Réutiliser les données et le code
• ✅ Modifier et adapter
• ✅ Usage commercial autorisé

Sous condition de :

• 📝 Mentionner la paternité (source + date)

🙏 Remerciements

• data.gouv.fr pour l'API et les données ouvertes
• Etalab pour la plateforme et la Licence Ouverte
• La communauté des producteurs de données publiques
• Claude Code par Anthropic

📞 Support

• 🐛 Bug reports : GitHub Issues
• 💡 Feature requests : GitHub Discussions
• 📧 Contact : benoitvinceneux@gmail.com

---

Auteur : Benoit Vinceneux
Version : 2.1.1
Dernière mise à jour : 2025-12-02

⭐ Si ce projet vous est utile, n'hésitez pas à mettre une étoile sur GitHub !