osm-commerces/docs/api-stats-export.md

# API - Export des objets Stats

## Endpoint

```
GET /api/v1/stats/export
```

## Description

Cet endpoint permet d'exporter les objets Stats au format JSON avec leurs propriétés de nom et de décomptes, similaire à la commande `app:export-stats`.

## Paramètres de requête

| Paramètre | Type | Défaut | Description |
|-----------|------|--------|-------------|
| `zone` | string | - | Code INSEE spécifique à exporter (optionnel) |
| `pretty` | boolean | false | Formater le JSON avec indentation |
| `include_followups` | boolean | true | Inclure les données de followup |
| `include_places` | boolean | false | Inclure les données des lieux (peut être volumineux) |

## Exemples d'utilisation

### Export de toutes les zones
```bash
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export"
```

### Export avec formatage JSON
```bash
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?pretty=true"
```

### Export d'une zone spécifique
```bash
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?zone=75056"
```

### Export d'une zone avec formatage et sans followups
```bash
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?zone=75056&pretty=true&include_followups=false"
```

### Export complet avec lieux
```bash
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?pretty=true&include_places=true"
```

## Réponse

### Succès (200 OK)

```json
[
  {
    "id": 1,
    "zone": "75056",
    "name": "Paris",
    "dateCreated": "2024-01-15 10:30:00",
    "dateModified": "2024-01-20 14:45:00",
    "population": 2161000,
    "budgetAnnuel": "8500000000",
    "siren": 200054781,
    "codeEpci": 200054781,
    "codesPostaux": "75001;75002;75003;...",
    "decomptes": {
      "placesCount": 1250,
      "avecHoraires": 980,
      "avecAdresse": 1200,
      "avecSite": 850,
      "avecAccessibilite": 450,
      "avecNote": 320,
      "completionPercent": 75,
      "placesCountReal": 1250
    },
    "followups": [
      {
        "name": "fire_hydrant_count",
        "measure": 1250,
        "date": "2024-01-20 14:45:00"
      },
      {
        "name": "fire_hydrant_completion",
        "measure": 85.5,
        "date": "2024-01-20 14:45:00"
      }
    ],
    "places": [
      {
        "id": 1,
        "name": "Boulangerie du Centre",
        "mainTag": "shop",
        "osmId": 123456,
        "osmKind": "node",
        "email": "contact@boulangerie.fr",
        "note": "Boulangerie artisanale",
        "zipCode": "75001",
        "siret": "12345678901234",
        "lat": 48.8566,
        "lon": 2.3522,
        "hasOpeningHours": true,
        "hasAddress": true,
        "hasWebsite": true,
        "hasWheelchair": false,
        "hasNote": true,
        "completionPercentage": 85
      }
    ]
  }
]
```

### Erreur - Zone non trouvée (404 Not Found)

```json
{
  "error": "Aucun objet Stats trouvé",
  "message": "Aucune zone trouvée pour le code INSEE: 99999"
}
```

### Erreur - Erreur serveur (500 Internal Server Error)

```json
{
  "error": "Erreur lors de l'export",
  "message": "Description de l'erreur"
}
```

## Headers de réponse

| Header | Description |
|--------|-------------|
| `Content-Type` | `application/json` |
| `Content-Disposition` | `attachment; filename="stats_export.json"` |
| `X-Export-Count` | Nombre d'objets exportés |
| `X-Export-Generated` | Date/heure de génération (format ISO 8601) |
| `X-Export-Zone` | Code INSEE si export d'une zone spécifique |

## Structure des données

### Informations générales
- `id` : Identifiant unique de l'objet Stats
- `zone` : Code INSEE de la zone
- `name` : Nom de la ville/zone
- `dateCreated` : Date de création
- `dateModified` : Date de dernière modification

### Données démographiques et administratives
- `population` : Population de la zone
- `budgetAnnuel` : Budget annuel de la collectivité
- `siren` : Code SIREN
- `codeEpci` : Code EPCI
- `codesPostaux` : Codes postaux de la zone

### Décomptes
- `placesCount` : Nombre de lieux enregistrés
- `avecHoraires` : Nombre de lieux avec horaires d'ouverture
- `avecAdresse` : Nombre de lieux avec adresse complète
- `avecSite` : Nombre de lieux avec site web
- `avecAccessibilite` : Nombre de lieux avec accessibilité PMR
- `avecNote` : Nombre de lieux avec note
- `completionPercent` : Pourcentage de complétion global
- `placesCountReal` : Nombre réel de lieux (comptage direct)

### Followups (si `include_followups=true`)
- `followups` : Tableau des mesures de suivi (CityFollowUp)
  - `name` : Nom de la mesure
  - `measure` : Valeur de la mesure
  - `date` : Date de la mesure

### Places (si `include_places=true`)
- `places` : Tableau des lieux de la zone
  - `id` : Identifiant du lieu
  - `name` : Nom du lieu
  - `mainTag` : Tag principal OSM
  - `osmId` : ID OSM
  - `osmKind` : Type OSM (node/way)
  - `email` : Email de contact
  - `note` : Note
  - `zipCode` : Code postal
  - `siret` : Numéro SIRET
  - `lat` : Latitude
  - `lon` : Longitude
  - `hasOpeningHours` : A des horaires d'ouverture
  - `hasAddress` : A une adresse complète
  - `hasWebsite` : A un site web
  - `hasWheelchair` : A des informations d'accessibilité
  - `hasNote` : A une note
  - `completionPercentage` : Pourcentage de complétion du lieu

## Cas d'usage

### Export pour analyse
```bash
# Export de toutes les villes avec formatage
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?pretty=true" > analyse_villes.json

# Export d'une ville spécifique
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?zone=75056&pretty=true" > paris.json
```

### Export pour traitement automatisé
```bash
# Export compact pour traitement par script
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export" > stats_compact.json
```

### Export avec données complètes
```bash
# Export avec tous les lieux (attention: peut être volumineux)
curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?include_places=true&pretty=true" > stats_complet.json
```

## Limitations

- L'option `include_places=true` peut générer des fichiers très volumineux pour les grandes villes
- Les requêtes avec `include_places=true` peuvent être plus lentes
- Le formatage JSON (`pretty=true`) augmente la taille de la réponse