# Connecteurs API - Foncier narratif

Ce lot prepare le maximum de donnees recuperables hors PostGIS, en restant limite au perimetre AULA.

## Principe de perimetre

Le fichier `data/agency_scope.json` contient la liste des EPCI utilises comme perimetre applicatif. Par defaut :

- CA de Lens-Lievin (`246200364`)
- CA d'Henin-Carvin (`246200299`)
- CA de Bethune-Bruay, Artois-Lys Romane (`200072460`)
- CC du Ternois (`200069672`)
- CC des 7 Vallees (`200044030`)

Ces codes sont une amorce de travail : ils doivent etre valides avec le referentiel interne de l'agence avant une publication.

## Sources preparees

| Source | Connecteur | Usage dans l'application | Strategie |
|---|---|---|---|
| API Geo | `external/geo_api.py` | Communes, EPCI, rattachement commune-EPCI | appel live ou cache |
| INSEE Melodi | `external/insee_melodi.py` | population, recensement, menages, socio-demo | API + cache |
| data.gouv / artificialisation | `external/artificialisation.py` | consommation ENAF, trajectoire ZAN | metadonnees + filtrage CSV par EPCI/commune |
| SDES Sitadel | `external/sitadel.py` | logements autorises, locaux, PA, PD | metadonnees + filtrage CSV par communes AULA |
| Georisques | `external/georisques.py` | risques par commune, PPRN/PPRi metadata | API + cache |

## Endpoints ajoutes

```text
GET /api/agency/scope
GET /api/agency/scope?live=true
GET /api/external/sources
GET /api/external/status
GET /api/external/artificialisation/metadata
GET /api/external/artificialisation/status
GET /api/external/artificialisation/consumption?territoire=62001&niveau=commune
GET /api/external/artificialisation/consumption?territoire=62001&niveau=commune&live=true
GET /api/external/artificialisation/cerema?code=62001&niveau=commune&force=true
GET /api/external/sitadel/metadata
GET /api/external/insee/catalog?q=population
GET /api/external/insee/population-reference?epci=246200364
GET /api/external/georisques/commune/62427
GET /api/indicators?territoire=demo
```

## Commandes de rafraichissement

```bash
python scripts/refresh_external_cache.py --source geo --force
python scripts/refresh_external_cache.py --source artificialisation --level epci --force
python scripts/refresh_external_cache.py --source artificialisation --level epci --code 246200364 --force
python scripts/refresh_external_cache.py --source artificialisation --level commune --code 62001 --force
python scripts/refresh_external_cache.py --source sitadel --sitadel-kind logements --force
python scripts/refresh_external_cache.py --source georisques --force
python scripts/refresh_external_cache.py --source insee --force
```

## Regle de stockage

- PostGIS reste la source locale pour les batiments historiques, geometries, croisements spatiaux et tuiles.
- Les API publiques alimentent un cache local pour les statistiques de contexte.
- Le front appelle uniquement FastAPI, jamais directement les API publiques.

## Points a valider

1. Perimetre officiel complet de l'agence, communes isolees incluses si besoin.
2. Choix des indicateurs socio-demo exacts dans Melodi.
3. Colonnes exactes des fichiers Sitadel et artificialisation apres premier telechargement.
4. Frequence de rafraichissement : mensuelle pour Sitadel, annuelle ou au millesime pour artificialisation et INSEE.
5. Croisements spatiaux risques x batiments a conserver dans PostGIS.