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

curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export"

Export avec formatage JSON

curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?pretty=true"

Export d'une zone spécifique

curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?zone=75056"

Export d'une zone avec formatage et sans followups

curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?zone=75056&pretty=true&include_followups=false"

Export complet avec lieux

curl "https://osm-commerces.cipherbliss.com/api/v1/stats/export?pretty=true&include_places=true"

Réponse

Succès (200 OK)

[
  {
    "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)

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

Erreur - Erreur serveur (500 Internal Server Error)

{
  "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

# 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é

# 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

# 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