Wrapper Python pour l'API Découpage Administratif Français

Ce projet fournit un wrapper Python moderne et complet pour interroger l'API de découpage administratif français (geo.api.gouv.fr). Cette API permet d'accéder aux référentiels géographiques officiels français sans authentification.

✨ Nouveauté : Version avec Dataclasses

Le wrapper est disponible en deux versions :

• Version classique (geo_api_gouv.py) : Retourne des dictionnaires Python
• Version dataclasses (geo_api_gouv_v2.py) : Retourne des objets typés avec méthodes utilitaires

🎯 Fonctionnalités

• Communes : Recherche par nom, code postal, coordonnées géographiques
• Départements : Recherche et informations détaillées
• Régions : Liste complète et recherche
• EPCI : Établissements publics de coopération intercommunale
• Communes associées/déléguées : Accès aux communes fusionnées
• Calculs avancés : Distance entre communes, densité, analyses territoriales

📦 Installation

Seule la bibliothèque requests est nécessaire :

pip install requests

🚀 Usage rapide

Version Dataclasses (Recommandée)

from geo_api_gouv_v2 import GeoAPIGouv

# Initialiser le client API
api = GeoAPIGouv()

# Rechercher des communes par code postal
communes = api.communes_par_code_postal("75001")
for commune in communes:
    print(f"{commune.nom} - Population: {commune.population:,} hab")
    print(f"Densité: {commune.densite:.0f} hab/km²" if commune.densite else "Densité: N/A")

# Obtenir les détails d'une commune
paris = api.obtenir_commune("75056")
print(f"Population de Paris: {paris.population:,} hab")
print(f"Zone: {'Métropole' if paris.est_metropole else 'DROM/COM'}")

# Distance entre deux communes
lyon = api.obtenir_commune("69123")
distance = paris.distance_vers(lyon)
print(f"Distance Paris-Lyon: {distance:.1f} km")

Version Classique

from geo_api_gouv import GeoAPIGouv

api = GeoAPIGouv()
communes = api.communes_par_code_postal("75001")
print(f"Communes du 75001: {[c['nom'] for c in communes]}")

📚 Documentation des méthodes

Note : Cette documentation couvre les deux versions. La version dataclasses offre les mêmes méthodes mais retourne des objets avec des propriétés et méthodes utilitaires.

🏘️ Communes

rechercher_communes(**kwargs) → List[Commune] / List[Dict]

Recherche des communes selon différents critères.

Paramètres principaux :

• code_postal (str) : Code postal associé
• nom (str) : Nom de la commune
• code (str) : Code INSEE de la commune
• code_departement (str) : Code du département
• code_region (str) : Code de la région
• lon (float), lat (float) : Coordonnées géographiques
• limit (int) : Nombre maximum de résultats

Exemples :

# Version dataclasses
communes = api.rechercher_communes(nom="Lyon", limit=5)
for commune in communes:
    print(f"{commune.nom} - {commune.population:,} hab")
    print(f"Est en métropole: {commune.est_metropole}")

# Version classique
communes = api.rechercher_communes(nom="Lyon", limit=5)
for commune in communes:
    print(f"{commune['nom']} - {commune.get('population', 'N/A')}")

obtenir_commune(code, **kwargs) → Commune / Dict

Récupère les informations détaillées d'une commune par son code INSEE.

Avantages des dataclasses :

# Version dataclasses - propriétés automatiques
marseille = api.obtenir_commune("13055")
print(f"Densité: {marseille.densite:.0f} hab/km²")
print(f"Code postal principal: {marseille.code_postal_principal}")
print(f"Est un arrondissement: {marseille.est_arrondissement}")

# Calcul de distance
paris = api.obtenir_commune("75056")
distance = marseille.distance_vers(paris)
print(f"Distance vers Paris: {distance:.1f} km")

🗺️ Départements

rechercher_departements(**kwargs)

Recherche des départements.

Paramètres :

• code (str) : Code INSEE du département
• nom (str) : Nom du département
• code_region (str) : Code de la région associée

Exemple :

# Départements contenant "Seine"
depts = api.rechercher_departements(nom="Seine", limit=5)

obtenir_departement(code)

Informations détaillées d'un département.

obtenir_departements_region(code_region)

Liste des départements d'une région donnée.

🌍 Régions

rechercher_regions(**kwargs)

Recherche des régions par code ou nom.

obtenir_region(code)

Informations détaillées d'une région.

toutes_les_regions()

Méthode de convenance pour obtenir la liste complète des régions françaises.

Exemple :

regions = api.toutes_les_regions()
for region in regions:
    print(f"{region['nom']} ({region['code']})")

🏛️ EPCI

rechercher_epcis(**kwargs)

Recherche des EPCI (Établissements publics de coopération intercommunale).

Paramètres principaux :

• nom (str) : Nom de l'EPCI
• boost (str) : Mode de boost ("population" pour prioriser par population)
• code_departement (str) : Filtrer par département

Exemple :

# Recherche avec boost population
epcis = api.rechercher_epcis(nom="Nantes", boost="population", limit=3)

obtenir_epci(code)

Informations détaillées d'un EPCI.

obtenir_communes_epci(code)

Liste des communes appartenant à un EPCI.

🏘️ Communes associées et déléguées

rechercher_communes_associees_deleguees(**kwargs)

Recherche des communes associées et déléguées.

Paramètres :

• type_commune (list) : Filtrer par type ("commune-associee", "commune-deleguee")
• code_departement (str) : Filtrer par département

Exemple :

# Communes déléguées d'un département
communes = api.rechercher_communes_associees_deleguees(
    code_departement="08", 
    type_commune=["commune-deleguee"]
)

🎨 Paramètres avancés

Formatage des réponses

• fields (list) : Spécifier les champs souhaités dans la réponse
• format_reponse (str) : Format de réponse ("json", "geojson")
• geometry (str) : Géométrie pour GeoJSON ("centre", "contour", "bbox", "mairie")

Exemple :

# Réponse avec champs spécifiques
commune = api.obtenir_commune("75056", fields=["nom", "population", "surface"])

# Réponse en GeoJSON avec contour
commune_geo = api.obtenir_commune("75056", format_reponse="geojson", geometry="contour")

💡 Exemples d'usage

Exemple 1 : Informations complètes d'une ville

from geo_api_gouv import GeoAPIGouv

api = GeoAPIGouv()

# Rechercher Lyon
communes = api.commune_par_nom("Lyon", limit=1)
if communes:
    lyon = api.obtenir_commune(
        communes[0]['code'], 
        fields=["nom", "code", "population", "surface", "codeDepartement", "codeRegion"]
    )
    
    print(f"Ville: {lyon['nom']}")
    print(f"Population: {lyon.get('population', 'N/A'):,} habitants")
    print(f"Surface: {lyon.get('surface', 'N/A')} hectares")
    
    # Informations du département
    dept = api.obtenir_departement(lyon['codeDepartement'])
    print(f"Département: {dept['nom']}")
    
    # Informations de la région
    region = api.obtenir_region(lyon['codeRegion'])
    print(f"Région: {region['nom']}")

Exemple 2 : Autocomplétion de communes

def autocomplete_commune(saisie):
    """Fonction d'autocomplétion pour les communes"""
    api = GeoAPIGouv()
    communes = api.commune_par_nom(saisie, limit=10)
    return [f"{c['nom']} ({c['code']})" for c in communes]

# Utilisation
suggestions = autocomplete_commune("Mar")
print("Suggestions:", suggestions)

Exemple 3 : Analyser une région

def analyser_region(nom_region):
    """Analyse complète d'une région"""
    api = GeoAPIGouv()
    
    # Trouver la région
    regions = api.rechercher_regions(nom=nom_region, limit=1)
    if not regions:
        return f"Région '{nom_region}' non trouvée"
        
    region = regions[0]
    print(f"=== {region['nom']} ===")
    
    # Départements de la région
    departements = api.obtenir_departements_region(region['code'])
    print(f"Départements ({len(departements)}):")
    for dept in departements:
        print(f"  - {dept['nom']} ({dept['code']})")
    
    return f"Analyse terminée pour {region['nom']}"

# Utilisation
analyser_region("Bretagne")

🔧 Gestion des erreurs

Le wrapper gère automatiquement les erreurs HTTP et retourne les exceptions requests.RequestException en cas de problème :

try:
    commune = api.obtenir_commune("CODE_INEXISTANT")
except requests.RequestException as e:
    print(f"Erreur API: {e}")

🔥 Méthodes Exclusives aux Dataclasses

La version dataclasses offre des méthodes avancées utilisant les propriétés des objets :

Analyses Avancées

from geo_api_gouv_v2 import GeoAPIGouv

api = GeoAPIGouv()

# Communes les plus peuplées
grandes_villes = api.communes_les_plus_peuplees(limit=10)
for ville in grandes_villes:
    print(f"{ville.nom}: {ville.population:,} hab - {ville.densite:.0f} hab/km²")

# Uniquement les métropoles
metropoles = api.metropoles()
for metro in metropoles:
    print(f"{metro.nom} - {metro.type_complet}")

# Filtrage par zone géographique
communes_drom = api.communes_drom(limit=10)
communes_metropole = api.communes_metropole(limit=10)

Propriétés Utiles des Dataclasses

Commune

• commune.densite : Densité de population (hab/km²)
• commune.est_metropole / commune.est_drom / commune.est_com
• commune.est_arrondissement / commune.est_commune_actuelle
• commune.code_postal_principal : Premier code postal
• commune.distance_vers(autre_commune) : Distance en km

EPCI

• epci.est_metropole / epci.est_communaute_urbaine / etc.
• epci.type_complet : Nom complet du type d'EPCI
• epci.densite : Densité de population

Département / Région

• departement.est_metropole / departement.numero
• region.est_metropole / region.est_drom / region.est_com

Coordonnées

• coordonnees.distance_vers(autres) : Distance entre deux points

📄 Structure du projet

py_api_decoupage_administratif/
├── models.py                    # Dataclasses et modèles
├── geo_api_gouv.py             # Wrapper classique (dictionnaires)
├── geo_api_gouv_v2.py          # Wrapper avec dataclasses (recommandé)
├── exemple_utilisation.py      # Exemples version classique
├── exemple_utilisation_v2.py   # Exemples version dataclasses
├── README.md                   # Documentation
├── CLAUDE.md                   # Guide pour Claude Code
└── docs/                       # Documentation API officielle
    ├── swagger-1.1.yml                             # Spécification OpenAPI/Swagger
    ├── API Découpage administratif.md
    ├── API Découpage administratif_communes.md
    ├── API Découpage administratif_departements.md
    ├── API Découpage administratif_regions.md
    ├── API Découpage administratif_epcis.md
    └── API Découpage administratif_communes-associees-deleguees.md

🤝 Contribution

Ce wrapper couvre l'ensemble des fonctionnalités documentées de l'API geo.api.gouv.fr. Pour toute amélioration ou correction, n'hésitez pas à contribuer !

📜 Licence

Ce projet utilise l'API publique geo.api.gouv.fr qui est mise à disposition par l'État français.

🔗 Liens utiles

• API officielle geo.api.gouv.fr
• Documentation complète de l'API
• Code source sur la forge publique