# Preparation API / open data pour Foncier narratif

## Principe

Le noyau cartographique des batiments historiques reste local dans PostGIS, car il porte les geometries, l'annee d'apparition et les croisements spatiaux lourds. Les donnees statistiques publiques peuvent en revanche etre preparees par connecteurs API puis mises en cache JSON.

Le front ne doit pas appeler directement les API publiques. Il appelle l'API FastAPI du projet, qui normalise les formats, gere le cache et conserve les sources/millesimes.

## Sources preparees

| Source | Usage | Strategie |
|---|---|---|
| API Geo | liste communes/EPCI du perimetre AULA, codes INSEE, rattachements | appel live possible + cache |
| INSEE API Melodi / donnees locales | population, menages, classes d'age, naissances, revenus selon disponibilite | API + cache, token possible |
| CONSOENAF 2009-2024 / data.gouv | consommation ENAF communale, rythme annuel, trajectoire ZAN | metadata API + fichier cache |
| SDES Sitadel / Dido | logements autorises, locaux, permis d'amenager, dynamique de construction | API ou export Dido + cache |
| Georisques | risques par commune, documents PPR, metadonnees PPRi | API + cache ; croisement spatial dans PostGIS |
| DEPP / data.gouv | optionnel : effectifs scolaires, classes, niveaux | metadata API + cache |

## Endpoints ajoutes

```text
GET  /api/open-data/sources
GET  /api/open-data/aula-scope
GET  /api/open-data/context?territoire=...
POST /api/open-data/refresh/geo
POST /api/open-data/refresh/conso-enaf-metadata
```

## Script de rafraichissement

```bash
python scripts/refresh_open_data.py --geo
python scripts/refresh_open_data.py --conso-enaf-metadata
python scripts/refresh_open_data.py --all
```

## Perimetre AULA

Le fichier `data/aula_scope.example.json` donne une amorce par EPCI. Il faut le valider avec le perimetre officiel de l'agence avant toute production.

Parametres possibles dans `.env` :

```text
AULA_SCOPE_FILE=data/aula_scope.example.json
AULA_CACHE_DIR=data/cache
```

## Contrat de donnees front

Le front peut consommer `GET /api/open-data/context` des maintenant. Les blocs `sociodemo`, `consumption`, `construction` et `risks` renvoient un statut explicite :

- `prepared_not_loaded` : connecteur pret, cache non rempli ;
- `metadata_ready` : metadonnees chargees ;
- `ok` : valeurs chargees et pretes pour affichage.

Cela permet d'afficher les cartes et de masquer les statistiques non encore alimentees sans casser l'interface.

## A garder dans PostGIS

- batiments historiques et geometries ;
- tuiles vectorielles ou GeoJSON optimise ;
- croisements batiments x risques ;
- croisements batiments x foncier contraint ;
- calculs d'emprise et densite spatiale.