# 🚀 GUIDE D'IMPLÉMENTATION MCP - INFOPARCELLE API

## Vue d'ensemble

Ce document fournit un résumé exécutif de tous les endpoints disponibles dans l'API Infoparcelle, organisé pour faciliter l'implémentation des outils MCP.

## 📊 STATISTIQUES GLOBALES

- **Total d'endpoints:** 20
- **URL de base:** `https://app.infoparcelle.fr`
- **Authentification:** Bearer Token
- **Limite de débit:** 1200 req/min (20 req/sec)

## 🗂️ ENDPOINTS PAR CATÉGORIE

### 1️⃣ GÉOCODAGE (3 endpoints)

#### 1.1 Recherche d'adresses par texte
```
GET /api/v1/geocoder/search
```
- **Paramètres requis:** `recherche` (string)
- **Paramètres optionnels:** `champs`, `champ_tri`, `ordre_tri`, `limite`, `curseur`, `format`
- **Champs retournés:** `identifiant_ban`, `adresse_complete`, `numero`, `nom_voie`, `municipalite`, `parcelles`, `centre`, `similarite`
- **Use case:** Trouver des adresses par recherche textuelle

#### 1.2 Recherche par identifiant BAN
```
GET /api/v1/geocoder/ban/{identifiant_ban}
```
- **Paramètres requis:** `identifiant_ban` (path)
- **Paramètres optionnels:** `champs`, `format`
- **Champs retournés:** `identifiant_ban`, `adresse_complete`, `numero`, `nom_voie`, `municipalite`, `parcelles`, `centre`
- **Use case:** Récupérer une adresse précise par son ID BAN

#### 1.3 Géocodage inversé (coordonnées → parcelle)
```
GET /api/v1/geocoder/coordinates
```
- **Paramètres requis:** `lat` (number), `lon` (number)
- **Paramètres optionnels:** `champs`, `format`, `geometrie`
- **Champs retournés:** `identifiant_cadastre`, `section`, `numero`, `prefixe`, `superficie`, `perimetre`, `arpente`, `municipalite`, `centre`, `contour`, `bbox`
- **Use case:** Trouver la parcelle à des coordonnées GPS données

---

### 2️⃣ PARCELLES (4 endpoints)

#### 2.1 Recherche de parcelles (GET)
```
GET /api/v1/parcelles/recherche
```
- **Paramètres requis:** Au moins 1 filtre géographique (`code_departement`, `code_municipalite`, `code_postal`, `code_iris`, ou `lat`+`lon`)
- **Paramètres optionnels:** 79 paramètres de filtrage (superficie, bâtiments, DPE, DVF, PLU, etc.)
- **Champs retournés:** `cadastre_id`, `superficie`, `perimetre`, `arpente`, `section`, `municipalite`, `centre`, `contour`, `bbox`
- **Use case:** Recherche avancée de parcelles avec de nombreux critères

#### 2.2 Recherche avancée (POST)
```
POST /api/v1/parcelles/recherche
```
- **Mode:** Filtrage strict (WHERE) ou indicatif (scoring)
- **Champs retournés:** Mêmes que GET + `score_pertinence`
- **Use case:** Recherche complexe avec scoring de pertinence

#### 2.3 Fiche parcelle complète
```
GET /api/v1/parcelles/{cadastre_id}
```
- **Paramètres requis:** `cadastre_id` (path)
- **Paramètres optionnels:** `champs`, `format`, `geometrie`
- **Champs retournés (26):** Informations complètes incluant `batiments`, `zones_plu`, `dpes`, `dvfs`, `proprietaires`, `occupants`, `permis_construire`, etc.
- **Use case:** Obtenir toutes les données d'une parcelle

#### 2.4 Prévisualisation SVG
```
GET /api/v1/parcelles/previsualisation/{cadastre_id}
```
- **Paramètres requis:** `cadastre_id` (path, peut contenir plusieurs IDs séparés par virgules)
- **Paramètres optionnels:** `theme`, `width`, `height`, `dpi`, `afficher_surface`, `afficher_mesures`, etc.
- **Réponse:** Image SVG
- **Use case:** Générer une carte/plan de la parcelle

---

### 3️⃣ TERRITOIRES (13 endpoints)

#### 3.1 Régions
```
GET /api/v1/regions
```
- **Filtres:** `code`, `nom`, `lat`+`lon`
- **Champs:** `nom`, `code`, `superficie`, `perimetre`, `centre`, `contour`, `bbox`

#### 3.2 Départements
```
GET /api/v1/departements
```
- **Filtres:** `code`, `nom`, `code_region`, `lat`+`lon`
- **Champs:** `code`, `nom`, `superficie`, `perimetre`, `region`, `centre`, `contour`, `bbox`

#### 3.3 Municipalités (Communes)
```
GET /api/v1/municipalities
```
- **Filtres:** `code`, `nom`, `code_postal`, `est_rnu`, `lat`+`lon`
- **Champs:** `code`, `nom`, `codes_postaux`, `departement`, `region`, `population`, `superficie`, `est_rnu`, etc.

#### 3.4 Sections cadastrales
```
GET /api/v1/sections
```
- **Filtres:** `code`, `code_municipalite`, `code_postal`, `code_departement`, `code_region`, `lat`+`lon`
- **Champs:** `code`, `superficie`, `perimetre`, `municipalite`, `departement`, `region`, `centre`, `contour`, `bbox`

#### 3.5 Quartiers (IRIS)
```
GET /api/v1/quartiers
```
- **Filtres:** `code`, `nom`, `type`, `code_municipalite`, `code_postal`, etc.
- **Champs:** `code`, `nom`, `type`, `superficie`, `municipalite`, `departement`, `region`, etc.
- **Types IRIS:** `H` (Habitat), `A` (Activité), `D` (Divers), `Z` (Zone non habitée)

#### 3.6 EPCI
```
GET /api/v1/epci
```
- **Filtres:** `code`, `nom`, `nature`, `lat`+`lon`
- **Champs:** `code`, `nom`, `nature`, `superficie`, `perimetre`, `centre`, `contour`, `bbox`

#### 3.7 DPE (Diagnostics de Performance Énergétique)
```
GET /api/v1/dpes
```
- **Filtres (33):** `numero_dpe`, `type_dpe`, `etiquette_dpe`, `etiquette_ges`, `type_batiment`, dates, consommation, etc.
- **Champs (31):** Informations complètes sur le diagnostic énergétique
- **Étiquettes:** `A`, `B`, `C`, `D`, `E`, `F`, `G`

#### 3.8 DVF (Transactions immobilières)
```
GET /api/v1/dvfs
```
- **Filtres (48):** `code_type_bien`, `valeur_fonciere_min/max`, `surface_habitable_min/max`, `date_mutation_min/max`, etc.
- **Champs (25):** `id_mutation`, `date_mutation`, `nature_mutation`, `valeur_fonciere`, `code_type_bien`, surfaces, etc.

#### 3.9 PLU (Plans Locaux d'Urbanisme)
```
GET /api/v1/plu
```
- **Filtres:** `zone`, `type_zone`, `code_postal`, `lat`+`lon`, `code_parcelle`, etc.
- **Champs:** `titre`, `description`, `zone`, `type_zone`, `surface`, `documents`, `municipalite`, etc.
- **Zones principales:** `U` (Urbaine), `AU` (À urbaniser), `A` (Agricole), `N` (Naturelle)

#### 3.10 Permis de construire
```
GET /api/v1/permis
```
- **Filtres (64):** `code`, `type_autorisation`, `etat`, dates, catégories, surfaces, etc.
- **Champs (44):** Informations complètes sur les autorisations d'urbanisme

#### 3.11 Propriétaires (personnes morales)
```
GET /api/v1/proprietaires
```
- **Filtres:** `siren`, `denomination`, `code_droit`, `forme_juridique`, `type_bien`, localisation, etc.
- **Champs (19):** `siren`, `denomination`, `code_droit`, `forme_juridique`, `adresse_complete`, `parcelles`, etc.

#### 3.12 Copropriétés
```
GET /api/v1/coproprietes
```
- **Filtres (24):** `immatriculation`, `nom`, `type_syndic`, `mandat`, `nb_lot_min/max`, localisation, etc.
- **Champs (29):** Informations complètes sur la copropriété

#### 3.13 Occupants (établissements)
```
GET /api/v1/occupants
```
- **Filtres (20):** `siret`, `siren`, `denomination_complete`, `activite_principale`, `etat_administratif`, etc.
- **Champs (35):** Informations complètes sur l'établissement

---

## 🔑 PARAMÈTRES COMMUNS

### Pagination
- `limite` (integer): Défaut 10, max 50
- `curseur` (string): Token pour page suivante

### Tri
- `champ_tri` (string): Champ de tri
- `ordre_tri` (enum): `asc` | `desc`

### Format
- `format` (enum): `json` (défaut) | `geojson`
- `geometrie` (enum): `centre` (défaut) | `contour` | `bbox`
- `champs` (array): Liste des champs à retourner

### Filtres géographiques
- `code_departement` (string): Code INSEE 2 chiffres
- `code_municipalite` (string): Code INSEE 5 chiffres
- `code_postal` (string): Code postal 5 chiffres
- `code_iris` (string): Code IRIS (quartier)
- `code_section` (string): Code section cadastrale 2 caractères
- `lat` + `lon` (number): Coordonnées GPS (WGS84)

---

## 📝 TYPES DE DONNÉES IMPORTANTS

### Étiquettes DPE/GES
- `A`, `B`, `C`, `D`, `E`, `F`, `G`

### Zones PLU principales
- `U`: Urbaine
- `AU`: À urbaniser
- `A`: Agricole
- `N`: Naturelle et forestière

### Types IRIS
- `H`: Habitat
- `A`: Activité
- `D`: Divers
- `Z`: Zone non habitée

### Nature de mutation (DVF)
- Vente
- Vente en l'état futur d'achèvement (VEFA)
- Vente terrain à bâtir
- Adjudication
- Expropriation

---

## 🛠️ RECOMMANDATIONS POUR L'IMPLÉMENTATION MCP

### Outils MCP à créer (suggestions)

1. **geocode_address** - Recherche d'adresses
2. **reverse_geocode** - Coordonnées → Parcelle
3. **search_parcels** - Recherche de parcelles avec filtres
4. **get_parcel_info** - Fiche complète d'une parcelle
5. **get_parcel_svg** - Génération de carte SVG
6. **search_municipalities** - Recherche de communes
7. **search_dpe** - Recherche de DPE
8. **search_dvf** - Recherche de transactions
9. **search_plu** - Recherche de zones PLU
10. **search_permis** - Recherche de permis
11. **search_proprietaires** - Recherche de propriétaires
12. **search_coproprietes** - Recherche de copropriétés
13. **search_occupants** - Recherche d'établissements

### Gestion des erreurs
- 400: Valider les paramètres côté client
- 401: Vérifier le token Bearer
- 403: Gérer les quotas et permissions
- 404: Ressource non trouvée
- 429: Implémenter retry avec backoff
- 432-435: Erreurs de facturation/abonnement

### Performance
- Utiliser le paramètre `champs` pour limiter les données retournées
- Préférer `geometrie=centre` pour les listes
- Utiliser `geometrie=contour` uniquement quand nécessaire
- Implémenter un cache pour les données statiques (territoires)
- Respecter la limite de 20 req/sec

### Formats de réponse
- Par défaut: JSON simple
- Pour SIG: GeoJSON (FeatureCollection)
- Pour visualisation: SVG (parcelles)

---

## 📚 DOCUMENTATION COMPLÉMENTAIRE

- **RAPPORT_API_COMPLET.md**: Documentation détaillée de tous les endpoints (1699 lignes)
- **ENUMERATIONS_API.md**: Liste complète de toutes les valeurs possibles (1400 lignes)
- **docs-openapi.json**: Spécification OpenAPI 3.0.0 complète

---

*Document généré pour faciliter l'implémentation du serveur MCP Infoparcelle*