# Socio-démographie INSEE

## Objectif

Le chapitre **Comprendre** doit rester léger et expliquer le lien entre foncier, population et ménages.

Indicateurs retenus pour la V1 :

- population municipale ou population EPCI selon le filtre ;
- évolution de la population depuis la première année disponible ;
- nombre de ménages et évolution ;
- densité ;
- taille moyenne des ménages.

La taille moyenne des ménages est volontairement ajoutée car elle explique souvent le besoin de logements même lorsque la population est stable ou baisse.

## Logique de filtre

L'application utilise les mêmes paramètres que la carte des bâtiments :

```text
/api/indicators?territoire=62498&niveau=commune
/api/indicators?territoire=200072460&niveau=epci
```

## Priorité de lecture des données

L'application cherche les données dans cet ordre :

1. `foncier_poc.v_sociodemo_insee` si la vue existe ;
2. fichier cache JSON `data/cache/insee_sociodemo_<niveau>_<code>.json` ;
3. API Géo pour population/surface actuelle uniquement ;
4. valeurs de démonstration explicites.

Ce choix évite de déclencher un appel API lourd à chaque ouverture de page.

## Vue PostGIS optionnelle

Si un script de rafraîchissement INSEE alimente PostgreSQL, la vue attendue est :

```sql
CREATE OR REPLACE VIEW foncier_poc.v_sociodemo_insee AS
SELECT
  'commune'::text AS niveau,
  code_insee::text AS code_territoire,
  annee::integer AS year,
  population::double precision AS population,
  menages::double precision AS households,
  densite::double precision AS density,
  'INSEE RP'::text AS source,
  millesime::text AS millesime
FROM ...;
```

Pour les EPCI, la même vue peut contenir `niveau='epci'` et `code_territoire=<SIREN EPCI>`.

## Cache JSON optionnel

Format attendu :

```json
{
  "source": "INSEE RP",
  "millesime": "2021",
  "series": [
    {"year": 1975, "population": 12000, "households": 4200, "type": "observed"},
    {"year": 1982, "population": 12500, "households": 4700, "type": "observed"},
    {"year": 2021, "population": 11800, "households": 5600, "type": "observed"}
  ]
}
```

Nom du fichier :

```text
data/cache/insee_sociodemo_commune_62498.json
data/cache/insee_sociodemo_epci_200072460.json
```

## API

Endpoint de test :

```text
/api/external/insee/sociodemo?territoire=62498&niveau=commune
```

L'endpoint retourne toujours un statut de source : `postgis_cache`, `insee_cache_json`, `api_geo_current_partial` ou `demo_fallback`.

## Ajustement interface - données observées 2022

Le chapitre **Comprendre** affiche uniquement les données observées : population, évolution de population, ménages, densité et taille moyenne des ménages. Les projections sont retirées de cette section et restent traitées dans le chapitre **Anticiper**.

Pour le moment, l'interface indique le millésime **2022** pour la population et les ménages. Si seule l'API Géo est disponible, l'application affiche population et densité, mais signale que les ménages et les séries historiques doivent être alimentés par `v_sociodemo_insee` ou par un cache INSEE RP.