# 📋 ANALYSE COMPLÈTE DE L'API INFOPARCELLE

**Date d'analyse:** 2025-11-17
**Fichier source:** `/home/user/Infoparcelle-MCP/docs-openapi.json` (1.2MB)
**Version API:** 1.0
**URL de base:** https://app.infoparcelle.fr

---

## 📊 STATISTIQUES GLOBALES

- **Nombre total d'endpoints:** 20
- **Nombre total de paramètres:** 410
- **Nombre de catégories:** 4
- **Formats supportés:** JSON, GeoJSON, SVG
- **Authentification:** Bearer Token (API Key)
- **Limite de débit:** 1200 requêtes/minute (20 req/s)

---

## 🎯 RÉSUMÉ EXÉCUTIF

L'API Infoparcelle est une API REST complète donnant accès à des données foncières, cadastrales et immobilières pour la France métropolitaine et les DOM. Elle agrège des données provenant de multiples sources officielles (DGFiP, ADEME, Géorisques, INPI, INSEE, etc.).

### Catégories principales:

1. **Géocodage** (3 endpoints) - Conversion adresses ↔ coordonnées
2. **Parcelles** (4 endpoints) - Recherche et données cadastrales
3. **Données territoriales** (6 endpoints) - Régions, départements, communes, etc.
4. **Données foncières & immobilières** (7 endpoints) - DPE, DVF, PLU, Permis, etc.

---

## 📑 LISTE COMPLÈTE DES ENDPOINTS

### 🌍 GÉOCODAGE (3 endpoints)

#### 1. `GET /api/v1/geocoder/search`
- **Résumé:** Rechercher des adresses par texte libre
- **Paramètres:** 7 total | 1 REQUIS (`recherche`)
- **Champs de réponse:** identifiant_ban, adresse_complete, numero, nom_voie, municipalite, parcelles, centre, similarite

#### 2. `GET /api/v1/geocoder/ban/{identifiant_ban}`
- **Résumé:** Rechercher une adresse par son identifiant BAN
- **Paramètres:** 3 total | 1 REQUIS (`identifiant_ban`)
- **Champs de réponse:** identifiant_ban, adresse_complete, numero, nom_voie, municipalite, parcelles, centre

#### 3. `GET /api/v1/geocoder/coordinates`
- **Résumé:** Rechercher une parcelle par coordonnées géographiques (géocodage inverse)
- **Paramètres:** 5 total | 2 REQUIS (`lat`, `lon`)
- **Champs de réponse:** identifiant_cadastre, section, numero, prefixe, superficie, perimetre, arpente, municipalite, centre, contour, bbox

---

### 🏘️ PARCELLES (4 endpoints)

#### 1. `GET /api/v1/parcelles/recherche`
- **Résumé:** Recherche de parcelles avec filtres multiples
- **Paramètres:** 79 total | Tous optionnels
- **Note importante:** Au moins UN filtre géographique REQUIS parmi: `code_departement`, `code_municipalite`, `code_postal`, `code_iris`, ou la paire `lat`+`lon`
- **Filtres disponibles:**
  - Géographiques: département, commune, code postal, IRIS, coordonnées GPS
  - Cadastraux: section, parcelle multiple
  - Fonciers: superficie, jardin, emprise sol, surface habitable, altitude
  - Bâtiments: type de bâti, piscine, hauteur, année construction, étages, mitoyenneté
  - DPE: étiquette énergie/GES, date réception
  - Énergie: consommations électrique/gaz résidentielle/tertiaire
  - DVF: prix, date, type de bien
  - Permis: type, état, nature, catégorie demandeur
  - PLU: zone, type de zone
  - Risques: argile, radon
  - Estimation: prix, prix/m²
- **Champs de réponse:** cadastre_id, superficie, perimetre, arpente, section, municipalite, centre, contour, bbox

#### 2. `POST /api/v1/parcelles/recherche`
- **Résumé:** Recherche avancée de parcelles avec filtres configurables (POST pour requêtes complexes)
- **Request Body:** JSON avec structure de filtres
- **Champs de réponse:** Identiques au GET

#### 3. `GET /api/v1/parcelles/{cadastre_id}`
- **Résumé:** Obtenir une fiche parcelle complète par son identifiant cadastral
- **Paramètres:** 4 total | 1 REQUIS (`cadastre_id`)
- **Champs de réponse (27 champs):** cadastre_id, section, numero, prefixe, superficie, perimetre, arpente, municipalite, quartier, lieu_dit, adresses, detail, batiments, zones_plu, dpes, dvfs, coproprietaires, proprietaires, occupants, permis_construire, risques, monuments_historiques, consommations, statistiques, centre, contour, bbox

#### 4. `GET /api/v1/parcelles/previsualisation/{cadastre_id}`
- **Résumé:** Générer une prévisualisation SVG d'une parcelle
- **Paramètres:** 12 total | 1 REQUIS (`cadastre_id`)
- **Format de réponse:** `image/svg+xml`

---

### 🗺️ DONNÉES TERRITORIALES (6 endpoints)

#### 1. `GET /api/v1/regions`
- **Résumé:** Rechercher des régions françaises
- **Paramètres:** 11 total | Tous optionnels
- **Champs de réponse:** nom, code, superficie, perimetre, centre, contour, bbox

#### 2. `GET /api/v1/departements`
- **Résumé:** Rechercher des départements français
- **Paramètres:** 12 total | Tous optionnels
- **Champs de réponse:** nom, code, region, superficie, perimetre, centre, contour, bbox

#### 3. `GET /api/v1/municipalities`
- **Résumé:** Rechercher des communes françaises
- **Paramètres:** 13 total | Tous optionnels
- **Champs de réponse:** nom, code, codes_postaux, superficie, population, departement, region, est_rnu, perimetre, centre, contour, bbox

#### 4. `GET /api/v1/sections`
- **Résumé:** Rechercher des sections cadastrales
- **Paramètres:** 14 total | Tous optionnels
- **Champs de réponse:** code, municipalite, departement, region, superficie, perimetre, centre, contour, bbox

#### 5. `GET /api/v1/quartiers`
- **Résumé:** Rechercher des quartiers (IRIS)
- **Paramètres:** 16 total | Tous optionnels
- **Champs de réponse:** code, nom, type, municipalite, departement, region, superficie, perimetre, centre, contour, bbox

#### 6. `GET /api/v1/epci`
- **Résumé:** Rechercher des EPCI (Établissements publics de coopération intercommunale)
- **Paramètres:** 12 total | Tous optionnels
- **Champs de réponse:** code, nom, nature, superficie, perimetre, centre, contour, bbox

---

### 🏢 DONNÉES FONCIÈRES & IMMOBILIÈRES (7 endpoints)

#### 1. `GET /api/v1/dpes`
- **Résumé:** Rechercher des Diagnostics de Performance Énergétique (DPE)
- **Paramètres:** 33 total | Tous optionnels
- **Filtres disponibles:**
  - Identifiants: numero_dpe, code_parcelle, code_section, code_municipalite
  - Caractéristiques: type_dpe, etiquette_dpe, etiquette_ges, type_batiment, bati_type
  - Dates: date_etablissement, date_reception
  - Construction: annee_construction, surface_habitable
  - Performance: conso_energie, emission_ges, cout_total
  - Localisation: code_postal, lat/lon
- **Champs de réponse (31 champs):** numero_dpe, type_dpe, date_etablissement, date_reception, date_visite, date_fin_validite, version, etiquette_dpe, etiquette_ges, adresse, type_batiment, bati_type, annee_construction, periode_construction, surface_habitable, nombre_niveau_logement, hauteur_sous_plafond, conso_energie, conso_chauffage, conso_ecs, conso_refroidissement, conso_eclairage, emission_ges, emission_ges_chauffage, emission_ges_ecs, cout_total, cout_chauffage, cout_ecs, parcelles, municipalite, centre

#### 2. `GET /api/v1/dvfs`
- **Résumé:** Rechercher des transactions immobilières (Demandes de Valeurs Foncières)
- **Paramètres:** 48 total | Tous optionnels
- **Filtres disponibles:**
  - Identifiants: code, code_parcelle, code_section, code_municipalite
  - Transaction: code_type_bien, valeur_fonciere, date_mutation, nature_mutation, vefa
  - Surfaces: surface_habitable, surface_terrain, surface_batie, surface_maisons, surface_appartements, surface_activite
  - Comptages: nb_lots, nb_parcelles, nb_locaux, nb_maisons, nb_appartements, nb_dependances, nb_locaux_activite
  - Localisation: code_postal, lat/lon
- **Champs de réponse (25 champs):** id_mutation, date_mutation, nature_mutation, valeur_fonciere, vefa, code_type_bien, libelle_type, bati_type, nb_dispositions, nb_lots, nb_parcelles, nb_parcelles_mutees, nb_locaux, nb_maisons, nb_appartements, nb_dependances, nb_locaux_activite, surface_terrain, surface_batie, surface_maisons, surface_appartements, surface_activite, parcelles, municipalite, centre

#### 3. `GET /api/v1/plu`
- **Résumé:** Rechercher des zones PLU avec leurs documents associés
- **Paramètres:** 15 total | Tous optionnels
- **Filtres disponibles:**
  - Zones: zone (A, Ah, AUc, AUs, N, Nd, Nh, U), type_zone (ex: UBa, AUs, U1e)
  - Localisation: code_postal, lat/lon, code_parcelle, code_section, code_municipalite
- **Champs de réponse (12 champs):** titre, description, zone, type_zone, surface, perimetre, documents, parcelles, municipalite, bbox, centre, contour

#### 4. `GET /api/v1/permis`
- **Résumé:** Rechercher des permis de construire et autres autorisations d'urbanisme
- **Paramètres:** 64 total | Tous optionnels
- **Filtres disponibles:**
  - Identifiants: code, siren_dem
  - État: type_autorisation, etat, cat_dem
  - Dates: date_autorisation, date_doc, date_daact
  - Projet: zone_op, nature_projet, extension, surelevation, nivsupp, nb_niv_max
  - Usage: utilisation, res_princip_ou_second, type_annexe, residence
  - Logements: nb_chambres, nb_lgt_ind_crees, nb_lgt_col_crees, nb_lgt_demolis, nb_lgt_1p à 6p_plus, nb_lgt_pret_loc_social
  - Surfaces: surf_hab (avant/creee/issue_transfo/demolie/transformee), surf_autre (idem), surf_totale
  - Localisation: code_postal, lat/lon, code_parcelle, code_section, code_municipalite
- **Champs de réponse (44 champs):** code, type_autorisation, etat, date_autorisation, date_doc, date_daact, cat_dem, siren_dem, denomination_dem, rec_archi, zone_op, nature_projet, extension, surelevation, nivsupp, nb_niv_max, utilisation, res_princip_ou_second, type_annexe, residence, nb_chambres, nb_lgt_ind_crees, nb_lgt_col_crees, nb_lgt_demolis, nb_lgt_1p à 6p_plus, nb_lgt_pret_loc_social, surf_hab_avant, surf_hab_creee, surf_hab_issue_transfo, surf_hab_demolie, surf_hab_transformee, surf_autre_avant, surf_autre_creee, surf_autre_issue_transfo, surf_autre_demolie, surf_autre_transformee, parcelles, municipalite, centre

#### 5. `GET /api/v1/proprietaires`
- **Résumé:** Rechercher des propriétaires (personnes morales)
- **Paramètres:** 18 total | Tous optionnels
- **Filtres disponibles:**
  - Identité: siren, denomination, forme_juridique
  - Droits: code_droit (P=Pleine propriété, U=Usufruit, N=Nue-propriété, etc.)
  - Biens: type_bien (1=Bâti, 2=Non bâti)
  - Localisation: code_postal, lat/lon, code_parcelle, code_section, code_municipalite
- **Champs de réponse (19 champs):** siren, denomination, code_droit, libelle_code_droit, forme_juridique, forme_juridique_abregee, type_bien, adresse_complete, adresse_numero, adresse_indice_repetition, adresse_nature_voie, adresse_nom_voie, identification_local, subdivision_fiscale, subdivision_nature_culture, subdivision_superficie, parcelles, municipalite, centre

#### 6. `GET /api/v1/coproprietes`
- **Résumé:** Rechercher des copropriétés
- **Paramètres:** 24 total | Tous optionnels
- **Filtres disponibles:**
  - Identité: immatriculation, nom
  - Organisation: type_syndic, mandat, syndic_cooperatif, syndic_principal
  - Composition: nb_lot, nb_lot_hab_bur_com, nb_lot_hab, nb_lot_stationement, nb_asl, nb_aful, nb_union
  - Arrêtés: nb_arrete_sante, nb_arrete_peril, nb_arrete_equipement
  - Localisation: code_postal, lat/lon, code_parcelle, code_section, code_municipalite
- **Champs de réponse (29 champs):** immatriculation, nom, epci, type_syndic, mandat, adresse_complete, adresse_comp1 à comp3, nb_adresse_comp, date_reglement, residence_service, syndic_cooperatif, syndic_principal, num_syndic_principal, nb_asl, nb_aful, nb_union, nb_lot, nb_lot_hab_bur_com, nb_lot_hab, nb_lot_stationement, nb_arrete_sante, nb_arrete_peril, nb_arrete_equipement, syndic, parcelles, municipalite, centre

#### 7. `GET /api/v1/occupants`
- **Résumé:** Rechercher des occupants (établissements/entreprises)
- **Paramètres:** 20 total | Tous optionnels
- **Filtres disponibles:**
  - Identité: siret, siren, denomination_complete, denomination_usuelle
  - Activité: activite_principale, categorie_activite, naf_section, naf_division, naf_groupe
  - État: etat_administratif, caractere_employeur, tranche_effectifs
  - Dates: date_creation, date_debut
  - Localisation: code_postal, lat/lon, code_parcelle, code_section, code_municipalite
- **Champs de réponse (35 champs):** siret, siren, nic, denomination_complete, denomination_usuelle, enseigne_1 à 3, activite_principale, activite_principale_registre_metiers, nomenclature_activite_principale, categorie_activite, categorie_parent_activite, naf_section, naf_division, naf_groupe, naf_classe, naf_sous_classe, etat_administratif, caractere_employeur, tranche_effectifs, annee_effectifs, date_creation, date_debut, date_dernier_traitement, etablissement_siege, statut_diffusion, adresse_complete, adresse_numero, adresse_indice_repetition, adresse_nom_voie, adresse_code_postal, parcelle, municipalite, centre

---

## 🔧 FONCTIONNALITÉS TRANSVERSALES

### Pagination
- **Type:** Cursor-based pagination (pagination par curseur)
- **Paramètres:**
  - `limite`: Nombre de résultats par page (défaut: 10, max: 50)
  - `curseur`: Token opaque pour accéder à la page suivante
- **Headers de réponse:**
  - `X-Pagination-Limit`: Nombre de résultats par page
  - `X-Pagination-Cursor`: Curseur actuel
  - `X-Pagination-Next-Cursor`: Curseur pour la page suivante
  - `X-Pagination-Has-More`: Indique s'il y a plus de résultats

### Formats de sortie
- **`format=json`** (défaut): Format JSON simple
- **`format=geojson`**: Format GeoJSON (FeatureCollection) conforme RFC 7946

### Types de géométries
- **`geometrie=centre`** (défaut): Point central (GeoJSON Point)
- **`geometrie=contour`**: Géométrie complète (GeoJSON Polygon/MultiPolygon)
- **`geometrie=bbox`**: Boîte englobante rectangulaire

### Personnalisation des champs
- **Paramètre `champs`**: Liste de champs à retourner (séparés par des virgules)
- Réduit la taille des données transférées
- Améliore les performances

### Tri
- **`champ_tri`**: Champ utilisé pour le tri (varie selon l'endpoint)
- **`ordre_tri`**: Direction du tri (`asc` ou `desc`)

---

## 🔑 AUTHENTIFICATION

**Méthode:** Bearer Token (API Key)

**Format du header:**
```
Authorization: Bearer VOTRE_CLE_API
```

**Format de la clé API:**
```
MON_APP_WEB_a8Kf9jM2pL5qR7tY3wX6zB1vC4
```
- Préfixe: `MON_APP_WEB` (identifie votre application)
- Token: `a8Kf9jM2pL5qR7tY3wX6zB1vC4` (partie aléatoire sécurisée)

**Obtention de la clé:**
1. Créer un compte sur https://www.infoparcelle.fr
2. Souscrire à un plan API
3. Générer une clé API depuis: https://www.infoparcelle.fr/compte/api

---

## ⚠️ LIMITES ET QUOTAS

- **Limite de débit:** 1200 requêtes/minute (20 req/s)
- **Réinitialisation:** Automatique chaque minute
- **En cas de dépassement:** Erreur 429 avec header `Retry-After`

---

## 📋 CODES DE RÉPONSE HTTP

| Code | Description |
|------|-------------|
| 200 | Succès |
| 400 | Requête invalide (paramètres malformés) |
| 401 | Non authentifié (token manquant/invalide) |
| 403 | Accès refusé (quota dépassé, permissions insuffisantes) |
| 404 | Ressource non trouvée |
| 429 | Trop de requêtes (débit dépassé) |
| 432 | Abonnement requis |
| 433 | Moyen de paiement invalide |
| 434 | Quota dépassé |
| 435 | Mise à niveau requise |
| 500 | Erreur interne du serveur |
| 503 | Service temporairement indisponible |

---

## 💡 BONNES PRATIQUES

1. **Espacez vos requêtes** pour rester sous la limite de 20 req/s
2. **Gérez les erreurs 429** avec un système de retry
3. **Utilisez le paramètre `champs`** pour ne récupérer que les données nécessaires
4. **Privilégiez `geometrie=centre`** si vous n'avez pas besoin des contours complets
5. **Mettez en cache** les données peu volatiles (géométries, références cadastrales)
6. **Utilisez la pagination** pour traiter de grands volumes de données

---

## 📚 RESSOURCES

- **Documentation officielle:** https://infoparcelle.fr
- **Compte API:** https://www.infoparcelle.fr/compte/api
- **Support:** contact@infoparcelle.fr
- **CGU:** https://infoparcelle.fr/cgu

---

## 🎯 CAS D'USAGE PRINCIPAUX

### 1. Recherche d'une adresse
```
GET /api/v1/geocoder/search?recherche=7 Rue de l'Elysée 75008 Paris
```

### 2. Obtenir les infos d'une parcelle
```
GET /api/v1/parcelles/{cadastre_id}?champs=superficie,batiments,dpes,dvfs
```

### 3. Rechercher des parcelles avec piscine dans une commune
```
GET /api/v1/parcelles/recherche?code_municipalite=75056&piscine=true
```

### 4. Trouver les DPE d'une zone
```
GET /api/v1/dpes?code_postal=75008&etiquette_dpe=D,E,F,G
```

### 5. Historique des transactions d'une parcelle
```
GET /api/v1/dvfs?code_parcelle=75056000AB0001
```

### 6. Permis de construire dans un département
```
GET /api/v1/permis?code_departement=75&etat=2&date_autorisation_min=2023-01-01
```

---

## 📄 FICHIERS GÉNÉRÉS PAR L'ANALYSE

- `/tmp/analyse_complete_api.txt` - Analyse détaillée complète (1334 lignes)
- `/tmp/api_documentation.md` - Documentation Markdown (1421 lignes)
- `/tmp/api_structure.json` - Structure JSON complète (7845 lignes)
- `/tmp/response_fields.txt` - Liste des champs de réponse (474 lignes)
- `/home/user/Infoparcelle-MCP/ANALYSE_API_COMPLETE.md` - Ce document

---

**Fin de l'analyse - Document généré automatiquement le 2025-11-17**