# 🚀 API INFOPARCELLE - RÉFÉRENCE RAPIDE

## 📊 Vue d'ensemble
- **20 endpoints** répartis en 4 catégories
- **410 paramètres** au total
- **Base URL:** https://app.infoparcelle.fr
- **Auth:** Bearer Token
- **Limite:** 1200 req/min (20 req/s)

---

## 🔑 Authentification
```
Authorization: Bearer VOTRE_CLE_API
```
Clé API disponible sur: https://www.infoparcelle.fr/compte/api

---

## 📋 ENDPOINTS PAR CATÉGORIE

### 🌍 GÉOCODAGE (3)
| Méthode | Endpoint | Description |
|---------|----------|-------------|
| GET | `/api/v1/geocoder/search` | Recherche adresse par texte |
| GET | `/api/v1/geocoder/ban/{id}` | Recherche par ID BAN |
| GET | `/api/v1/geocoder/coordinates` | Géocodage inverse (lat/lon → parcelle) |

### 🏘️ PARCELLES (4)
| Méthode | Endpoint | Description | Paramètres |
|---------|----------|-------------|------------|
| GET | `/api/v1/parcelles/recherche` | Recherche multicritères | 79 filtres |
| POST | `/api/v1/parcelles/recherche` | Recherche avancée (POST) | Body JSON |
| GET | `/api/v1/parcelles/{cadastre_id}` | Fiche parcelle complète | 27 champs |
| GET | `/api/v1/parcelles/previsualisation/{id}` | Prévisualisation SVG | 12 options |

### 🗺️ TERRITOIRES (6)
| Endpoint | Description |
|----------|-------------|
| `/api/v1/regions` | Régions françaises |
| `/api/v1/departements` | Départements |
| `/api/v1/municipalities` | Communes |
| `/api/v1/sections` | Sections cadastrales |
| `/api/v1/quartiers` | Quartiers (IRIS) |
| `/api/v1/epci` | Intercommunalités |

### 🏢 FONCIER & IMMOBILIER (7)
| Endpoint | Description | Paramètres |
|----------|-------------|------------|
| `/api/v1/dpes` | Diagnostics Performance Énergétique | 33 filtres |
| `/api/v1/dvfs` | Transactions immobilières | 48 filtres |
| `/api/v1/plu` | Plans Locaux d'Urbanisme | 15 filtres |
| `/api/v1/permis` | Permis de construire | 64 filtres |
| `/api/v1/proprietaires` | Propriétaires (personnes morales) | 18 filtres |
| `/api/v1/coproprietes` | Copropriétés | 24 filtres |
| `/api/v1/occupants` | Occupants/Établissements | 20 filtres |

---

## ⚙️ PARAMÈTRES TRANSVERSAUX

### Pagination
```
?limite=20&curseur=TOKEN_CURSEUR
```
- Défaut: 10 résultats
- Max: 50 résultats
- Headers: `X-Pagination-Next-Cursor`, `X-Pagination-Has-More`

### Formats
```
?format=json          # JSON simple (défaut)
?format=geojson       # GeoJSON FeatureCollection
```

### Géométries
```
?geometrie=centre     # Point central (défaut)
?geometrie=contour    # Polygone complet
?geometrie=bbox       # Rectangle englobant
```

### Champs personnalisés
```
?champs=cadastre_id,superficie,municipalite
```

### Tri
```
?champ_tri=date_mutation&ordre_tri=desc
```

---

## 💡 EXEMPLES RAPIDES

### Rechercher une adresse
```bash
GET /api/v1/geocoder/search?recherche=7 Rue de l'Elysée Paris
```

### Parcelle par ID cadastral
```bash
GET /api/v1/parcelles/75056000AB0001?champs=superficie,batiments,dpes
```

### Parcelles avec piscine à Paris
```bash
GET /api/v1/parcelles/recherche?code_municipalite=75056&piscine=true&superficie_min=500
```

### DPE passoires thermiques
```bash
GET /api/v1/dpes?code_postal=75008&etiquette_dpe=F,G&limite=50
```

### Transactions récentes > 1M€
```bash
GET /api/v1/dvfs?code_departement=75&valeur_fonciere_min=1000000&date_mutation_min=2024-01-01
```

### Permis autorisés récents
```bash
GET /api/v1/permis?code_municipalite=75056&etat=2&date_autorisation_min=2024-01-01
```

### Propriétaires SAS/SARL
```bash
GET /api/v1/proprietaires?forme_juridique=5710,5498&code_postal=75008
```

---

## 🎯 FILTRES PRINCIPAUX PAR ENDPOINT

### Parcelles (`/api/v1/parcelles/recherche`)
**Géo (1 REQUIS):** `code_departement`, `code_municipalite`, `code_postal`, `code_iris`, `lat+lon`

**Top filtres:**
- Surfaces: `superficie_min/max`, `surface_habitable_min/max`
- Bâti: `bati_type`, `piscine`, `etages`, `annee_construction_min/max`
- DPE: `dpe_energie`, `dpe_ges`
- DVF: `dvf_prix_min/max`, `dvf_date_min/max`
- PLU: `plu_zone`, `plu_zone_type`
- Risques: `risque_argile`, `risque_radon`

### DPE (`/api/v1/dpes`)
- `etiquette_dpe`: A, B, C, D, E, F, G
- `etiquette_ges`: A, B, C, D, E, F, G
- `type_batiment`: appartement, maison
- `annee_construction_min/max`
- `conso_energie_min/max`
- `emission_ges_min/max`

### DVF (`/api/v1/dvfs`)
- `valeur_fonciere_min/max`
- `date_mutation_min/max`
- `code_type_bien`: 111 (maison), 121 (appartement), etc.
- `surface_habitable_min/max`
- `nature_mutation`: 1 (échange), 2 (adjudication), 3 (vente), 4 (expropriation)

### Permis (`/api/v1/permis`)
- `type_autorisation`: 1 (PC logement), 2 (DP logement), 3 (PC local), 5 (PA), 6 (démolir)
- `etat`: 2 (autorisé), 5 (commencé), 6 (terminé)
- `date_autorisation_min/max`
- `nb_lgt_ind_crees_min/max`, `nb_lgt_col_crees_min/max`
- `surf_hab_min/max`, `surf_totale_min/max`

---

## 📊 CODES HTTP

| Code | Signification |
|------|---------------|
| 200 | ✅ Succès |
| 400 | ❌ Requête invalide |
| 401 | 🔒 Non authentifié |
| 403 | 🚫 Accès refusé |
| 404 | ❓ Non trouvé |
| 429 | ⏸️ Trop de requêtes |
| 432 | 💳 Abonnement requis |
| 434 | 📊 Quota dépassé |

---

## 🔍 CHAMPS DE RÉPONSE PRINCIPAUX

### Parcelles
```
cadastre_id, section, numero, prefixe, superficie, perimetre,
municipalite, quartier, batiments, zones_plu, dpes, dvfs,
proprietaires, occupants, permis_construire, risques,
centre, contour, bbox
```

### DPE
```
numero_dpe, etiquette_dpe, etiquette_ges, type_batiment,
annee_construction, surface_habitable, conso_energie,
emission_ges, cout_total, date_reception, municipalite
```

### DVF
```
id_mutation, date_mutation, nature_mutation, valeur_fonciere,
code_type_bien, bati_type, surface_batie, surface_terrain,
nb_lots, nb_locaux, nb_maisons, nb_appartements, municipalite
```

### Territoires
```
nom, code, superficie, population (communes),
nature (EPCI), centre, contour, bbox
```

---

## 📚 RESSOURCES

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

---

## ⚡ TIPS

1. ✅ Utilisez `champs` pour réduire la taille des réponses
2. ✅ Privilégiez `geometrie=centre` pour la performance
3. ✅ Mettez en cache les données territoriales
4. ✅ Gérez les erreurs 429 avec retry + backoff
5. ✅ Limitez à 20 req/s maximum
6. ✅ Pour parcelles, TOUJOURS un filtre géographique

---

**Référence rapide générée le 2025-11-17**