# 📖 DOCUMENTATION API INFOPARCELLE - INDEX

Ce répertoire contient une analyse complète de l'API Infoparcelle extraite depuis `docs-openapi.json`.

## 📁 Fichiers générés

### 1. **GUIDE_IMPLEMENTATION_MCP.md** ⭐ (À LIRE EN PREMIER)
- **Contenu:** Résumé exécutif pour l'implémentation MCP
- **Taille:** Guide condensé et pratique
- **Usage:** Référence rapide pour implémenter les 20 endpoints
- **Inclut:**
  - Vue d'ensemble des 20 endpoints
  - Paramètres requis et optionnels pour chaque endpoint
  - Suggestions d'outils MCP à créer
  - Bonnes pratiques (gestion erreurs, performance, formats)

### 2. **RAPPORT_API_COMPLET.md** 📚
- **Contenu:** Documentation exhaustive de tous les endpoints
- **Taille:** 1699 lignes, 71 KB
- **Usage:** Documentation détaillée pour l'implémentation
- **Inclut:**
  - Description complète de chaque endpoint
  - Tous les paramètres avec types et descriptions
  - Tous les champs de réponse avec leurs types
  - Codes de réponse HTTP

### 3. **ENUMERATIONS_API.md** 📋
- **Contenu:** Liste complète de toutes les valeurs possibles
- **Taille:** 1400 lignes, 38 KB
- **Usage:** Référence pour la validation des paramètres
- **Inclut:**
  - Énumérations par thématique
  - Toutes les valeurs possibles pour chaque paramètre
  - Types de bâtiments (bati_type)
  - Étiquettes DPE/GES
  - Codes DVF, types de permis, zones PLU, etc.

### 4. **docs-openapi.json** (Original)
- **Contenu:** Spécification OpenAPI 3.0.0 complète
- **Taille:** 18759 lignes, 1.2 MB
- **Usage:** Source de vérité pour l'API

## 🎯 Comment utiliser cette documentation

### Pour démarrer rapidement
1. Lire **GUIDE_IMPLEMENTATION_MCP.md** en premier
2. Identifier les endpoints nécessaires pour votre cas d'usage
3. Consulter **RAPPORT_API_COMPLET.md** pour les détails d'implémentation

### Pour une implémentation complète
1. **GUIDE_IMPLEMENTATION_MCP.md** → Vue d'ensemble
2. **RAPPORT_API_COMPLET.md** → Détails techniques
3. **ENUMERATIONS_API.md** → Validation des données
4. **docs-openapi.json** → Vérification finale

## 📊 Statistiques de l'API

### Endpoints par catégorie
| Catégorie | Nombre | Endpoints clés |
|-----------|--------|----------------|
| **Géocodage** | 3 | Recherche d'adresses, géocodage inversé |
| **Parcelles** | 4 | Recherche, fiche complète, prévisualisation SVG |
| **Territoires** | 13 | Régions, départements, communes, sections, quartiers, EPCI, DPE, DVF, PLU, permis, propriétaires, copropriétés, occupants |
| **TOTAL** | **20** | |

### Complexité des endpoints
- **Simple** (< 10 paramètres): 9 endpoints
- **Moyen** (10-30 paramètres): 7 endpoints
- **Complexe** (> 30 paramètres): 4 endpoints

### Endpoints les plus puissants
1. **GET/POST /api/v1/parcelles/recherche** - 79 paramètres de filtrage
2. **GET /api/v1/permis** - 64 paramètres
3. **GET /api/v1/dvfs** - 48 paramètres
4. **GET /api/v1/dpes** - 33 paramètres

## 🔑 Concepts clés de l'API

### Authentification
```
Authorization: Bearer YOUR_API_KEY
```

### Formats de réponse
- **JSON** (`format=json`) - Format standard
- **GeoJSON** (`format=geojson`) - Pour SIG
- **SVG** - Pour visualisation parcelles

### Types de géométries
- **centre** - Point central (léger)
- **contour** - Polygone complet (précis)
- **bbox** - Boîte englobante (minimal)

### Pagination
- Basée sur curseur (cursor-based)
- Headers: `X-Pagination-*`
- Limite: 10-50 résultats par page

### Rate Limiting
- **Limite:** 1200 requêtes/minute (20/sec)
- **Dépassement:** HTTP 429 avec `Retry-After`

## 🛠️ Outils MCP suggérés

### Priorité 1 (Essentiels)
1. `geocode_address` - Recherche d'adresses
2. `search_parcels` - Recherche de parcelles
3. `get_parcel_info` - Fiche parcelle complète
4. `search_municipalities` - Recherche de communes

### Priorité 2 (Importants)
5. `reverse_geocode` - Coordonnées → Parcelle
6. `search_dpe` - Diagnostics énergétiques
7. `search_dvf` - Transactions immobilières
8. `search_plu` - Zones d'urbanisme

### Priorité 3 (Optionnels)
9. `get_parcel_svg` - Visualisation
10. `search_permis` - Permis de construire
11. `search_proprietaires` - Propriétaires
12. `search_coproprietes` - Copropriétés
13. `search_occupants` - Établissements

## 💡 Cas d'usage typiques

### 1. Recherche immobilière
- `geocode_address` → Trouver l'adresse
- `search_parcels` → Chercher des parcelles dans la zone
- `get_parcel_info` → Détails complets (DPE, DVF, PLU)

### 2. Analyse territoriale
- `search_municipalities` → Trouver la commune
- `search_parcels` → Parcelles de la commune
- `search_dpe` → Analyse énergétique
- `search_dvf` → Analyse du marché

### 3. Étude d'urbanisme
- `reverse_geocode` → Identifier la parcelle
- `get_parcel_info` → Informations complètes
- `search_plu` → Règles d'urbanisme
- `search_permis` → Historique des permis

### 4. Due diligence immobilière
- `get_parcel_info` → Données cadastrales
- `search_proprietaires` → Propriétaires
- `search_dvf` → Historique des ventes
- `search_dpe` → Performance énergétique
- `search_coproprietes` → Si copropriété

## ⚠️ Points d'attention

### Validation des paramètres
- **Filtres géographiques obligatoires** pour la recherche de parcelles
- Vérifier les formats de dates (YYYY-MM-DD)
- Respecter les limites min/max (ex: limite ≤ 50)

### Gestion des erreurs
- **400**: Valider paramètres avant envoi
- **401**: Vérifier token d'authentification
- **403**: Gérer quotas et permissions
- **429**: Implémenter retry avec backoff
- **432-435**: Problèmes de facturation

### Performance
- Utiliser `champs` pour limiter les données
- Préférer `geometrie=centre` pour les listes
- Mettre en cache les données statiques
- Respecter le rate limit

## 📞 Support

- **Email:** contact@infoparcelle.fr
- **Documentation officielle:** https://infoparcelle.fr/docs
- **API:** https://app.infoparcelle.fr/api/v1

---

*Documentation générée automatiquement le 2025-11-17*
*Source: docs-openapi.json (API Infoparcelle v1.0)*