openapi: 3.0.0
info:
  title: Infoparcelle API - Données foncières et immobilières
  description: >-
    # Prise en main


    ## Introduction


    L'API Infoparcelle est une **API REST complète et enrichie** donnant accès à
    des données foncières, cadastrales et immobilières pour la France
    métropolitaine et les DOM. Elle agrège, structure et enrichit des données
    publiques provenant de multiples sources officielles (DGFiP, ADEME,
    Géorisques, INPI, INSEE, etc) pour faciliter l'analyse territoriale, les
    études d'urbanisme, l'investissement immobilier et les projets de
    développement.


    Conçue pour les professionnels de l'immobilier, les collectivités
    territoriales, les urbanistes et les développeurs d'applications, l'API
    offre un accès unifié et performant à des millions de données actualisées
    régulièrement.


    ## Formats de réponse


    L'API supporte deux formats de sortie pour les données géographiques,
    sélectionnables via le paramètre `format` :


    - **JSON** (`format=json`, défaut) : Format JSON simple avec les géométries
    sous forme d'objets GeoJSON intégrés dans les propriétés. Idéal pour une
    consommation programmatique standard

    - **GeoJSON** (`format=geojson`) : Format standard GeoJSON
    (FeatureCollection) conforme à la RFC 7946, pour une intégration directe
    dans les SIG (QGIS, ArcGIS, Leaflet, Mapbox)


    **Types de géométries**


    Pour les endpoints géographiques, vous pouvez sélectionner le type de
    géométrie retournée via le paramètre `geometrie` :


    - **`centre`** (défaut) : Point central de l'objet (GeoJSON Point) - Léger
    et rapide, idéal pour l'affichage de marqueurs

    - **`contour`** : Géométrie complète (GeoJSON Polygon ou MultiPolygon) -
    Pour l'affichage précis des limites et le calcul de surfaces

    - **`bbox`** : Boîte englobante rectangulaire (GeoJSON Polygon) - Rectangle
    minimal contenant l'objet


    **Personnalisation des champs**


    La plupart des endpoints supportent le paramètre `champs` permettant de
    sélectionner uniquement les propriétés souhaitées dans la réponse, réduisant
    ainsi la taille des données transférées et améliorant les performances.


    **Exemple :** `champs=code,nom,superficie` ne retournera que ces trois
    champs pour chaque résultat.


    ## Authentification


    Toutes les requêtes nécessitent une authentification par **clé API**.


    **Prérequis**


    1. **Créer un compte** sur
    [https://www.infoparcelle.fr](https://www.infoparcelle.fr)

    2. **Souscrire à un plan API** adapté à vos besoins

    3. **Générer une clé API** depuis votre espace personnel :
    [https://www.infoparcelle.fr/compte/api](https://www.infoparcelle.fr/compte/api)


    **Format de la clé API**


    Les clés API sont des tokens courts avec un **préfixe identifiable** basé
    sur le nom que vous leur donnez lors de la création.


    **Exemple de clé :** `MON_APP_WEB_a8Kf9jM2pL5qR7tY3wX6zB1vC4`


    - **Préfixe** : `MON_APP_WEB` (identifie votre application)

    - **Token** : `a8Kf9jM2pL5qR7tY3wX6zB1vC4` (partie aléatoire sécurisée)


    **Utilisation**


    Incluez votre clé API dans le header `Authorization` de chaque requête :


    ```

    Authorization: Bearer MON_APP_WEB_a8Kf9jM2pL5qR7tY3wX6zB1vC4

    ```


    **Sécurité**


    - **Ne partagez jamais votre clé API** publiquement (GitHub, forums, etc.)

    - **Conservez-la en sécurité** côté serveur (variables d'environnement)

    - **Révoquez immédiatement** toute clé compromise depuis votre espace compte

    - **Les clés n'expirent pas** mais peuvent être supprimées à tout moment


    **Gestion des clés**


    Depuis [votre espace compte](https://www.infoparcelle.fr/compte/api), vous
    pouvez :

    - Créer plusieurs clés API (une par application/environnement)

    - Voir le graphique d'utilisation des clés

    - Supprimer les clés non utilisées


    ## Pagination


    Les endpoints de liste utilisent une **pagination par curseur**
    (cursor-based pagination) pour des performances optimales, même avec de
    grands volumes de données.


    **Paramètres de pagination**


    - **`limite`** : Nombre de résultats par page (défaut: 10, maximum: 50)

    - **`curseur`** : Token opaque de pagination pour accéder à la page suivante
    (fourni par l'API dans le header `X-Pagination-Next-Cursor`)


    **Headers de réponse**


    Chaque réponse paginée inclut les headers suivants pour faciliter la
    navigation :


    - **`X-Pagination-Limit`** : Nombre de résultats par page demandé

    - **`X-Pagination-Cursor`** : Curseur actuel de pagination (vide pour la
    première page)

    - **`X-Pagination-Next-Cursor`** : Curseur pour la page suivante (vide s'il
    n'y a pas de page suivante)

    - **`X-Pagination-Has-More`** : Indique s'il y a plus de résultats
    disponibles (`true` ou `false`)


    **Exemple d'utilisation**


    1. **Première requête** : `GET /api/v1/parcelles?limite=20`

    2. **Récupérer le curseur** depuis le header `X-Pagination-Next-Cursor` de
    la réponse

    3. **Page suivante** : `GET
    /api/v1/parcelles?limite=20&curseur={valeur_du_curseur}`

    4. **Répéter** jusqu'à ce que `X-Pagination-Has-More` soit `false`


    ## Limites et quotas


    Pour garantir une qualité de service optimale à tous les utilisateurs, l'API
    applique des limites de débit :


    **Limite de débit**

    - **1200 requêtes par minute** (soit 20 requêtes par seconde)

    - Le compteur se réinitialise automatiquement chaque minute


    **En cas de dépassement**


    Si vous dépassez la limite, l'API retourne une erreur **429 Too Many
    Requests** avec le header `Retry-After` indiquant le nombre de secondes à
    attendre avant de réessayer.


    **Bonnes pratiques pour optimiser l'utilisation**

    - **Espacez vos requêtes** pour rester sous la limite de 20 requêtes par
    seconde

    - **Gérez les erreurs 429** en implémentant un système de retry avec délai

    - **Utilisez le paramètre `champs`** pour ne récupérer que les données
    nécessaires

    - **Privilégiez le format `centre`** pour les géométries si vous n'avez pas
    besoin des contours complets

    - **Mettez en cache** les données peu volatiles (géométries des territoires,
    références cadastrales)


    ## Codes de réponse HTTP


    L'API utilise les codes de statut HTTP standards pour indiquer le succès ou
    l'échec d'une requête :


    - **200 Succès** : La requête a réussi et les données sont retournées dans
    le corps de la réponse

    - **400 Requête invalide** : La requête est malformée ou contient des
    paramètres invalides (format incorrect, valeurs hors limites)

    - **401 Non authentifié** : Token d'authentification manquant, invalide ou
    expiré. Vérifiez votre header Authorization

    - **403 Accès refusé** : Accès refusé. Causes possibles : quota API dépassé,
    permissions insuffisantes ou IP bloquée

    - **404 Non trouvé** : La ressource demandée n'existe pas (parcelle
    introuvable, territoire inexistant, etc.)

    - **429 Trop de requêtes** : Trop de requêtes envoyées dans un court laps de
    temps. Respectez les limites de débit

    - **432 Abonnement requis** : Aucun abonnement actif détecté. Souscrivez à
    un plan api.

    - **433 Moyen de paiement invalide** : Aucun moyen de paiement valide ou
    actif. Vérifiez vos informations de paiement

    - **434 Quota dépassé** : Quota de crédits API épuisé. Activez les
    dépassements ou passez à un plan supérieur

    - **435 Mise à niveau requise** : Fonctionnalité nécessitant un plan
    supérieur.

    - **500 Erreur interne** : Erreur interne du serveur. Si le problème
    persiste, contactez le support

    - **503 Service indisponible** : Service temporairement indisponible
    (maintenance programmée ou charge serveur élevée)


    Toutes les erreurs retournent un corps de réponse JSON avec un message
    explicatif.
  termsOfService: https://infoparcelle.fr/cgu
  contact:
    name: Support technique Infoparcelle
    url: https://infoparcelle.fr/contact
    email: contact@infoparcelle.fr
  version: '1.0'
servers:
  - url: http://app.devinfoparcelle.fr
    description: API Production Infoparcelle
paths:
  /api/v1/geocoder/search:
    get:
      tags:
        - Géocodage
      summary: Rechercher des adresses par texte libre
      description: >-
        Permet de rechercher des adresses françaises par texte libre avec
        recherche par similarité. Retourne les informations d'adresse incluant
        les coordonnées GPS, identifiants BAN et parcelles cadastrales
        associées. Les résultats peuvent être retournés au format JSON ou
        GeoJSON.
      operationId: geocoderSearch
      parameters:
        - name: recherche
          in: query
          description: >-
            Terme de recherche (adresse complète ou partielle). La recherche
            utilise un algorithme de similarité pour trouver les meilleures
            correspondances.
          required: true
          schema:
            type: string
            example: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=identifiant_ban,adresse_complete,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - identifiant_ban
                - adresse_complete
                - numero
                - nom_voie
                - municipalite
                - parcelles
                - centre
                - similarite
            default:
              - identifiant_ban
              - adresse_complete
              - numero
              - nom_voie
              - municipalite
              - parcelles
              - centre
        - name: champ_tri
          in: query
          description: >-
            Champ utilisé pour trier les résultats. Par défaut, le tri se fait
            par similarité (pertinence de la recherche).
          required: false
          schema:
            type: string
            default: similarite
            enum:
              - similarite
              - adresse_complete
              - numero
              - municipalite
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: desc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    identifiant_ban:
                      description: Identifiant unique BAN (Base Adresse Nationale)
                      type: string
                      example: '75108_3190_00007'
                    adresse_complete:
                      description: Adresse complète formatée
                      type: string
                      example: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                    numero:
                      description: Numéro de voie
                      type: string
                      example: '10'
                    nom_voie:
                      description: Nom de la voie
                      type: string
                      example: rue de la République
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          description: Code INSEE de la commune
                          type: string
                          example: '75101'
                        nom:
                          description: Nom de la commune
                          type: string
                          example: Paris
                        codes_postaux:
                          description: Liste de tous les codes postaux de la commune
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                            - '75002'
                            - '75003'
                      type: object
                    parcelles:
                      description: Liste des parcelles associées à l'adresse
                      type: array
                      items:
                        properties:
                          code:
                            description: Code cadastral complet
                            type: string
                            example: 750010001AB0001
                          section:
                            description: Code de la section
                            type: string
                            example: AB
                          numero:
                            description: Numéro de parcelle
                            type: string
                            example: '0001'
                          superficie:
                            description: Superficie de la parcelle en m²
                            type: number
                            example: 450.5
                        type: object
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    similarite:
                      description: >-
                        Score de similarité entre 0 et 1 indiquant la pertinence
                        du résultat par rapport à la recherche
                      type: number
                      format: float
                      example: 0.95
                  type: object
                example:
                  - identifiant_ban: '75108_3190_00007'
                    adresse_complete: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                    numero: '10'
                    nom_voie: rue de la République
                    municipalite:
                      code: '75101'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 450.5
                      - code: 750010001AB0002
                        section: AB
                        numero: '0002'
                        superficie: 380
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    similarite: 0.95
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: Géométrie de l'adresse (Point avec coordonnées GPS)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            identifiant_ban:
                              description: Identifiant unique BAN (Base Adresse Nationale)
                              type: string
                              example: '75108_3190_00007'
                            adresse_complete:
                              description: Adresse complète formatée
                              type: string
                              example: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                            numero:
                              description: Numéro de voie
                              type: string
                              example: '10'
                            nom_voie:
                              description: Nom de la voie
                              type: string
                              example: rue de la République
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  description: Code INSEE de la commune
                                  type: string
                                  example: '75101'
                                nom:
                                  description: Nom de la commune
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: >-
                                    Liste de tous les codes postaux de la
                                    commune
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                                    - '75002'
                                    - '75003'
                              type: object
                            parcelles:
                              description: Liste des parcelles associées à l'adresse
                              type: array
                              items:
                                properties:
                                  code:
                                    description: Code cadastral complet
                                    type: string
                                    example: 750010001AB0001
                                  section:
                                    description: Code de la section
                                    type: string
                                    example: AB
                                  numero:
                                    description: Numéro de parcelle
                                    type: string
                                    example: '0001'
                                  superficie:
                                    description: Superficie de la parcelle en m²
                                    type: number
                                    example: 450.5
                                type: object
                            similarite:
                              description: >-
                                Score de similarité entre 0 et 1 indiquant la
                                pertinence du résultat par rapport à la
                                recherche
                              type: number
                              format: float
                              example: 0.95
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        identifiant_ban: '75108_3190_00007'
                        adresse_complete: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                        numero: '10'
                        nom_voie: rue de la République
                        municipalite:
                          code: '75101'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75003'
                        parcelles:
                          - code: 750010001AB0001
                            section: AB
                            numero: '0001'
                            superficie: 450.5
                          - code: 750010001AB0002
                            section: AB
                            numero: '0002'
                            superficie: 380
                        similarite: 0.95
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune adresse trouvée
      security:
        - bearer:
            - '*'
  /api/v1/geocoder/ban/{identifiant_ban}:
    get:
      tags:
        - Géocodage
      summary: Rechercher une adresse par son identifiant BAN
      description: >-
        Permet de récupérer les informations complètes d'une adresse à partir de
        son identifiant unique BAN (Base Adresse Nationale). Retourne les
        coordonnées GPS, informations de voirie et parcelles cadastrales
        associées.
      operationId: geocoderByBan
      parameters:
        - name: identifiant_ban
          in: path
          description: 'Identifiant BAN de l''adresse (format: CODE_INSEE_VOIE_NUMERO)'
          required: true
          schema:
            type: string
            example: '75108_3190_00007'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=identifiant_ban,adresse_complete,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - identifiant_ban
                - adresse_complete
                - numero
                - nom_voie
                - municipalite
                - parcelles
                - centre
            default:
              - identifiant_ban
              - adresse_complete
              - numero
              - nom_voie
              - municipalite
              - parcelles
              - centre
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un objet JSON simple,
            'geojson' pour un Feature GeoJSON
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
      responses:
        '200':
          description: Succès - Retourne les informations de l'adresse
          content:
            application/json:
              schema:
                title: JSON Object
                description: Format JSON simple (format=json)
                properties:
                  identifiant_ban:
                    description: Identifiant unique BAN
                    type: string
                    example: '75108_3190_00007'
                  adresse_complete:
                    description: Adresse complète formatée
                    type: string
                    example: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                  numero:
                    description: Numéro de voie
                    type: string
                    example: '10'
                  nom_voie:
                    description: Nom de la voie
                    type: string
                    example: rue de la République
                  municipalite:
                    description: Informations sur la commune
                    properties:
                      code:
                        description: Code INSEE de la commune
                        type: string
                        example: '75101'
                      nom:
                        description: Nom de la commune
                        type: string
                        example: Paris
                      codes_postaux:
                        description: Liste de tous les codes postaux de la commune
                        type: array
                        items:
                          type: string
                        example:
                          - '75001'
                          - '75002'
                          - '75003'
                    type: object
                  parcelles:
                    description: Liste des parcelles associées à l'adresse
                    type: array
                    items:
                      properties:
                        code:
                          type: string
                        section:
                          type: string
                        numero:
                          type: string
                        superficie:
                          type: number
                      type: object
                  centre:
                    description: Coordonnées du centre géographique (GeoJSON Point)
                    properties:
                      type:
                        type: string
                        example: Point
                      coordinates:
                        type: array
                        items:
                          type: number
                        example:
                          - 2.3522
                          - 48.8566
                    type: object
                type: object
                example:
                  identifiant_ban: '75108_3190_00007'
                  adresse_complete: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                  numero: '10'
                  nom_voie: rue de la République
                  municipalite:
                    code: '75101'
                    nom: Paris
                    codes_postaux:
                      - '75001'
                      - '75002'
                      - '75003'
                  parcelles:
                    - code: 750010001AB0001
                      section: AB
                      numero: '0001'
                      superficie: 450.5
                    - code: 750010001AB0002
                      section: AB
                      numero: '0002'
                      superficie: 380
                  centre:
                    type: Point
                    coordinates:
                      - 2.3522
                      - 48.8566
            application/geo+json:
              schema:
                title: GeoJSON Feature
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: Feature
                  geometry:
                    properties:
                      type:
                        type: string
                        example: Point
                      coordinates:
                        type: array
                        items:
                          type: number
                        example:
                          - 2.3522
                          - 48.8566
                    type: object
                  properties:
                    properties:
                      identifiant_ban:
                        type: string
                        example: '75108_3190_00007'
                      adresse_complete:
                        type: string
                        example: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                      numero:
                        type: string
                        example: '10'
                      nom_voie:
                        type: string
                        example: rue de la République
                      municipalite:
                        description: Informations sur la commune
                        properties:
                          code:
                            description: Code INSEE de la commune
                            type: string
                            example: '75101'
                          nom:
                            description: Nom de la commune
                            type: string
                            example: Paris
                          codes_postaux:
                            description: Liste de tous les codes postaux de la commune
                            type: array
                            items:
                              type: string
                            example:
                              - '75001'
                              - '75002'
                              - '75003'
                        type: object
                      parcelles:
                        type: array
                        items:
                          properties:
                            code:
                              type: string
                            section:
                              type: string
                            numero:
                              type: string
                            superficie:
                              type: number
                          type: object
                    type: object
                type: object
                example:
                  type: Feature
                  geometry:
                    type: Point
                    coordinates:
                      - 2.3522
                      - 48.8566
                  properties:
                    identifiant_ban: '75108_3190_00007'
                    adresse_complete: 7 Rue de l'Elysée 75008 Paris 8e Arrondissement
                    numero: '10'
                    nom_voie: rue de la République
                    municipalite:
                      code: '75101'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 450.5
                      - code: 750010001AB0002
                        section: AB
                        numero: '0002'
                        superficie: 380
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune adresse trouvée
      security:
        - bearer:
            - '*'
  /api/v1/geocoder/coordinates:
    get:
      tags:
        - Géocodage
      summary: Rechercher une parcelle par coordonnées géographiques
      description: >-
        Permet de rechercher la parcelle cadastrale qui contient un point
        géographique donné (géocodage inverse). Retourne les informations de la
        parcelle incluant les données cadastrales, superficie, commune et
        géométrie.
      operationId: geocoderByCoordinates
      parameters:
        - name: lat
          in: query
          description: >-
            Latitude de la coordonnée à géocoder (WGS84, requis pour le
            géocodage inversé)
          required: true
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: 48.8566
        - name: lon
          in: query
          description: >-
            Longitude de la coordonnée à géocoder (WGS84, requis pour le
            géocodage inversé)
          required: true
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: 2.3522
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=identifiant_cadastre,superficie,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - identifiant_cadastre
                - section
                - numero
                - prefixe
                - superficie
                - perimetre
                - arpente
                - municipalite
                - centre
                - contour
                - bbox
            default:
              - identifiant_cadastre
              - section
              - numero
              - prefixe
              - superficie
              - municipalite
              - centre
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un objet JSON simple,
            'geojson' pour un Feature GeoJSON
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Retourne les informations de la parcelle
          content:
            application/json:
              schema:
                title: JSON Object
                description: Format JSON simple (format=json)
                properties:
                  identifiant_cadastre:
                    description: Identifiant cadastral unique
                    type: string
                    example: 750010001AB0001
                  section:
                    description: Section cadastrale
                    type: string
                    example: AB
                  numero:
                    description: Numéro de parcelle
                    type: string
                    example: '0001'
                  prefixe:
                    description: Préfixe de section
                    type: string
                    example: '000'
                  superficie:
                    description: Superficie en m²
                    type: number
                    example: 1250.5
                  perimetre:
                    description: Périmètre en m
                    type: number
                    example: 145.8
                  arpente:
                    description: Parcelle arpentée
                    type: boolean
                    example: true
                  municipalite:
                    description: Informations sur la commune
                    properties:
                      code:
                        description: Code INSEE de la commune
                        type: string
                        example: '75101'
                      nom:
                        description: Nom de la commune
                        type: string
                        example: Paris
                      codes_postaux:
                        description: Liste des codes postaux
                        type: array
                        items:
                          type: string
                        example:
                          - '75001'
                    type: object
                  centre:
                    description: Géométrie GeoJSON du centre de la parcelle (Point)
                    properties:
                      type:
                        type: string
                        example: Point
                      coordinates:
                        description: Coordonnées du point [lon, lat]
                        type: array
                        items:
                          type: number
                        example:
                          - 2.3522
                          - 48.8566
                    type: object
                  contour:
                    description: >-
                      Géométrie GeoJSON du contour de la parcelle (Polygon ou
                      MultiPolygon)
                    properties:
                      type:
                        type: string
                        example: Polygon
                      coordinates:
                        description: Coordonnées du polygone
                        type: array
                        items:
                          type: number
                    type: object
                  bbox:
                    description: >-
                      Géométrie GeoJSON de la boîte englobante de la parcelle
                      (Polygon rectangulaire)
                    properties:
                      type:
                        type: string
                        example: Polygon
                      coordinates:
                        description: Coordonnées du polygone rectangulaire
                        type: array
                        items:
                          type: number
                    type: object
                type: object
                example:
                  identifiant_cadastre: 750010001AB0001
                  section: AB
                  numero: '0001'
                  prefixe: '000'
                  superficie: 1250.5
                  perimetre: 145.8
                  arpente: true
                  municipalite:
                    code: '75101'
                    nom: Paris
                    codes_postaux:
                      - '75001'
                  centre:
                    type: Point
                    coordinates:
                      - 2.3522
                      - 48.8566
                  contour:
                    type: Polygon
                    coordinates:
                      - - - 2.32
                          - 48.85
                        - - 2.37
                          - 48.85
                        - - 2.37
                          - 48.87
                        - - 2.32
                          - 48.87
                        - - 2.32
                          - 48.85
                  bbox:
                    type: Polygon
                    coordinates:
                      - - - 2.32
                          - 48.85
                        - - 2.37
                          - 48.85
                        - - 2.37
                          - 48.87
                        - - 2.32
                          - 48.87
                        - - 2.32
                          - 48.85
            application/geo+json:
              schema:
                title: GeoJSON Feature
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: Feature
                  geometry:
                    description: >-
                      Géométrie de la parcelle contrôlée par le paramètre
                      'geometrie' : Point si geometrie=centre (défaut),
                      Polygon/MultiPolygon si geometrie=contour, Polygon
                      rectangulaire si geometrie=bbox. Les autres géométries
                      sont disponibles dans properties si demandées via champs.
                    properties:
                      type:
                        type: string
                        example: Polygon
                      coordinates:
                        description: Coordonnées de la géométrie
                        type: array
                        items:
                          type: number
                    type: object
                  properties:
                    properties:
                      identifiant_cadastre:
                        description: Identifiant cadastral unique de la parcelle
                        type: string
                        example: 750010001AB0001
                      section:
                        description: Section cadastrale
                        type: string
                        example: AB
                      numero:
                        description: Numéro de parcelle
                        type: string
                        example: '0001'
                      prefixe:
                        description: Préfixe de section
                        type: string
                        example: '000'
                      superficie:
                        description: Superficie de la parcelle en m²
                        type: number
                        example: 1250.5
                      perimetre:
                        description: Périmètre de la parcelle en m
                        type: number
                        example: 145.8
                      arpente:
                        description: >-
                          Indique si la parcelle est arpentée (mesurée avec
                          précision)
                        type: boolean
                        example: true
                      municipalite:
                        description: Informations sur la commune
                        properties:
                          code:
                            description: Code INSEE de la commune
                            type: string
                            example: '75101'
                          nom:
                            description: Nom de la commune
                            type: string
                            example: Paris
                          codes_postaux:
                            description: Liste des codes postaux de la commune
                            type: array
                            items:
                              type: string
                            example:
                              - '75001'
                        type: object
                      centre:
                        description: >-
                          Coordonnées GPS du centre de la parcelle (inclus dans
                          properties si demandé via champs)
                        properties:
                          lon:
                            type: number
                            example: 2.3522
                          lat:
                            type: number
                            example: 48.8566
                        type: object
                      contour:
                        description: >-
                          Géométrie GeoJSON du contour complet de la parcelle
                          (inclus dans properties si demandé via champs)
                        properties:
                          type:
                            type: string
                            example: Polygon
                          coordinates:
                            description: Coordonnées du polygone
                            type: array
                            items:
                              type: number
                        type: object
                      bbox:
                        description: >-
                          Boîte englobante de la parcelle [xmin, ymin, xmax,
                          ymax] (inclus dans properties si demandé via champs)
                        type: array
                        items:
                          type: number
                        example:
                          - 2.32
                          - 48.85
                          - 2.37
                          - 48.87
                    type: object
                type: object
                example:
                  type: Feature
                  geometry:
                    type: Point
                    coordinates:
                      - 2.3522
                      - 48.8566
                  properties:
                    identifiant_cadastre: 750010001AB0001
                    section: AB
                    numero: '0001'
                    prefixe: '000'
                    superficie: 1250.5
                    perimetre: 145.8
                    arpente: true
                    municipalite:
                      code: '75101'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune parcelle trouvée
      security:
        - bearer:
            - '*'
  /api/v1/parcelles/recherche:
    get:
      tags:
        - Parcelles
      summary: Recherche de parcelles avec filtres multiples
      description: >-
        Recherche permettant de filtrer les parcelles cadastrales selon de
        nombreux critères. 


        ⚠️ **IMPORTANT** : Au moins UN filtre géographique est REQUIS parmi :
        `code_departement`, `code_municipalite`, `code_postal`, `code_iris`, ou
        la paire de coordonnées GPS (`lat` ET `lon` ensemble). Cela permet de
        limiter la portée de la recherche et éviter de scanner toute la France.
      operationId: getParcelSearch
      parameters:
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher la parcelle
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher la parcelle
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
        - name: code_departement
          in: query
          description: Code INSEE du département (2 caractères).
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: >-
            Code INSEE de la commune (5 caractères). Accepte plusieurs valeurs
            séparées par des virgules (ex: '75056,69123,13055').
          required: false
          schema:
            type: string
            example: 75056,69123,13055
        - name: code_postal
          in: query
          description: >-
            Code postal (5 caractères). Accepte plusieurs valeurs séparées par
            des virgules (ex: '75001,75002,75003').
          required: false
          schema:
            type: string
            example: ''
        - name: code_iris
          in: query
          description: >-
            Code IRIS (zone géographique infracommunale - Quartier). Accepte
            plusieurs valeurs séparées par des virgules (ex:
            '751010105,751010204,751010301').
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules (ex: 'AB,AC,AD').
          required: false
          schema:
            type: string
            example: ''
        - name: parcelle_multiple
          in: query
          description: >-
            Mode de recherche multi-parcelle (parcelles regroupées). Accepte
            plusieurs valeurs séparées par des virgules (ex: '1,2,3').


            **Liste complète des modes possibles :**


            - `0` - Toutes : Recherche toutes les parcelles (simples et
            multiples)

            - `1` - Parcelles simples : Uniquement les parcelles non regroupées
            (par défaut)

            - `2` - 2 parcelles : Uniquement les groupements de 2 parcelles

            - `3` - 3 parcelles : Uniquement les groupements de 3 parcelles

            - `4` - 4 parcelles et plus : Groupements de 4 parcelles ou plus
          required: false
          schema:
            type: string
            example: ''
        - name: superficie_min
          in: query
          description: Superficie minimale de la parcelle en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: superficie_max
          in: query
          description: Superficie maximale de la parcelle en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: jardin_min
          in: query
          description: Surface minimale du jardin en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: jardin_max
          in: query
          description: Surface maximale du jardin en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: emprise_sol_min
          in: query
          description: Emprise au sol minimale en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: emprise_sol_max
          in: query
          description: Emprise au sol maximale en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: surface_habitable_min
          in: query
          description: Surface habitable minimale en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: surface_habitable_max
          in: query
          description: Surface habitable maximale en m².
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: altitude_min
          in: query
          description: Altitude minimale en mètres.
          required: false
          schema:
            type: number
            format: float
        - name: altitude_max
          in: query
          description: Altitude maximale en mètres.
          required: false
          schema:
            type: number
            format: float
        - name: arpente
          in: query
          description: >-
            Lorsque le terrain a été mesuré par un Géomètre-Expert, la parcelle
            est dite 'arpentée' (true/false).
          required: false
          schema:
            type: boolean
        - name: bati_type
          in: query
          description: >-
            Type de bâti calculé. Accepte plusieurs valeurs séparées par des
            virgules (ex: '1,7,13').


            **Liste complète des types possibles :**


            **Global :**

            - `0` - Bâtiment : Maison/Appartement/Autres


            **Maisons :**

            - `1` - Maison

            - `2` - Maison 1 pièce/studio

            - `3` - Maison 2 pièces

            - `4` - Maison 3 pièces

            - `5` - Maison 4 pièces

            - `6` - Maison 5 pièces et plus


            **Appartements :**

            - `7` - Appartement

            - `8` - Appartement 1 pièce/studio

            - `9` - Appartement 2 pièces

            - `10` - Appartement 3 pièces

            - `11` - Appartement 4 pièces

            - `12` - Appartement 5 pièces et plus


            **Bâtiments et locaux :**

            - `13` - Immeuble : Bâtiment/Immeuble

            - `14` - Activité : Local d'activités

            - `15` - Dépendance


            **Terrains :**

            - `16` - Terrain à bâtir

            - `17` - Terrain
          required: false
          schema:
            type: string
            example: ''
        - name: piscine
          in: query
          description: Construction de type piscine référencée au cadastre (true/false).
          required: false
          schema:
            type: boolean
        - name: piscine_surface_min
          in: query
          description: Surface minimale de la piscine en m².
          required: false
          schema:
            type: integer
            minimum: 0
        - name: piscine_surface_max
          in: query
          description: Surface maximale de la piscine en m².
          required: false
          schema:
            type: integer
            minimum: 0
        - name: hauteur_min
          in: query
          description: Hauteur minimale des bâtiments en mètres.
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: hauteur_max
          in: query
          description: Hauteur maximale des bâtiments en mètres.
          required: false
          schema:
            type: number
            format: float
            minimum: 0
        - name: annee_construction_min
          in: query
          description: Année de construction minimale.
          required: false
          schema:
            type: integer
            maximum: 2100
            minimum: 1000
        - name: annee_construction_max
          in: query
          description: Année de construction maximale.
          required: false
          schema:
            type: integer
            maximum: 2100
            minimum: 1000
        - name: isole
          in: query
          description: >-
            Bâtiment isolé : true = parcelle ne comportant aucun bâtiment dans
            les parcelles voisines, false = parcelle avec bâtiments voisins
          required: false
          schema:
            type: boolean
        - name: etages
          in: query
          description: >-
            Nombre d'étages du bâtiment principal. Accepte plusieurs valeurs
            séparées par des virgules (ex: '1', '1,2', '1,2,3').


            **Exemples de valeurs :**


            - `0` - Rez-de-chaussée uniquement : Bâtiment de plain-pied

            - `1` - 1 étage : Rez-de-chaussée + 1 étage (R+1)

            - `2` - 2 étages : Rez-de-chaussée + 2 étages (R+2)

            - `3` - 3 étages : Rez-de-chaussée + 3 étages (R+3)

            - `4` - 4 étages et plus : Rez-de-chaussée + 4 étages ou plus (R+4+)
          required: false
          schema:
            type: integer
            minimum: 0
        - name: batiment_dur
          in: query
          description: >-
            Nombre de bâtiments durs (constructions en matériaux solides) sur la
            parcelle. Accepte plusieurs valeurs séparées par des virgules (ex:
            '1,2,3').


            **Liste complète des valeurs possibles :**


            - `0` - Aucun : Pas de bâtiment dur sur la parcelle

            - `1` - Un seul : Exactement 1 bâtiment dur (maison, immeuble, local
            commercial, etc.)

            - `2` - Deux : Exactement 2 bâtiments durs

            - `3` - Trois : Exactement 3 bâtiments durs

            - `4` - Quatre et plus : 4 bâtiments durs ou plus
          required: false
          schema:
            type: integer
            maximum: 4
            minimum: 0
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
        - name: batiment_leger
          in: query
          description: >-
            Nombre de bâtiments légers (constructions légères ou temporaires)
            sur la parcelle. Accepte plusieurs valeurs séparées par des virgules
            (ex: '1,2,3').


            **Liste complète des valeurs possibles :**


            - `0` - Aucun : Pas de bâtiment léger sur la parcelle

            - `1` - Un seul : Exactement 1 bâtiment léger (abri de jardin,
            préfabriqué, cabanon, serre, etc.)

            - `2` - Deux : Exactement 2 bâtiments légers

            - `3` - Trois : Exactement 3 bâtiments légers

            - `4` - Quatre et plus : 4 bâtiments légers ou plus
          required: false
          schema:
            type: integer
            maximum: 4
            minimum: 0
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
        - name: mitoyen
          in: query
          description: >-
            Nombre de faces mitoyennes (murs partagés avec des bâtiments
            voisins). Accepte plusieurs valeurs séparées par des virgules (ex:
            '0,1,2').


            **Liste complète des valeurs possibles :**


            - `0` - Aucune face mitoyenne : Bâtiment totalement isolé, sans mur
            partagé

            - `1` - Une face mitoyenne : Bâtiment partagé sur un côté

            - `2` - Deux faces mitoyennes : Bâtiment partagé sur deux côtés

            - `3` - Trois faces mitoyennes ou plus : Bâtiment partagé sur trois
            côtés ou plus
          required: false
          schema:
            type: string
            example: ''
        - name: forme_piscine
          in: query
          description: >-
            Forme de la piscine cadastrée. Accepte plusieurs valeurs séparées
            par des virgules (ex: '0,1,3').


            **Liste complète des formes possibles :**


            - `0` - Rectangle : Piscine de forme rectangulaire classique

            - `1` - Rectangle avec escalier : Piscine rectangulaire avec
            escalier intégré

            - `2` - L : Piscine en forme de L

            - `3` - Ronde/Arrondi : Piscine de forme ronde ou avec angles
            arrondis

            - `4` - Autres : Autres formes (haricot, ovale, libre, etc.)
          required: false
          schema:
            type: string
        - name: dpe_energie
          in: query
          description: >-
            Étiquette de performance énergétique (consommation). Accepte
            plusieurs valeurs séparées par des virgules (ex: 'A,B,C').


            **Liste complète des étiquettes possibles :**


            - `A` - Très performant : Consommation ≤ 70 kWh/m²/an (logements
            neufs ou très bien isolés)

            - `B` - Performant : Consommation entre 71 et 110 kWh/m²/an
            (logements bien isolés)

            - `C` - Assez performant : Consommation entre 111 et 180 kWh/m²/an
            (logements correctement isolés)

            - `D` - Moyennement performant : Consommation entre 181 et 250
            kWh/m²/an (isolation moyenne)

            - `E` - Peu performant : Consommation entre 251 et 330 kWh/m²/an
            (isolation faible)

            - `F` - Très peu performant : Consommation entre 331 et 420
            kWh/m²/an (isolation très faible)

            - `G` - Extrêmement peu performant : Consommation > 420 kWh/m²/an
            (passoire thermique)
          required: false
          schema:
            type: string
            enum:
              - A
              - B
              - C
              - D
              - E
              - F
              - G
        - name: dpe_ges
          in: query
          description: >-
            Étiquette d'émission de gaz à effet de serre (GES). Accepte
            plusieurs valeurs séparées par des virgules (ex: 'D,E,F').


            **Liste complète des étiquettes possibles :**


            - `A` - Très faible émission : Émission ≤ 6 kg CO2/m²/an (logements
            très écologiques)

            - `B` - Faible émission : Émission entre 7 et 11 kg CO2/m²/an
            (logements écologiques)

            - `C` - Émission modérée : Émission entre 12 et 30 kg CO2/m²/an
            (logements assez écologiques)

            - `D` - Émission moyenne : Émission entre 31 et 50 kg CO2/m²/an
            (impact environnemental moyen)

            - `E` - Émission importante : Émission entre 51 et 70 kg CO2/m²/an
            (impact environnemental élevé)

            - `F` - Émission très importante : Émission entre 71 et 100 kg
            CO2/m²/an (impact environnemental très élevé)

            - `G` - Émission extrêmement importante : Émission > 100 kg
            CO2/m²/an (logement très polluant)
          required: false
          schema:
            type: string
            enum:
              - A
              - B
              - C
              - D
              - E
              - F
              - G
        - name: dpe_date_reception_min
          in: query
          description: >-
            Date minimale de réception du diagnostic de performance énergétique
            (format: YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: dpe_date_reception_max
          in: query
          description: >-
            Date maximale de réception du diagnostic de performance énergétique
            (format: YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: elec_tertiaire_min
          in: query
          description: Consommation électrique tertiaire minimale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: elec_tertiaire_max
          in: query
          description: Consommation électrique tertiaire maximale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: elec_residentielle_min
          in: query
          description: Consommation électrique résidentielle minimale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: elec_residentielle_max
          in: query
          description: Consommation électrique résidentielle maximale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: gaz_tertiaire_min
          in: query
          description: Consommation gaz tertiaire minimale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: gaz_tertiaire_max
          in: query
          description: Consommation gaz tertiaire maximale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: gaz_residentielle_min
          in: query
          description: Consommation gaz résidentielle minimale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: gaz_residentielle_max
          in: query
          description: Consommation gaz résidentielle maximale (en kWh/an).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: dvf_existe
          in: query
          description: >-
            Inclus dans les ventes immobilières depuis le 1er Janvier 2014
            (true/false).
          required: false
          schema:
            type: boolean
        - name: dvf_prix_min
          in: query
          description: >-
            Prix de vente minimal des biens immobiliers depuis le 1er Janvier
            2014 (en euros).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: dvf_prix_max
          in: query
          description: >-
            Prix de vente maximal des biens immobiliers depuis le 1er Janvier
            2014 (en euros).
          required: false
          schema:
            type: integer
            minimum: 0
        - name: dvf_date_min
          in: query
          description: >-
            Date minimale de vente des biens immobiliers depuis le 1er Janvier
            2014 (format: YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: dvf_date_max
          in: query
          description: >-
            Date maximale de vente des biens immobiliers depuis le 1er Janvier
            2014 (format: YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: dvf_code_type_bien
          in: query
          description: >-
            Code du type de bien vendu depuis le 1er Janvier 2014. Accepte
            plusieurs valeurs séparées par des virgules.


            **Liste complète des codes possibles :**


            **Activité et indéterminé :**

            - `14` - ACTIVITE

            - `101` - BATI - INDETERMINE : Vefa sans descriptif

            - `102` - BATI - INDETERMINE : Vente avec volume(s)


            **Maisons :**

            - `110` - MAISON - INDETERMINEE

            - `111` - UNE MAISON

            - `112` - DES MAISONS


            **Appartements :**

            - `120` - APPARTEMENT INDETERMINE

            - `121` - UN APPARTEMENT

            - `122` - DEUX APPARTEMENTS


            **Dépendances :**

            - `131` - UNE DEPENDANCE

            - `132` - DES DEPENDANCES


            **Bâti mixte :**

            - `151` - BATI MIXTE - LOGEMENTS

            - `152` - BATI MIXTE - LOGEMENT/ACTIVITE


            **Terrains non bâtis :**

            - `20` - TERRAIN NON BATIS INDETERMINE

            - `21` - TERRAIN DE TYPE TAB (Terrain à bâtir)


            **Terrains artificialisés :**

            - `221` - TERRAIN D'AGREMENT

            - `222` - TERRAIN D'EXTRACTION

            - `223` - TERRAIN DE TYPE RESEAU

            - `229` - TERRAIN ARTIFICIALISE MIXTE


            **Terrains naturels :**

            - `232` - TERRAIN FORESTIER

            - `233` - TERRAIN LANDES ET EAUX

            - `239` - TERRAIN NATUREL MIXTE


            **Terrains agricoles :**

            - `2311` - TERRAIN VITICOLE

            - `2312` - TERRAIN VERGER

            - `2313` - TERRAIN DE TYPE TERRE ET PRE

            - `2319` - TERRAIN AGRICOLE MIXTE
          required: false
          schema:
            type: string
            example: ''
        - name: permis_type
          in: query
          description: >-
            Types de permis depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs séparées par des virgules.


            **Liste complète des types possibles :**


            - `0` - Non communiqué : Type de permis non précisé

            - `1` - Permis de construire de logement (PC) : Autorisation pour
            construire des logements neufs

            - `2` - Déclaration préalable de travaux de logement (DP) : Pour
            travaux de logement de faible ampleur

            - `3` - Permis de construire de local (PC) : Autorisation pour
            construire des locaux commerciaux, industriels ou professionnels

            - `4` - Déclaration préalable de travaux de local (DP) : Pour
            travaux de local de faible ampleur

            - `5` - Permis d'aménager (PA) : Pour aménager un terrain
            (lotissement, camping, etc.)

            - `6` - Permis de démolir : Autorisation de démolir une construction
            existante
          required: false
          schema:
            type: string
        - name: permis_etat
          in: query
          description: >-
            États du permis depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs séparées par des virgules.


            **Liste complète des états possibles :**


            - `0` - Non communiqué : État du permis non précisé

            - `2` - Autorisé : Permis délivré et autorisé

            - `4` - Annulé : Permis annulé ou refusé

            - `5` - Commencé : Travaux commencés (DOC - Déclaration d'Ouverture
            de Chantier)

            - `6` - Terminé : Travaux terminés (DAACT - Déclaration Attestant
            l'Achèvement et la Conformité des Travaux)
          required: false
          schema:
            type: string
        - name: permis_nature
          in: query
          description: >-
            Natures du permis depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs séparées par des virgules.


            **Liste complète des natures possibles :**


            - `0` - Destruction de construction : Démolition totale ou partielle
            d'une construction existante

            - `1` - Nouvelle construction : Construction d'un bâtiment neuf sur
            terrain nu

            - `2` - Transformation sans extension ni diminution : Modification
            intérieure sans changement de surface

            - `3` - Transformation avec extension : Modification avec
            augmentation de la surface

            - `4` - Transformation avec diminution : Modification avec réduction
            de la surface

            - `5` - Extension sans transformation : Agrandissement sans
            modification de l'existant

            - `6` - Diminution sans transformation : Réduction de surface sans
            modification de l'existant

            - `7` - Non communiqué : Nature du permis non précisée
          required: false
          schema:
            type: string
        - name: permis_cat_dem
          in: query
          description: >-
            Catégories du demandeur du permis depuis le 1er Janvier 2013.
            Accepte plusieurs valeurs séparées par des virgules.


            **Liste complète des catégories possibles :**


            **Particuliers :**

            - `10` - Particuliers SAI (Sans Autre Indication) : Particuliers non
            catégorisés

            - `11` - Particuliers purs : Personnes physiques individuelles

            - `12` - SCI de particuliers : Sociétés Civiles Immobilières de
            particuliers


            **Bailleurs sociaux :**

            - `20` - Bailleurs sociaux SAI : Bailleurs sociaux non catégorisés

            - `21` - Organismes HLM : Office public de l'habitat, entreprises
            sociales pour l'habitat

            - `22` - EPL (Entreprises Publiques Locales) : SEM, SPL
            d'aménagement ou de construction

            - `23` - Autres organismes : Collecteurs d'Action Logement,
            associations, fondations


            **Promoteurs :**

            - `30` - Promoteurs : Promoteurs immobiliers non catégorisés

            - `31` - Promoteurs reconnus : Promoteurs immobiliers professionnels
            reconnus

            - `32` - SCI ou supports de programmes : Supports juridiques de
            programmes immobiliers

            - `33` - Autres professionnels : Constructeurs de maisons
            individuelles, lotisseurs


            **Administrations publiques :**

            - `40` - Administrations publiques : Administrations non
            catégorisées

            - `41` - État et ODAC : État et Organismes Divers d'Administration
            Centrale

            - `42` - Départements et régions : Collectivités territoriales de
            niveau supérieur

            - `43` - Communes et EPIC : Communes et Établissements Publics à
            caractère Industriel et Commercial


            **Autres :**

            - `50` - Autres sociétés : Sociétés commerciales, industrielles ou
            de services

            - `80` - Sans objet : Catégorie non applicable

            - `90` - Non déterminé : Catégorie du demandeur non précisée
          required: false
          schema:
            type: string
        - name: plu_zone
          in: query
          description: >-
            Zone PLU principale. Accepte plusieurs valeurs séparées par des
            virgules. La recherche est insensible à la casse (u = U).


            **Liste complète des zones possibles :**


            - `A` - Zone Agricole : Secteurs à protéger en raison du potentiel
            agronomique, biologique ou économique des terres agricoles

            - `Ah` - Zone Agricole avec habitat diffus : Sous-zone A permettant
            l'habitat diffus en milieu agricole

            - `AUc` - Zone À Urbaniser - Centre : Secteur destiné à
            l'urbanisation future, généralement situé en centre-ville

            - `AUs` - Zone À Urbaniser - Secteur : Secteur destiné à
            l'urbanisation future, généralement en périphérie

            - `N` - Zone Naturelle : Secteurs à protéger en raison de la qualité
            des sites, des milieux naturels ou des paysages

            - `Nd` - Zone Naturelle avec densification : Sous-zone N permettant
            une densification limitée

            - `Nh` - Zone Naturelle avec habitat diffus : Sous-zone N permettant
            l'habitat diffus en milieu naturel

            - `U` - Zone Urbaine : Secteurs déjà urbanisés où les équipements
            publics existants permettent d'admettre immédiatement des
            constructions
          required: false
          schema:
            type: string
            example: ''
        - name: plu_zone_type
          in: query
          description: >-
            Type de zone PLU spécifique (ex: UBa, AUs, U1e, N, etc.). Accepte
            plusieurs valeurs séparées par des virgules (ex: 'UBa,AUs,U1e'). La
            recherche est insensible à la casse (uba = UBa).
          required: false
          schema:
            type: string
            example: ''
        - name: risque_argile
          in: query
          description: >-
            Aléa de retrait-gonflement des sols argileux. Accepte plusieurs
            valeurs séparées par des virgules (ex: '1,2,3').
                 
            **Valeurs possibles :**


            - `1` - Faible : Aléa faible de retrait-gonflement des argiles

            - `2` - Moyen : Aléa moyen de retrait-gonflement des argiles

            - `3` - Fort : Aléa fort de retrait-gonflement des argiles
          required: false
          schema:
            type: string
            example: ''
        - name: risque_radon
          in: query
          description: >-
            Potentiel radon dans les roches et sous-sols. Accepte plusieurs
            valeurs séparées par des virgules (ex: '1,2,3').


            **Valeurs possibles :**


            - `1` - Faible : Potentiel radon faible dans les roches et sous-sols

            - `2` - Moyen : Potentiel radon moyen dans les roches et sous-sols

            - `3` - Fort : Potentiel radon fort dans les roches et sous-sols
          required: false
          schema:
            type: string
            example: ''
        - name: estimation_min
          in: query
          description: Prix d'estimation minimale en euros.
          required: false
          schema:
            type: integer
            minimum: 0
        - name: estimation_max
          in: query
          description: Prix d'estimation maximale en euros.
          required: false
          schema:
            type: integer
            minimum: 0
        - name: estimation_ppm_min
          in: query
          description: Prix par m² d'estimation minimal en euros.
          required: false
          schema:
            type: integer
            minimum: 0
        - name: estimation_ppm_max
          in: query
          description: Prix par m² d'estimation maximal en euros.
          required: false
          schema:
            type: integer
            minimum: 0
        - name: construction
          in: query
          description: >-
            Parcelle contenant des constructions (true = Avec construction,
            false = Sans construction).
          required: false
          schema:
            type: boolean
        - name: copropriete
          in: query
          description: >-
            Numéro d'immatriculation de la copropriété (identifiant unique de la
            copropriété). Accepte plusieurs valeurs séparées par des virgules
            (ex: '123456,234567,345678').
          required: false
          schema:
            type: string
            example: ''
        - name: personne_morale
          in: query
          description: >-
            Code SIREN de la personne morale propriétaire (9 chiffres). Accepte
            plusieurs valeurs séparées par des virgules (ex:
            '123456789,234567890,345678901').
          required: false
          schema:
            type: string
            example: ''
        - name: personne_morale_presente
          in: query
          description: Présence de personne morale sur la parcelle (true/false).
          required: false
          schema:
            type: boolean
        - name: opportunite
          in: query
          description: Parcelle contenant des opportunités (true/false).
          required: false
          schema:
            type: boolean
        - name: opportunite_date_min
          in: query
          description: 'Date minimale de l''opportunité (format: YYYY-MM-DD).'
          required: false
          schema:
            type: string
            format: date
        - name: opportunite_date_max
          in: query
          description: 'Date maximale de l''opportunité (format: YYYY-MM-DD).'
          required: false
          schema:
            type: string
            format: date
        - name: opportunite_type
          in: query
          description: >-
            Type d'opportunités détectées sur la parcelle. Accepte plusieurs
            valeurs séparées par des virgules (ex: 'dpe,terrain').


            **Liste complète des types possibles :**


            - `dpe` - Opportunité DPE : Parcelles avec diagnostic de performance
            énergétique  de moins de 3 mois

            - `terrain` - Opportunité terrain : Parcelles avec potentiel foncier
            (terrain constructible, division possible, etc.)
          required: false
          schema:
            type: string
            example: ''
        - name: numero_rue
          in: query
          description: >-
            Numéro de rue de l'adresse postale. Accepte plusieurs valeurs
            séparées par des virgules (ex: '2,3').
          required: false
          schema:
            type: string
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Exemple
            : champs=cadastre_id,superficie,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - cadastre_id
                - superficie
                - perimetre
                - arpente
                - section
                - municipalite
                - centre
                - contour
                - bbox
            default:
              - cadastre_id
              - municipalite
              - superficie
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: superficie
            enum:
              - cadastre_id
              - superficie
              - code_municipalite
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique : 'centre'
            pour le point central, 'contour' pour le polygone complet. Ce
            paramètre est principalement utilisé en format GeoJSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    cadastre_id:
                      description: Liste des identifiants cadastraux (multi-parcelle)
                      type: array
                      items:
                        type: string
                      example:
                        - 75056000AB0123
                        - 75056000AB0124
                    superficie:
                      description: Superficie de la parcelle en m²
                      type: number
                      example: 523.45
                    perimetre:
                      description: Périmètre de la parcelle en m
                      type: number
                      example: 102.34
                    arpente:
                      description: Parcelle arpentée
                      type: boolean
                      example: true
                    section:
                      description: Informations sur la section cadastrale
                      properties:
                        code:
                          description: Code de la section
                          type: string
                          example: AB
                      type: object
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          description: Code INSEE
                          type: string
                          example: '75056'
                        nom:
                          description: Nom de la commune
                          type: string
                          example: Paris
                        codes_postaux:
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                      type: object
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    contour:
                      description: >-
                        Contour géographique de la parcelle (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante de la parcelle (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - cadastre_id:
                      - 75056000AB0123
                      - 75056000AB0124
                    superficie: 523.45
                    perimetre: 102.34
                    arpente: true
                    section:
                      code: AB
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        id:
                          type: integer
                          example: 123456
                        geometry:
                          description: >-
                            Géométrie de la parcelle (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            cadastre_id:
                              description: >-
                                Liste des identifiants cadastraux
                                (multi-parcelle)
                              type: array
                              items:
                                type: string
                              example:
                                - 75056000AB0123
                                - 75056000AB0124
                            superficie:
                              description: Superficie de la parcelle en m²
                              type: number
                              example: 523.45
                            perimetre:
                              description: Périmètre de la parcelle en m
                              type: number
                              example: 102.34
                            arpente:
                              description: Parcelle arpentée
                              type: boolean
                              example: true
                            section:
                              description: Informations sur la section cadastrale
                              properties:
                                code:
                                  description: Code de la section
                                  type: string
                                  example: AB
                              type: object
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  description: Code INSEE
                                  type: string
                                  example: '75056'
                                nom:
                                  description: Nom de la commune
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: Liste des codes postaux
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                              type: object
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.3522
                                    - 48.8566
                              type: object
                            bbox:
                              description: >-
                                Boîte englobante de la parcelle (GeoJSON
                                Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      id: 123456
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 2.32
                              - 48.85
                            - - 2.37
                              - 48.85
                            - - 2.37
                              - 48.87
                            - - 2.32
                              - 48.87
                            - - 2.32
                              - 48.85
                      properties:
                        cadastre_id:
                          - 75056000AB0123
                          - 75056000AB0124
                        superficie: 523.45
                        perimetre: 102.34
                        arpente: true
                        section:
                          code: AB
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                        centre:
                          type: Point
                          coordinates:
                            - 2.3522
                            - 48.8566
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.32
                                - 48.85
                              - - 2.37
                                - 48.85
                              - - 2.37
                                - 48.87
                              - - 2.32
                                - 48.87
                              - - 2.32
                                - 48.85
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune parcelle trouvée
      security:
        - bearer:
            - '*'
    post:
      tags:
        - Parcelles
      summary: Recherche avancée de parcelles avec filtres configurables
      description: >-
        Recherche avancée permettant de filtrer les parcelles cadastrales selon
        de nombreux critères. Supporte deux modes de filtrage : strict (WHERE
        exact) et indicatif (scoring par pertinence).


        ⚠️ **IMPORTANT** : Au moins UN filtre géographique est REQUIS parmi :
        `code_departement`, `code_municipalite`, `code_postal`, `code_iris`, ou
        la paire de coordonnées GPS (`lat` ET `lon` ensemble). Cela permet de
        limiter la portée de la recherche et éviter de scanner toute la France.


        **Mode STRICT (indicatif: false)** : Applique un filtre WHERE SQL
        classique. Seules les parcelles correspondant exactement au critère sont
        retournées. Idéal pour des contraintes obligatoires.


        **Mode INDICATIF (indicatif: true)** : Utilise un système de scoring
        pour classer les résultats par pertinence. Les parcelles sont triées
        selon leur score de correspondance au critère. Idéal pour des
        préférences plutôt que des contraintes strictes.
      operationId: postParcelSearch
      requestBody:
        description: >-
          Requête de recherche avec filtres optionnels, pagination et options
          d'affichage.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CTB_POSTSCHEMA_RechercheParcelleRequest'
      responses:
        '200':
          description: >-
            Recherche effectuée avec succès - Format varie selon le paramètre
            'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur de pagination actuel
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: Curseur pour la page suivante (vide si dernière page)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il reste d'autres pages
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    cadastre_id:
                      description: Liste des identifiants cadastraux (multi-parcelle)
                      type: array
                      items:
                        type: string
                      example:
                        - 75056000AB0123
                        - 75056000AB0124
                    superficie:
                      description: Superficie de la parcelle en m²
                      type: number
                      example: 523.45
                    perimetre:
                      description: Périmètre de la parcelle en m
                      type: number
                      example: 102.34
                    arpente:
                      description: Parcelle arpentée
                      type: boolean
                      example: true
                    section:
                      description: Informations sur la section cadastrale
                      properties:
                        code:
                          description: Code de la section
                          type: string
                          example: AB
                      type: object
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          description: Code INSEE
                          type: string
                          example: '75056'
                        nom:
                          description: Nom de la commune
                          type: string
                          example: Paris
                        codes_postaux:
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                      type: object
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    contour:
                      description: >-
                        Contour géographique de la parcelle (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante de la parcelle (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                    score_pertinence:
                      description: >-
                        Score de pertinence calculé lors de l'utilisation de
                        filtres en mode indicatif (0-100)
                      type: number
                      example: 85.5
                  type: object
                example:
                  - cadastre_id:
                      - 75056000AB0123
                      - 75056000AB0124
                    superficie: 523.45
                    perimetre: 102.34
                    arpente: true
                    section:
                      code: AB
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
                    score_pertinence: 85.5
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        id:
                          type: integer
                          example: 123456
                        geometry:
                          description: >-
                            Géométrie de la parcelle (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            cadastre_id:
                              description: >-
                                Liste des identifiants cadastraux
                                (multi-parcelle)
                              type: array
                              items:
                                type: string
                              example:
                                - 75056000AB0123
                                - 75056000AB0124
                            superficie:
                              description: Superficie de la parcelle en m²
                              type: number
                              example: 523.45
                            perimetre:
                              description: Périmètre de la parcelle en m
                              type: number
                              example: 102.34
                            arpente:
                              description: Parcelle arpentée
                              type: boolean
                              example: true
                            section:
                              description: Informations sur la section cadastrale
                              properties:
                                code:
                                  description: Code de la section
                                  type: string
                                  example: AB
                              type: object
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  description: Code INSEE
                                  type: string
                                  example: '75056'
                                nom:
                                  description: Nom de la commune
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: Liste des codes postaux
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                              type: object
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.3522
                                    - 48.8566
                              type: object
                            bbox:
                              description: >-
                                Boîte englobante de la parcelle (GeoJSON
                                Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                            score_pertinence:
                              description: >-
                                Score de pertinence calculé lors de
                                l'utilisation de filtres en mode indicatif
                                (0-100)
                              type: number
                              example: 85.5
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      id: 123456
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 2.32
                              - 48.85
                            - - 2.37
                              - 48.85
                            - - 2.37
                              - 48.87
                            - - 2.32
                              - 48.87
                            - - 2.32
                              - 48.85
                      properties:
                        cadastre_id:
                          - 75056000AB0123
                          - 75056000AB0124
                        superficie: 523.45
                        perimetre: 102.34
                        arpente: true
                        section:
                          code: AB
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                        centre:
                          type: Point
                          coordinates:
                            - 2.3522
                            - 48.8566
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.32
                                - 48.85
                              - - 2.37
                                - 48.85
                              - - 2.37
                                - 48.87
                              - - 2.32
                                - 48.87
                              - - 2.32
                                - 48.85
                        score_pertinence: 85.5
        '400':
          description: |-
            Requête invalide - Exemples d'erreurs :
                *
                * • Aucun filtre géographique fourni (au moins un requis parmi : code_municipalite, code_postal, code_departement, code_region, code_iris, ou la paire lat+lon)
                * • Paramètres manquants ou incorrects
                * • Format de données invalide
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune parcelle trouvée
      security:
        - bearer: []
  /api/v1/parcelles/{cadastre_id}:
    get:
      tags:
        - Parcelles
      summary: Obtenir une fiche parcelle complète par son identifiant cadastral
      operationId: getParcelByCode
      parameters:
        - name: cadastre_id
          in: path
          description: Identifiant cadastral de la parcelle
          required: true
          schema:
            type: string
            example: 75108000BO0025
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne tous les champs disponibles.
            Permet de personnaliser les données retournées pour optimiser la
            taille de la réponse. Exemple :
            champs=cadastre_id,superficie,centre,dpes,dvfs
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - cadastre_id
                - section
                - numero
                - prefixe
                - superficie
                - perimetre
                - arpente
                - municipalite
                - quartier
                - lieu_dit
                - adresses
                - detail
                - batiments
                - zones_plu
                - dpes
                - dvfs
                - coproprietaires
                - proprietaires
                - occupants
                - permis_construire
                - risques
                - monuments_historiques
                - consommations
                - statistiques
                - centre
                - contour
                - bbox
            default:
              - cadastre_id
              - superficie
              - dpes
              - dvfs
              - zones_plu
              - centre
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un objet JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à inclure dans la réponse : 'centre' pour le point
            central, 'contour' pour le polygone complet, 'bbox' pour la boîte
            englobante. Ce paramètre est principalement utilisé en format
            GeoJSON mais peut aussi filtrer les champs géométriques en format
            JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: >-
            Succès - Retourne une fiche complète avec toutes les données de la
            parcelle. Format varie selon le paramètre 'format' (json ou geojson)
          content:
            application/json:
              schema:
                title: Format JSON
                description: Format JSON simple (format=json)
                properties:
                  cadastre_id:
                    description: >-
                      Identifiant cadastral unique de la parcelle (14
                      caractères) - Format : Code INSEE (5) + Préfixe (3) +
                      Section (2) + Numéro (4). Clé primaire pour identifier de
                      manière unique une parcelle cadastrale en France.
                    type: string
                    example: 75108000BO0025
                  section:
                    description: >-
                      Code de la section cadastrale (2 caractères) - Subdivision
                      du territoire communal pour l'organisation du cadastre.
                      Composée de lettres (A-Z) ou de chiffres. Exemple : 'BO',
                      'AB', '01'.
                    type: string
                    example: BO
                  numero:
                    description: >-
                      Numéro de la parcelle au sein de la section (4 caractères
                      avec zéros de tête). Identifiant séquentiel de la parcelle
                      dans sa section cadastrale.
                    type: string
                    example: '0025'
                  prefixe:
                    description: >-
                      Préfixe de la parcelle (3 caractères) - Code spécifique
                      utilisé pour certaines communes (000 par défaut, autre
                      valeur pour les communes avec arrondissements ou sections
                      particulières).
                    type: string
                    example: '000'
                  superficie:
                    description: >-
                      Superficie officielle de la parcelle en m² (mètres
                      carrés).
                    type: number
                    format: float
                    example: 523.45
                  perimetre:
                    description: >-
                      Périmètre de la parcelle en m (mètres) - Longueur totale
                      du contour de la parcelle, calculée à partir de la
                      géométrie cadastrale vectorielle.
                    type: number
                    format: float
                    example: 102.34
                  arpente:
                    description: >-
                      Lorsque le terrain a été mesuré par un Géomètre-Expert, la
                      parcelle est dite 'arpentée' (true) - Les limites ont été
                      mesurées et validées par un géomètre professionnel,
                      garantissant une précision maximale. false = parcelle non
                      arpentée ou limites non validées.
                    type: boolean
                    example: true
                  municipalite:
                    description: Informations sur la commune où est située la parcelle
                    properties:
                      code:
                        description: >-
                          Code INSEE officiel de la commune (5 caractères) -
                          Identifiant unique et permanent de la commune,
                          attribué par l'INSEE.
                        type: string
                        example: '75108'
                      nom:
                        description: >-
                          Nom officiel de la commune (nomenclature INSEE) - Peut
                          inclure l'arrondissement pour Paris, Lyon et
                          Marseille.
                        type: string
                        example: Paris 8e Arrondissement
                      codes_postaux:
                        description: >-
                          Liste complète de tous les codes postaux desservant la
                          commune - Une même commune peut avoir plusieurs codes
                          postaux.
                        type: array
                        items:
                          type: string
                        example:
                          - '75008'
                    type: object
                  quartier:
                    description: >-
                      Informations sur le quartier IRIS (Îlots Regroupés pour
                      l'Information Statistique) - Découpage territorial de
                      l'INSEE à des fins statistiques. Un IRIS correspond à
                      environ 2000 habitants.
                    properties:
                      code:
                        description: >-
                          Code IRIS du quartier (9 caractères) - Format : Code
                          INSEE commune (5) + Code IRIS (4)
                        type: string
                        example: '751080804'
                      nom:
                        description: Nom du quartier IRIS - Dénomination locale du quartier
                        type: string
                        example: Champs-Elysées
                      type:
                        description: Type de quartier IRIS selon la classification INSEE
                        type: string
                        enum:
                          - Habitat
                          - Activité
                          - Divers
                          - Hors IRIS
                          - Autre
                        example: Habitat
                    type: object
                    nullable: true
                  lieu_dit:
                    description: >-
                      Nom du lieu-dit cadastral si applicable - Appellation
                      locale traditionnelle d'un espace géographique (ex: 'Les
                      Vignes', 'Le Moulin'). Peut être null si la parcelle n'est
                      pas située dans un lieu-dit nommé.
                    type: string
                    nullable: true
                  adresses:
                    description: >-
                      Liste des adresses postales associées à la parcelle.
                      Triées automatiquement par score de fiabilité décroissant
                      (la première adresse est la plus fiable). Utile pour
                      géolocaliser, afficher l'adresse principale ou croiser
                      avec d'autres données.
                    type: array
                    items:
                      properties:
                        label:
                          description: >-
                            Libellé complet et normalisé de l'adresse postale -
                            Format standardisé : [Numéro] [Indice] [Type de
                            voie] [Nom de voie] [Code postal] [Commune]
                          type: string
                          example: 8 Avenue des Champs-Élysées 75008 Paris
                        fiability:
                          description: >-
                            Score de fiabilité de l'adresse (0 à 95) - Calculé
                            en fonction de la source (BAN = haute fiabilité), de
                            la précision de géolocalisation et de la concordance
                            avec les données cadastrales. Scores > 80 = très
                            fiable, 60-80 = fiable, < 60 = peu fiable.
                          type: integer
                          example: 90
                      type: object
                  detail:
                    description: >-
                      Détails complets de la parcelle (surfaces, piscines,
                      bâtiments, etc.)
                    properties:
                      piscines:
                        properties:
                          nombre:
                            description: Nombre de piscines
                            type: integer
                            example: 0
                          surface_totale:
                            description: Surface totale des piscines en m²
                            type: number
                            example: null
                          forme:
                            description: >-
                              Forme de la piscine cadastrée.


                              **Liste complète des formes possibles :**


                              - `0` - Rectangle : Piscine de forme rectangulaire
                              classique

                              - `1` - Rectangle avec escalier : Piscine
                              rectangulaire avec escalier intégré

                              - `2` - L : Piscine en forme de L

                              - `3` - Ronde/Arrondi : Piscine de forme ronde ou
                              avec angles arrondis

                              - `4` - Autres : Autres formes (haricot, ovale,
                              libre, etc.)
                            type: string
                            example: null
                        type: object
                      batiments_durs:
                        properties:
                          nombre:
                            description: Nombre de bâtiments durs
                            type: integer
                            example: 2
                          surface_totale:
                            description: Surface totale des bâtiments durs en m²
                            type: number
                            example: 450.5
                        type: object
                      batiments_legers:
                        properties:
                          nombre:
                            description: Nombre de bâtiments légers
                            type: integer
                            example: 0
                          surface_totale:
                            description: Surface totale des bâtiments légers en m²
                            type: number
                            example: null
                        type: object
                      surfaces:
                        properties:
                          jardin:
                            description: Surface de jardin en m²
                            type: number
                            example: 100
                          emprise_sol:
                            description: Emprise au sol en m²
                            type: number
                            example: 200.5
                          habitable:
                            description: Surface habitable en m²
                            type: number
                            example: 350
                          habitable_calculee:
                            description: Surface habitable calculée - approximative
                            type: boolean
                            example: false
                        type: object
                      hauteurs:
                        properties:
                          min:
                            description: Hauteur minimale en m
                            type: number
                            example: 8.5
                          max:
                            description: Hauteur maximale en m
                            type: number
                            example: 12
                        type: object
                      altitudes:
                        properties:
                          min:
                            description: Altitude minimale en m
                            type: number
                            example: 45.2
                          max:
                            description: Altitude maximale en m
                            type: number
                            example: 46.8
                        type: object
                      construction:
                        properties:
                          annee_min:
                            description: Année de construction la plus ancienne
                            type: integer
                            example: 1890
                          annee_max:
                            description: Année de construction la plus récente
                            type: integer
                            example: 1920
                          nombre_etages:
                            description: Nombre d'étages
                            type: integer
                            example: 3
                        type: object
                      caracteristiques:
                        properties:
                          bati_type:
                            description: |-
                              Type de bâti calculé.

                              **Liste complète des types possibles :**

                              **Global :**
                              - `0` - Bâtiment : Maison/Appartement/Autres

                              **Maisons :**
                              - `1` - Maison
                              - `2` - Maison 1 pièce/studio
                              - `3` - Maison 2 pièces
                              - `4` - Maison 3 pièces
                              - `5` - Maison 4 pièces
                              - `6` - Maison 5 pièces et plus

                              **Appartements :**
                              - `7` - Appartement
                              - `8` - Appartement 1 pièce/studio
                              - `9` - Appartement 2 pièces
                              - `10` - Appartement 3 pièces
                              - `11` - Appartement 4 pièces
                              - `12` - Appartement 5 pièces et plus

                              **Bâtiments et locaux :**
                              - `13` - Immeuble : Bâtiment/Immeuble
                              - `14` - Activité : Local d'activités
                              - `15` - Dépendance

                              **Terrains :**
                              - `16` - Terrain à bâtir
                              - `17` - Terrain
                            type: integer
                            example: Maison
                          est_isolee:
                            description: >-
                              Bâtiment isolé : true = parcelle ne comportant
                              aucun bâtiment dans les parcelles voisines, false
                              = parcelle avec bâtiments voisins
                            type: boolean
                            example: false
                          nb_parcelles_adjacentes:
                            description: Nombre de parcelles adjacentes
                            type: integer
                            example: 4
                          nb_batiments_mitoyens:
                            description: Nombre de bâtiments mitoyens
                            type: integer
                            example: 2
                        type: object
                      risques:
                        properties:
                          argile:
                            description: Niveau de risque argile
                            type: string
                            enum:
                              - Faible
                              - Moyen
                              - Fort
                            example: Moyen
                          radon:
                            description: Niveau de risque radon
                            type: string
                            enum:
                              - Faible
                              - Moyen
                              - Fort
                            example: Faible
                        type: object
                      estimations:
                        properties:
                          prix_vente:
                            description: Prix de vente estimé en €
                            type: number
                            example: 850000
                          prix_vente_ppm:
                            description: Prix de vente au m² en €
                            type: number
                            example: 2428.57
                          prix_location:
                            description: Loyer mensuel estimé en €
                            type: number
                            example: 2500
                          prix_location_ppm:
                            description: Loyer au m² en €
                            type: number
                            example: 7.14
                        type: object
                    type: object
                  batiments:
                    description: Liste des bâtiments sur la parcelle
                    type: array
                    items:
                      properties:
                        type:
                          description: >-
                            Type de bâtiment/construction. Liste complète des
                            types possibles :


                            **Bâtiments :**

                            - `1` - Bâtiment dur : Construction en matériaux
                            durs (béton, pierre, brique)

                            - `2` - Bâtiment léger : Construction en matériaux
                            légers (bois, métal)


                            **Piscines :**

                            - `65` - Piscine : Bassin de natation


                            **Cimetières :**

                            - `51` - Cimetière : Cimetière général

                            - `52` - Cimetière israélite : Cimetière de
                            confession juive

                            - `53` - Cimetière musulman : Cimetière de
                            confession musulmane


                            **Infrastructures :**

                            - `32` - Limite de parcelle : Délimitation de
                            parcelle

                            - `33` - Parapet/pont : Ouvrage d'art (parapet,
                            pont)

                            - `37` - Tunnel : Ouvrage souterrain


                            **Points d'eau :**

                            - `34` - Point d'eau / étang / lac : Plan d'eau
                            naturel ou artificiel


                            **Autres :**

                            - `99` - Autre construction : Toute autre
                            construction non catégorisée
                          type: integer
                          example: 1
                        type_label:
                          description: Libellé du type de bâtiment
                          type: string
                          example: Bâtiment dur
                        superficie:
                          description: Superficie du bâtiment en m²
                          type: number
                          example: 150.5
                        perimetre:
                          description: Périmètre du bâtiment en m
                          type: number
                          example: 52.3
                      type: object
                  zones_plu:
                    description: Zones PLU (Plan Local d'Urbanisme)
                    type: array
                    items:
                      properties:
                        titre:
                          description: Titre de la zone
                          type: string
                          example: Zone Urbaine Mixte
                        description:
                          description: Description longue de la zone
                          type: string
                          example: 'Zone UB : Zone urbaine dense'
                        zone:
                          description: >-
                            Zone PLU principale.


                            **Liste complète des zones possibles :**


                            - `A` - Zone Agricole : Secteurs à protéger en
                            raison du potentiel agronomique, biologique ou
                            économique des terres agricoles

                            - `Ah` - Zone Agricole avec habitat diffus :
                            Sous-zone A permettant l'habitat diffus en milieu
                            agricole

                            - `AUc` - Zone À Urbaniser - Centre : Secteur
                            destiné à l'urbanisation future, généralement situé
                            en centre-ville

                            - `AUs` - Zone À Urbaniser - Secteur : Secteur
                            destiné à l'urbanisation future, généralement en
                            périphérie

                            - `N` - Zone Naturelle : Secteurs à protéger en
                            raison de la qualité des sites, des milieux naturels
                            ou des paysages

                            - `Nd` - Zone Naturelle avec densification :
                            Sous-zone N permettant une densification limitée

                            - `Nh` - Zone Naturelle avec habitat diffus :
                            Sous-zone N permettant l'habitat diffus en milieu
                            naturel

                            - `U` - Zone Urbaine : Secteurs déjà urbanisés où
                            les équipements publics existants permettent
                            d'admettre immédiatement des constructions
                          type: string
                          example: U
                        type_zone:
                          description: Type de zone (U, AU, A, N, etc.)
                          type: string
                          example: UB
                        surface:
                          description: Surface en m²
                          type: number
                          example: 523.45
                        perimetre:
                          description: Périmètre en m
                          type: number
                          example: 102.34
                        documents:
                          description: Document PLU parent avec fichiers associés
                          properties:
                            partition:
                              description: Partition du document PLU
                              type: string
                              example: 75108_PLU_20210115
                            fichiers:
                              description: Liste des fichiers PDF/documents liés au PLU
                              type: array
                              items:
                                properties:
                                  titre:
                                    description: Titre du fichier
                                    type: string
                                    example: Règlement Zones UB
                                  nom_fichier:
                                    description: Nom du fichier
                                    type: string
                                    example: 75108_reglement_UB.pdf
                                  url:
                                    description: URL de téléchargement
                                    type: string
                                    format: uri
                                    example: >-
                                      https://example.com/plu/75108_reglement_UB.pdf
                                  categorie:
                                    description: >-
                                      Catégorie du document PLU basée sur le nom
                                      du fichier
                                    type: string
                                    example: Documents Règlementaires
                                  date_creation:
                                    description: Date de création du fichier
                                    type: string
                                    format: date
                                    example: '2021-01-15'
                                type: object
                          type: object
                      type: object
                  dpes:
                    description: Diagnostics de performance énergétique
                    type: array
                    items:
                      properties:
                        numero_dpe:
                          description: Numéro unique du DPE
                          type: string
                          example: '2301E0123456'
                        type_dpe:
                          description: |-
                            Type de DPE.

                            **Liste complète des types possibles :**

                            - `0` - Existant : DPE pour un logement existant
                            - `1` - Neuf : DPE pour une construction neuve
                            - `2` - Tertiaire : DPE pour un bâtiment tertiaire
                          type: integer
                          example: DPE vierge
                        date_etablissement:
                          description: Date d'établissement du DPE (format AAAA-MM-JJ).
                          type: string
                          format: date
                          example: '2023-03-15'
                        date_reception:
                          description: Date de réception du DPE (format AAAA-MM-JJ).
                          type: string
                          format: date
                          example: '2023-03-20'
                        date_visite:
                          description: Date de visite (format AAAA-MM-JJ).
                          type: string
                          format: date
                        date_fin_validite:
                          description: Date de fin de validité (format AAAA-MM-JJ).
                          type: string
                          format: date
                        version:
                          description: Version du DPE
                          type: string
                          example: '2.1'
                        etiquette_dpe:
                          description: >-
                            Étiquette de performance énergétique.


                            **Liste complète des étiquettes possibles :**


                            - `A` - Très performant : Consommation ≤ 70
                            kWh/m²/an (logements neufs ou très bien isolés)

                            - `B` - Performant : Consommation entre 71 et 110
                            kWh/m²/an (logements bien isolés)

                            - `C` - Assez performant : Consommation entre 111 et
                            180 kWh/m²/an (logements correctement isolés)

                            - `D` - Moyennement performant : Consommation entre
                            181 et 250 kWh/m²/an (isolation moyenne)

                            - `E` - Peu performant : Consommation entre 251 et
                            330 kWh/m²/an (isolation faible)

                            - `F` - Très peu performant : Consommation entre 331
                            et 420 kWh/m²/an (isolation très faible)

                            - `G` - Extrêmement peu performant : Consommation >
                            420 kWh/m²/an (passoire thermique)
                          type: string
                          enum:
                            - A
                            - B
                            - C
                            - D
                            - E
                            - F
                            - G
                          example: D
                        etiquette_ges:
                          description: >-
                            Étiquette d'émission de gaz à effet de serre (GES).


                            **Liste complète des étiquettes possibles :**


                            - `A` - Très faible émission : Émission ≤ 6 kg
                            CO2/m²/an (logements très écologiques)

                            - `B` - Faible émission : Émission entre 7 et 11 kg
                            CO2/m²/an (logements écologiques)

                            - `C` - Émission modérée : Émission entre 12 et 30
                            kg CO2/m²/an (logements assez écologiques)

                            - `D` - Émission moyenne : Émission entre 31 et 50
                            kg CO2/m²/an (impact environnemental moyen)

                            - `E` - Émission importante : Émission entre 51 et
                            70 kg CO2/m²/an (impact environnemental élevé)

                            - `F` - Émission très importante : Émission entre 71
                            et 100 kg CO2/m²/an (impact environnemental très
                            élevé)

                            - `G` - Émission extrêmement importante : Émission >
                            100 kg CO2/m²/an (logement très polluant)
                          type: string
                          enum:
                            - A
                            - B
                            - C
                            - D
                            - E
                            - F
                            - G
                          example: C
                        adresse:
                          description: Adresse complète du bien
                          type: string
                          example: 8 Avenue des Champs-Élysées
                        bati_type:
                          description: |-
                            Type de bâti calculé.

                            **Liste complète des types possibles :**

                            **Global :**
                            - `0` - Bâtiment : Maison/Appartement/Autres

                            **Maisons :**
                            - `1` - Maison
                            - `2` - Maison 1 pièce/studio
                            - `3` - Maison 2 pièces
                            - `4` - Maison 3 pièces
                            - `5` - Maison 4 pièces
                            - `6` - Maison 5 pièces et plus

                            **Appartements :**
                            - `7` - Appartement
                            - `8` - Appartement 1 pièce/studio
                            - `9` - Appartement 2 pièces
                            - `10` - Appartement 3 pièces
                            - `11` - Appartement 4 pièces
                            - `12` - Appartement 5 pièces et plus

                            **Bâtiments et locaux :**
                            - `13` - Immeuble : Bâtiment/Immeuble
                            - `14` - Activité : Local d'activités
                            - `15` - Dépendance

                            **Terrains :**
                            - `16` - Terrain à bâtir
                            - `17` - Terrain
                          type: integer
                          example: Maison
                        type_batiment:
                          description: >-
                            Type de bâtiment.


                            **Liste complète des types possibles :**


                            - `appartement` - Appartement : Logement dans un
                            immeuble collectif

                            - `maison` - Maison : Logement individuel

                            - `immeuble` - Immeuble : Bâtiment collectif complet
                          type: string
                          enum:
                            - appartement
                            - maison
                            - immeuble
                          example: immeuble
                        surface_habitable:
                          description: Surface habitable en m².
                          type: number
                          format: float
                          example: 350
                        annee_construction:
                          description: Année de construction du bâtiment.
                          type: integer
                          example: 1900
                        periode_construction:
                          description: Période de construction
                          type: string
                          example: 1881-1914
                        nombre_niveau_logement:
                          description: Nombre de niveaux du logement
                          type: integer
                          example: 2
                        hauteur_sous_plafond:
                          description: Hauteur sous plafond en m
                          type: number
                          format: float
                          example: 2.8
                        conso_energie:
                          description: Consommation énergétique totale en kWh/m²/an.
                          type: number
                          format: float
                          example: 220.5
                        conso_chauffage:
                          description: Consommation chauffage en kWh/m²/an
                          type: number
                          format: float
                          example: 180
                        conso_ecs:
                          description: Consommation eau chaude sanitaire en kWh/m²/an
                          type: number
                          format: float
                          example: 30.5
                        conso_refroidissement:
                          description: Consommation refroidissement en kWh/m²/an
                          type: number
                          format: float
                          example: 5
                        conso_eclairage:
                          description: Consommation éclairage en kWh/m²/an
                          type: number
                          format: float
                          example: 5
                        emission_ges:
                          description: Émission totale de GES en kg CO2/m²/an
                          type: number
                          format: float
                          example: 45.2
                        emission_ges_chauffage:
                          description: Émission GES chauffage en kg CO2/m²/an
                          type: number
                          format: float
                          example: 38
                        emission_ges_ecs:
                          description: Émission GES eau chaude sanitaire en kg CO2/m²/an
                          type: number
                          format: float
                          example: 7.2
                        cout_total:
                          description: Coût total annuel en €
                          type: number
                          format: float
                          example: 3200
                        cout_chauffage:
                          description: Coût annuel chauffage en €
                          type: number
                          format: float
                          example: 2700
                        cout_ecs:
                          description: Coût annuel eau chaude sanitaire en €
                          type: number
                          format: float
                          example: 500
                      type: object
                  dvfs:
                    description: Transactions immobilières (Demandes de Valeurs Foncières)
                    type: array
                    items:
                      properties:
                        id_mutation:
                          description: Identifiant unique de la mutation
                          type: string
                          example: 2022-12345
                        date_mutation:
                          description: Date de signature de l'acte
                          type: string
                          format: date
                          example: '2022-06-15'
                        nature_mutation:
                          description: >-
                            Nature de la mutation.


                            **Liste complète des natures possibles :**


                            - `Adjudication` - Vente aux enchères publiques

                            - `Echange` - Échange de biens immobiliers

                            - `Expropriation` - Acquisition forcée pour cause
                            d'utilité publique

                            - `Vente` - Vente classique

                            - `Vente en l'état futur d'achèvement` - Vente VEFA
                            (logement vendu avant achèvement des travaux)

                            - `Vente terrain à bâtir` - Vente d'un terrain
                            constructible
                          type: string
                          example: Vente
                        valeur_fonciere:
                          description: Prix de la transaction en euros
                          type: number
                          example: 850000
                        vefa:
                          description: Indicateur VEFA (0=Non, 1=Oui)
                          type: integer
                          example: 0
                        code_type_bien:
                          description: |-
                            Code du type de bien.

                            **Activité et indéterminé :**
                            - `14` - ACTIVITE
                            - `101` - BATI - INDETERMINE : Vefa sans descriptif
                            - `102` - BATI - INDETERMINE : Vente avec volume(s)

                            **Maisons :**
                            - `110` - MAISON - INDETERMINEE
                            - `111` - UNE MAISON
                            - `112` - DES MAISONS

                            **Appartements :**
                            - `120` - APPARTEMENT INDETERMINE
                            - `121` - UN APPARTEMENT
                            - `122` - DEUX APPARTEMENTS

                            **Dépendances :**
                            - `131` - UNE DEPENDANCE
                            - `132` - DES DEPENDANCES

                            **Bâti mixte :**
                            - `151` - BATI MIXTE - LOGEMENTS
                            - `152` - BATI MIXTE - LOGEMENT/ACTIVITE

                            **Terrains non bâtis :**
                            - `20` - TERRAIN NON BATIS INDETERMINE
                            - `21` - TERRAIN DE TYPE TAB (Terrain à bâtir)

                            **Terrains artificialisés :**
                            - `221` - TERRAIN D'AGREMENT
                            - `222` - TERRAIN D'EXTRACTION
                            - `223` - TERRAIN DE TYPE RESEAU
                            - `229` - TERRAIN ARTIFICIALISE MIXTE

                            **Terrains naturels :**
                            - `232` - TERRAIN FORESTIER
                            - `233` - TERRAIN LANDES ET EAUX
                            - `239` - TERRAIN NATUREL MIXTE

                            **Terrains agricoles :**
                            - `2311` - TERRAIN VITICOLE
                            - `2312` - TERRAIN VERGER
                            - `2313` - TERRAIN DE TYPE TERRE ET PRE
                            - `2319` - TERRAIN AGRICOLE MIXTE
                          type: integer
                          example: 111
                        libelle_type:
                          description: Libellé du type de bien
                          type: string
                          example: UNE MAISON
                        bati_type:
                          description: |-
                            Type de bâti calculé.

                            **Liste complète des types possibles :**

                            **Global :**
                            - `0` - Bâtiment : Maison/Appartement/Autres

                            **Maisons :**
                            - `1` - Maison
                            - `2` - Maison 1 pièce/studio
                            - `3` - Maison 2 pièces
                            - `4` - Maison 3 pièces
                            - `5` - Maison 4 pièces
                            - `6` - Maison 5 pièces et plus

                            **Appartements :**
                            - `7` - Appartement
                            - `8` - Appartement 1 pièce/studio
                            - `9` - Appartement 2 pièces
                            - `10` - Appartement 3 pièces
                            - `11` - Appartement 4 pièces
                            - `12` - Appartement 5 pièces et plus

                            **Bâtiments et locaux :**
                            - `13` - Immeuble : Bâtiment/Immeuble
                            - `14` - Activité : Local d'activités
                            - `15` - Dépendance

                            **Terrains :**
                            - `16` - Terrain à bâtir
                            - `17` - Terrain
                          type: integer
                          example: 7
                        nb_dispositions:
                          description: Nombre de dispositions
                          type: integer
                          example: 1
                        nb_lots:
                          description: Nombre de lots
                          type: integer
                          example: 1
                        nb_parcelles:
                          description: Nombre de parcelles
                          type: integer
                          example: 1
                        nb_parcelles_mutees:
                          description: Nombre de parcelles mutées
                          type: integer
                          example: 1
                        nb_locaux:
                          description: Nombre de locaux
                          type: integer
                          example: 1
                        nb_maisons:
                          description: Nombre de maisons
                          type: integer
                          example: 1
                        nb_appartements:
                          description: Nombre d'appartements
                          type: integer
                          example: 0
                        nb_dependances:
                          description: Nombre de dépendances
                          type: integer
                          example: 0
                        nb_locaux_activite:
                          description: Nombre de locaux d'activité
                          type: integer
                          example: 0
                        surface_terrain:
                          description: Surface de terrain en m²
                          type: number
                          example: 523.45
                        surface_batie:
                          description: Surface bâtie totale en m²
                          type: number
                          example: 350
                        surface_maisons:
                          description: Surface des maisons en m²
                          type: number
                          example: 350
                        surface_appartements:
                          description: Surface des appartements en m²
                          type: number
                          example: 0
                        surface_activite:
                          description: Surface des locaux d'activité en m²
                          type: number
                          example: 0
                      type: object
                  coproprietaires:
                    description: Copropriétés associées
                    type: array
                    items:
                      properties:
                        immatriculation:
                          description: Numéro d'immatriculation au registre national
                          type: string
                          example: ABC123456789
                        nom:
                          description: Nom d'usage de la copropriété
                          type: string
                          example: Résidence du Parc
                        type_syndic:
                          description: >-
                            Type de syndic gérant la copropriété.


                            **Liste complète des types possibles :**


                            - `1` - Bénévole : Syndic non professionnel
                            (copropriétaire élu)

                            - `2` - Professionnel : Syndic professionnel
                            (société ou agent immobilier)

                            - `3` - Non connu : Type de syndic non renseigné
                          type: string
                          example: Professionnel
                        mandat:
                          description: >-
                            Statut du mandat du syndic.


                            **Liste complète des statuts possibles :**


                            - `1` - Mandat en cours : Le syndic a un mandat
                            actif et valide

                            - `2` - Pas de mandat en cours : Aucun syndic
                            actuellement en fonction

                            - `3` - Mandat expiré avec successeur déclaré :
                            Mandat terminé avec nouveau syndic désigné

                            - `4` - Mandat expiré sans successeur déclaré :
                            Mandat terminé sans désignation de nouveau syndic
                          type: string
                          example: Mandat en cours
                        adresse_complete:
                          description: Adresse complète de la copropriété
                          type: string
                        adresse_comp1:
                          description: Complément d'adresse 1
                          type: string
                        adresse_comp2:
                          description: Complément d'adresse 2
                          type: string
                        adresse_comp3:
                          description: Complément d'adresse 3
                          type: string
                        nb_adresse_comp:
                          description: Nombre de compléments d'adresse
                          type: integer
                        date_reglement:
                          description: Date du règlement de copropriété
                          type: string
                          format: date
                          example: '2020-01-15'
                        residence_service:
                          description: Résidence-services
                          type: boolean
                        syndic_cooperatif:
                          description: Syndicat coopératif
                          type: boolean
                        syndic_principal:
                          description: Syndicat principal
                          type: boolean
                        num_syndic_principal:
                          description: Numéro du syndicat principal si secondaire
                          type: string
                        nb_asl:
                          description: Nombre d'ASL
                          type: integer
                          example: 0
                        nb_aful:
                          description: Nombre d'AFUL
                          type: integer
                          example: 0
                        nb_union:
                          description: Nombre d'unions de syndicats
                          type: integer
                          example: 0
                        nb_lot:
                          description: Nombre total de lots
                          type: integer
                          example: 45
                        nb_lot_hab_bur_com:
                          description: Nombre de lots habitation/bureaux/commerces
                          type: integer
                          example: 40
                        nb_lot_hab:
                          description: Nombre de lots d'habitation
                          type: integer
                          example: 35
                        nb_lot_stationement:
                          description: Nombre de lots de stationnement
                          type: integer
                          example: 45
                        nb_arrete_sante:
                          description: Nombre d'arrêtés de mise en sécurité sanitaire
                          type: integer
                          example: 0
                        nb_arrete_peril:
                          description: Nombre d'arrêtés de péril
                          type: integer
                          example: 0
                        nb_arrete_equipement:
                          description: Nombre d'arrêtés d'équipement
                          type: integer
                          example: 0
                        syndic:
                          description: Informations sur le syndic
                          properties:
                            siren:
                              type: string
                              example: '123456789'
                            denomination:
                              type: string
                              example: SYNDIC EXEMPLE SAS
                          type: object
                      type: object
                  proprietaires:
                    description: Propriétaires (personnes morales)
                    type: array
                    items:
                      properties:
                        siren:
                          description: Numéro SIREN du propriétaire
                          type: string
                          example: '123456789'
                        denomination:
                          description: Dénomination sociale du propriétaire
                          type: string
                          example: SCI EXEMPLE
                        code_droit:
                          description: >-
                            Code de droit sur le bien.


                            **Liste complète des codes possibles :**


                            **Propriété pleine ou démembrée :**

                            - `P` - Propriétaire : Pleine propriété du bien

                            - `U` - Usufruitier : Droit d'usage et de percevoir
                            les revenus du bien

                            - `N` - Nu-propriétaire : Propriétaire sans droit
                            d'usage ni de revenus


                            **Baux et locations :**

                            - `B` - Bailleur : Propriétaire qui loue le bien

                            - `R` - Preneur : Locataire du bien

                            - `V` - Bailleur à réhabilitation : Propriétaire
                            dans le cadre d'un bail à réhabilitation

                            - `W` - Preneur à réhabilitation : Locataire dans le
                            cadre d'un bail à réhabilitation

                            - `A` - Locataire-Attributaire : Locataire avec
                            attribution spécifique

                            - `E` - Emphytéote : Titulaire d'un bail
                            emphytéotique (bail de longue durée 18-99 ans)

                            - `K` - Antichrésiste : Créancier bénéficiant d'un
                            droit d'antichrèse


                            **Gestion et administration :**

                            - `F` - Foncier : Propriétaire foncier

                            - `T` - Tenuyer : Titulaire d'une tenure

                            - `D` - Domanier : Relevant du domaine public

                            - `G` - Gérant/Mandataire : Personne gérant le bien
                            pour le compte d'autrui

                            - `Q` - Gestionnaire : Personne assurant la gestion
                            du bien

                            - `S` - Syndic : Syndic de copropriété

                            - `Z` - Gestion État : Bien géré par l'État


                            **Occupation et usage :**

                            - `H` - Associé : Associé disposant d'un droit sur
                            le bien

                            - `O` - Occupation temporaire : Occupation
                            temporaire du domaine public

                            - `L` - Fonctionnaire logé : Fonctionnaire
                            bénéficiant d'un logement de fonction

                            - `J` - Jeune agriculteur : Jeune agriculteur
                            bénéficiaire

                            - `M` - Occupant Mayotte : Statut spécifique à
                            Mayotte


                            **Cas particuliers :**

                            - `X` - La Poste propriétaire : La Poste en tant que
                            propriétaire

                            - `Y` - La Poste occupant : La Poste en tant
                            qu'occupant

                            - `C` - Fiduciaire : Propriétaire dans le cadre
                            d'une fiducie
                          type: string
                          enum:
                            - P
                            - U
                            - 'N'
                            - B
                            - R
                            - V
                            - W
                            - A
                            - E
                            - K
                            - F
                            - T
                            - D
                            - G
                            - Q
                            - S
                            - H
                            - O
                            - L
                            - J
                            - M
                            - X
                            - 'Y'
                            - C
                            - Z
                          example: P
                        libelle_code_droit:
                          description: Libellé lisible du code de droit
                          type: string
                          example: Propriétaire
                        forme_juridique:
                          description: Forme juridique complète de la société
                          type: string
                          example: Société civile immobilière
                        forme_juridique_abregee:
                          description: Code abrégé de la forme juridique
                          type: string
                          example: '5499'
                        type_bien:
                          description: >-
                            Type de bien.


                            **Liste complète des types possibles :**


                            - `0` - LOCAL : Bien bâti (appartement, maison,
                            local commercial, etc.)

                            - `1` - PARCELLE : Terrain non bâti (parcelle
                            cadastrale sans construction)
                          type: string
                          enum:
                            - LOCAL
                            - PARCELLE
                            - INCONNU
                          example: PARCELLE
                        adresse_complete:
                          description: Adresse complète du bien (champ calculé)
                          type: string
                          example: 10 Rue de la Paix 75002 Paris
                        adresse_numero:
                          description: Numéro de voirie
                          type: string
                        adresse_indice_repetition:
                          description: Indice de répétition (Bis, Ter, etc.)
                          type: string
                        adresse_nature_voie:
                          description: Nature de la voie (rue, avenue, boulevard, etc.)
                          type: string
                        adresse_nom_voie:
                          description: Nom de la voie
                          type: string
                        identification_local:
                          description: >-
                            Identification du local (uniquement pour
                            type_bien=LOCAL)
                          properties:
                            batiment:
                              description: Bâtiment
                              type: string
                            entree:
                              description: Entrée
                              type: string
                            niveau:
                              description: Niveau
                              type: string
                            porte:
                              description: Porte
                              type: string
                          type: object
                        subdivision_fiscale:
                          description: >-
                            Subdivision fiscale (uniquement pour
                            type_bien=PARCELLE)
                          type: string
                        subdivision_nature_culture:
                          description: >-
                            Nature de culture de la subdivision fiscale
                            (uniquement pour type_bien=PARCELLE)
                          type: string
                        subdivision_superficie:
                          description: >-
                            Superficie de la subdivision fiscale en centiares
                            (uniquement pour type_bien=PARCELLE)
                          type: integer
                      type: object
                  occupants:
                    description: Occupants / Établissements (SIRENE)
                    type: array
                    items:
                      properties:
                        siret:
                          description: Numéro SIRET de l'établissement (14 chiffres)
                          type: string
                          example: '12345678900015'
                        siren:
                          description: Numéro SIREN de l'unité légale (9 chiffres)
                          type: string
                          example: '123456789'
                        nic:
                          description: Numéro interne de classement (5 chiffres)
                          type: string
                          example: '00015'
                        denomination_complete:
                          description: >-
                            Dénomination complète de l'établissement - Champ
                            calculé
                          type: string
                          example: ENTREPRISE EXEMPLE SAS
                        denomination_usuelle:
                          description: Dénomination usuelle (nom commercial)
                          type: string
                          nullable: true
                        enseigne_1:
                          description: Première enseigne
                          type: string
                          nullable: true
                        enseigne_2:
                          description: Deuxième enseigne
                          type: string
                          nullable: true
                        enseigne_3:
                          description: Troisième enseigne
                          type: string
                          nullable: true
                        activite_principale:
                          description: Code NAF/APE de l'activité principale
                          type: string
                          example: 7022Z
                        activite_principale_registre_metiers:
                          description: Code activité du registre des métiers
                          type: string
                          nullable: true
                        nomenclature_activite_principale:
                          description: Référentiel de l'APE (NAFRev2, etc.)
                          type: string
                        categorie_activite:
                          description: Catégorie d'activité
                          type: string
                          example: >-
                            Conseil pour les affaires et autres conseils de
                            gestion
                        categorie_parent_activite:
                          description: Catégorie parent d'activité
                          type: string
                        naf_section:
                          description: Section NAF (niveau 1)
                          type: object
                        naf_division:
                          description: Division NAF (niveau 2)
                          type: object
                        naf_groupe:
                          description: Groupe NAF (niveau 3)
                          type: object
                        naf_classe:
                          description: Classe NAF (niveau 4)
                          type: object
                        naf_sous_classe:
                          description: Sous-classe NAF (niveau 5)
                          type: object
                        etat_administratif:
                          description: |-
                            État administratif de l'établissement.

                            **Liste complète des états possibles :**

                            - `0` - Actif : Établissement en activité
                            - `1` - Fermé : Établissement fermé ou radié
                          type: string
                          enum:
                            - Actif
                            - Fermé
                          example: Actif
                        caractere_employeur:
                          description: Indique si l'établissement est employeur
                          type: boolean
                          example: true
                        tranche_effectifs:
                          description: |-
                            Tranche d'effectifs salariés de l'établissement.

                            **Liste complète des tranches possibles :**

                            **Très petites structures :**
                            - `0` - 0 salarié : Établissement sans salarié
                            - `1` - 1 ou 2 salariés
                            - `2` - 3 à 5 salariés
                            - `3` - 6 à 9 salariés

                            **Petites entreprises :**
                            - `11` - 10 à 19 salariés
                            - `12` - 20 à 49 salariés

                            **Moyennes entreprises :**
                            - `21` - 50 à 99 salariés
                            - `22` - 100 à 199 salariés
                            - `31` - 200 à 249 salariés
                            - `32` - 250 à 499 salariés

                            **Grandes entreprises :**
                            - `41` - 500 à 999 salariés
                            - `42` - 1 000 à 1 999 salariés
                            - `51` - 2 000 à 4 999 salariés
                            - `52` - 5 000 à 9 999 salariés
                            - `53` - 10 000 salariés et plus
                          type: integer
                          example: 11
                          nullable: true
                        annee_effectifs:
                          description: Année de référence des effectifs
                          type: string
                          example: '2023'
                          nullable: true
                        date_creation:
                          description: Date de création (AAAA-MM-JJ)
                          type: string
                          format: date
                          example: '2015-06-01'
                        date_debut:
                          description: Date de début de période (AAAA-MM-JJ)
                          type: string
                          format: date
                          example: '2015-06-01'
                        date_dernier_traitement:
                          description: Date de dernière modification (ISO 8601)
                          type: string
                          format: date-time
                          example: '2024-01-15T10:30:00'
                        etablissement_siege:
                          description: Indique si c'est le siège
                          type: boolean
                          example: true
                        statut_diffusion:
                          description: >-
                            Statut de diffusion.


                            **Liste complète des statuts possibles :**


                            - `0` - Diffusion ouverte : Les données de
                            l'établissement sont publiques et diffusables

                            - `1` - Diffusion opposée : L'établissement s'est
                            opposé à la diffusion de ses données
                          type: integer
                          example: 0
                        adresse_complete:
                          description: Adresse complète
                          type: string
                          example: 8 Avenue des Champs-Élysées 75008 Paris
                        adresse_numero:
                          description: Numéro de voirie
                          type: integer
                          nullable: true
                        adresse_indice_repetition:
                          description: Indice de répétition (bis, ter, etc.)
                          type: string
                          nullable: true
                        adresse_nom_voie:
                          description: Nom de la voie
                          type: string
                        adresse_code_postal:
                          description: Code postal
                          type: string
                      type: object
                  permis_construire:
                    description: >-
                      Permis de construire et autorisations d'urbanisme (PC, PA,
                      DP, etc.)
                    type: array
                    items:
                      properties:
                        code:
                          description: Numéro du permis de construire
                          type: string
                          example: PC 075 108 22 12345
                        type_autorisation:
                          description: >-
                            Type d'autorisation.


                            **Liste complète des types possibles :**


                            - `0` - Non communiqué : Type de permis non précisé

                            - `1` - Permis de construire de logement (PC) :
                            Autorisation pour construire des logements neufs

                            - `2` - Déclaration préalable de travaux de logement
                            (DP) : Pour travaux de logement de faible ampleur

                            - `3` - Permis de construire de local (PC) :
                            Autorisation pour construire des locaux commerciaux,
                            industriels ou professionnels

                            - `4` - Déclaration préalable de travaux de local
                            (DP) : Pour travaux de local de faible ampleur

                            - `5` - Permis d'aménager (PA) : Pour aménager un
                            terrain (lotissement, camping, etc.)

                            - `6` - Permis de démolir : Autorisation de démolir
                            une construction existante
                          type: string
                          example: PC
                        etat:
                          description: >-
                            État d'avancement.


                            **Liste complète des états possibles :**


                            - `0` - Non communiqué : État du permis non précisé

                            - `2` - Autorisé : Permis délivré et autorisé

                            - `4` - Annulé : Permis annulé ou refusé

                            - `5` - Commencé : Travaux commencés (DOC -
                            Déclaration d'Ouverture de Chantier)

                            - `6` - Terminé : Travaux terminés (DAACT -
                            Déclaration Attestant l'Achèvement et la Conformité
                            des Travaux)
                          type: string
                          example: Autorisé
                        date_autorisation:
                          description: Date réelle d'autorisation du permis
                          type: string
                          format: date
                          example: '2022-03-15'
                        date_doc:
                          description: >-
                            Date réelle de DOC (Déclaration d'Ouverture de
                            Chantier)
                          type: string
                          format: date
                          example: '2022-04-10'
                        date_daact:
                          description: >-
                            Date réelle de DAACT (Déclaration d'Achèvement et de
                            Conformité des Travaux)
                          type: string
                          format: date
                          example: '2023-02-20'
                        nature_projet:
                          description: >-
                            Nature du projet.


                            **Liste complète des natures possibles :**


                            - `0` - Destruction de construction : Démolition
                            totale ou partielle d'une construction existante

                            - `1` - Nouvelle construction : Construction d'un
                            bâtiment neuf sur terrain nu

                            - `2` - Transformation sans extension ni diminution
                            : Modification intérieure sans changement de surface

                            - `3` - Transformation avec extension : Modification
                            avec augmentation de la surface

                            - `4` - Transformation avec diminution :
                            Modification avec réduction de la surface

                            - `5` - Extension sans transformation :
                            Agrandissement sans modification de l'existant

                            - `6` - Diminution sans transformation : Réduction
                            de surface sans modification de l'existant

                            - `7` - Non communiqué : Nature du permis non
                            précisée
                          type: integer
                          example: 1
                        cat_dem:
                          description: >-
                            Catégorie du demandeur du permis depuis le 1er
                            Janvier 2013. Liste complète des catégories
                            possibles :


                            **Particuliers :**

                            - `10` - Particuliers SAI (Sans Autre Indication) :
                            Particuliers non catégorisés

                            - `11` - Particuliers purs : Personnes physiques
                            individuelles

                            - `12` - SCI de particuliers : Sociétés Civiles
                            Immobilières de particuliers


                            **Bailleurs sociaux :**

                            - `20` - Bailleurs sociaux SAI : Bailleurs sociaux
                            non catégorisés

                            - `21` - Organismes HLM : Office public de
                            l'habitat, entreprises sociales pour l'habitat

                            - `22` - EPL (Entreprises Publiques Locales) : SEM,
                            SPL d'aménagement ou de construction

                            - `23` - Autres organismes : Collecteurs d'Action
                            Logement, associations, fondations


                            **Promoteurs :**

                            - `30` - Promoteurs : Promoteurs immobiliers non
                            catégorisés

                            - `31` - Promoteurs reconnus : Promoteurs
                            immobiliers professionnels reconnus

                            - `32` - SCI ou supports de programmes : Supports
                            juridiques de programmes immobiliers

                            - `33` - Autres professionnels : Constructeurs de
                            maisons individuelles, lotisseurs


                            **Administrations publiques :**

                            - `40` - Administrations publiques : Administrations
                            non catégorisées

                            - `41` - État et ODAC : État et Organismes Divers
                            d'Administration Centrale

                            - `42` - Départements et régions : Collectivités
                            territoriales de niveau supérieur

                            - `43` - Communes et EPIC : Communes et
                            Établissements Publics à caractère Industriel et
                            Commercial


                            **Autres :**

                            - `50` - Autres sociétés : Sociétés commerciales,
                            industrielles ou de services

                            - `80` - Sans objet : Catégorie non applicable

                            - `90` - Non déterminé : Catégorie du demandeur non
                            précisée
                          type: string
                          example: Particulier
                        siren_dem:
                          description: Numéro SIREN du demandeur
                          type: string
                          example: '123456789'
                        denomination_dem:
                          description: Dénomination du demandeur
                          type: string
                          example: SCI EXEMPLE
                        rec_archi:
                          description: Recours à un architecte
                          type: boolean
                        zone_op:
                          description: >-
                            Code zone opératoire.


                            **Liste complète des zones possibles :**


                            - `1` - Lotissement : Terrain divisé en lots
                            destinés à la construction

                            - `2` - ZAC : Zone d'Aménagement Concerté

                            - `3` - AFU : Association Foncière Urbaine

                            - `4` - Hors zones : Projet situé hors de toute zone
                            opératoire
                          type: integer
                          example: 4
                        extension:
                          description: Indicateur d'extension
                          type: boolean
                        surelevation:
                          description: Indicateur de surélévation
                          type: boolean
                        nivsupp:
                          description: Indicateur de niveau(x) supplémentaire(s)
                          type: boolean
                        nb_niv_max:
                          description: Nombre de niveaux du bâtiment le plus élevé
                          type: integer
                          example: 3
                        utilisation:
                          description: >-
                            Utilisation visée.


                            **Liste complète des utilisations possibles :**


                            - `1` - Occupation personnelle : Le demandeur
                            occupera le bien

                            - `2` - Vente : Le bien sera mis en vente

                            - `3` - Location : Le bien sera mis en location

                            - `4` - Vente-Location : Usage mixte vente et
                            location

                            - `5` - Non rempli : Information non communiquée
                          type: integer
                          example: 2
                        res_princip_ou_second:
                          description: >-
                            Type d'habitation.


                            **Liste complète des types possibles :**


                            - `1` - Résidence principale : Logement occupé
                            habituellement par le propriétaire

                            - `2` - Résidence secondaire : Logement occupé
                            occasionnellement (vacances, week-end)

                            - `3` - Non rempli : Information non communiquée
                          type: integer
                          example: 1
                        type_annexe:
                          description: |-
                            Type d'annexe.

                            **Liste complète des types possibles :**

                            - `1` - Piscine
                            - `2` - Garage
                            - `3` - Véranda
                            - `4` - Abri de jardin
                            - `5` - Autre : Annexe d'un autre type
                            - `6` - Plusieurs : Plusieurs types d'annexes
                            - `7` - Aucune : Aucune annexe prévue
                          type: integer
                          example: 7
                        residence:
                          description: >-
                            Type de résidence.


                            **Liste complète des types possibles :**


                            - `1` - Résidence pour personnes âgées : EHPAD,
                            résidence seniors

                            - `2` - Résidence étudiante : Logements dédiés aux
                            étudiants

                            - `3` - Résidence de tourisme : Résidence hôtelière,
                            résidence de vacances

                            - `4` - Résidence hôtelière sociale : Hébergement
                            temporaire pour personnes en difficulté

                            - `5` - Résidence sociale : Logements accompagnés
                            pour personnes en insertion

                            - `6` - Résidence pour personnes handicapées :
                            Logements adaptés aux handicaps

                            - `7` - Autre : Résidence spécialisée d'un autre
                            type

                            - `8` - Mixte : Résidence combinant plusieurs types

                            - `9` - Non rempli : Information non communiquée
                          type: integer
                          example: 9
                        nb_chambres:
                          description: Nombre de chambres
                          type: integer
                        nb_lgt_ind_crees:
                          description: Nombre de logements individuels créés
                          type: integer
                          example: 1
                        nb_lgt_col_crees:
                          description: Nombre de logements collectifs créés
                          type: integer
                          example: 0
                        nb_lgt_demolis:
                          description: Nombre de logements démolis
                          type: integer
                          example: 0
                        nb_lgt_1p:
                          description: Nombre de logements de 1 pièce
                          type: integer
                          example: 0
                        nb_lgt_2p:
                          description: Nombre de logements de 2 pièces
                          type: integer
                          example: 0
                        nb_lgt_3p:
                          description: Nombre de logements de 3 pièces
                          type: integer
                          example: 0
                        nb_lgt_4p:
                          description: Nombre de logements de 4 pièces
                          type: integer
                          example: 1
                        nb_lgt_5p:
                          description: Nombre de logements de 5 pièces
                          type: integer
                          example: 0
                        nb_lgt_6p_plus:
                          description: Nombre de logements de 6 pièces et plus
                          type: integer
                          example: 0
                        nb_lgt_pret_loc_social:
                          description: Nombre de logements locatifs sociaux
                          type: integer
                          example: 0
                        surf_hab_avant:
                          description: Surface habitation avant travaux en m²
                          type: number
                          example: 0
                        surf_hab_creee:
                          description: Surface habitation créée en m²
                          type: number
                          example: 120.5
                        surf_hab_issue_transfo:
                          description: Surface habitation issue de transformation en m²
                          type: number
                          example: 0
                        surf_hab_demolie:
                          description: Surface habitation démolie en m²
                          type: number
                          example: 0
                        surf_hab_transformee:
                          description: Surface habitation transformée en m²
                          type: number
                          example: 0
                        surf_autre_avant:
                          description: Surface autre (non résidentiel) avant travaux en m²
                          type: number
                          example: 0
                        surf_autre_creee:
                          description: Surface autre créée en m²
                          type: number
                          example: 25
                        surf_autre_issue_transfo:
                          description: Surface autre issue de transformation en m²
                          type: number
                          example: 0
                        surf_autre_demolie:
                          description: Surface autre démolie en m²
                          type: number
                          example: 0
                        surf_autre_transformee:
                          description: Surface autre transformée en m²
                          type: number
                          example: 0
                      type: object
                  monuments_historiques:
                    description: >-
                      Liste des monuments historiques à proximité de la
                      parcelle. Recense les monuments classés ou inscrits au
                      titre des monuments historiques situés dans le voisinage.
                    type: array
                    items:
                      properties:
                        ref_merimee:
                          description: >-
                            Référence Mérimée du monument historique
                            (identifiant unique dans la base Mérimée)
                          type: string
                          example: PA00088799
                        nom:
                          description: Nom officiel du monument historique
                          type: string
                          example: Arc de Triomphe
                        distance:
                          description: >-
                            Distance en mètres entre la parcelle et le monument
                            historique (calculée depuis le centre de la
                            parcelle)
                          type: number
                          format: float
                          example: 250.5
                      type: object
                  consommations:
                    description: >-
                      Consommations énergétiques réelles de la parcelle
                      (électricité, gaz). Historique des consommations annuelles
                      avec distinction entre usage résidentiel et professionnel.
                    properties:
                      electricite:
                        description: >-
                          Historique des consommations électriques annuelles.
                          Tableau d'objets triés par année (millésime).
                        type: array
                        items:
                          properties:
                            annee:
                              description: >-
                                Année de référence (millésime) de la
                                consommation
                              type: integer
                              example: 2022
                            conso_residentielle:
                              description: >-
                                Consommation électrique résidentielle (usage
                                domestique) en kWh/an
                              type: number
                              format: float
                              example: 5500
                            conso_professionnelle:
                              description: >-
                                Consommation électrique professionnelle (usage
                                tertiaire/commercial) en kWh/an
                              type: number
                              format: float
                              example: 12000
                            conso_totale:
                              description: >-
                                Consommation électrique totale (somme
                                résidentielle + professionnelle) en kWh/an
                              type: number
                              format: float
                              example: 17500
                          type: object
                      gaz:
                        description: >-
                          Historique des consommations de gaz naturel annuelles.
                          Tableau d'objets triés par année (millésime).
                        type: array
                        items:
                          properties:
                            annee:
                              description: >-
                                Année de référence (millésime) de la
                                consommation
                              type: integer
                              example: 2022
                            conso_residentielle:
                              description: >-
                                Consommation de gaz résidentielle (usage
                                domestique) en kWh/an
                              type: number
                              format: float
                              example: 8500
                            conso_professionnelle:
                              description: >-
                                Consommation de gaz professionnelle (usage
                                tertiaire/commercial) en kWh/an
                              type: number
                              format: float
                              example: 0
                            conso_totale:
                              description: >-
                                Consommation de gaz totale (somme résidentielle
                                + professionnelle) en kWh/an
                              type: number
                              format: float
                              example: 8500
                          type: object
                    type: object
                  statistiques:
                    description: >-
                      Statistiques agrégées sur la parcelle - Compteurs
                      permettant d'obtenir rapidement le volume d'informations
                      disponibles (DPE, DVF, bâtiments, propriétaires,
                      occupants, permis, monuments). Utile pour l'affichage de
                      badges ou de synthèses.
                    properties:
                      nombre_dpes:
                        description: >-
                          Nombre total de Diagnostics de Performance Énergétique
                          (DPE) associés à la parcelle
                        type: integer
                        example: 1
                      nombre_dvfs:
                        description: >-
                          Nombre total de transactions immobilières (DVF -
                          Demandes de Valeurs Foncières) impliquant la parcelle
                        type: integer
                        example: 1
                      nombre_batiments:
                        description: Nombre de bâtiments construits sur la parcelle.
                        type: integer
                        example: 2
                      nombre_coproprietaires:
                        description: >-
                          Nombre de copropriétés dont des lots sont situés sur
                          la parcelle
                        type: integer
                        example: 1
                      nombre_proprietaires:
                        description: >-
                          Nombre de propriétaires personnes morales
                          (entreprises, SCI, etc.) possédant des droits sur la
                          parcelle
                        type: integer
                        example: 1
                      nombre_occupants:
                        description: >-
                          Nombre d'établissements (SIRENE) implantés sur la
                          parcelle
                        type: integer
                        example: 1
                      nombre_permis:
                        description: >-
                          Nombre de permis de construire et autorisations
                          d'urbanisme (PC, PA, DP) déposés sur la parcelle
                        type: integer
                        example: 1
                      nombre_monuments_historiques:
                        description: >-
                          Nombre de monuments historiques (base Mérimée) situés
                          à proximité de la parcelle
                        type: integer
                        example: 1
                    type: object
                  centre:
                    description: >-
                      Coordonnées du centre géographique de la parcelle au
                      format GeoJSON Point
                    properties:
                      type:
                        type: string
                        example: Point
                      coordinates:
                        description: Tableau [longitude, latitude]
                        type: array
                        items:
                          type: number
                        example:
                          - 2.3522
                          - 48.8566
                    type: object
                  contour:
                    description: >-
                      Contour géographique complet de la parcelle au format
                      GeoJSON Polygon ou MultiPolygon
                    properties:
                      type:
                        type: string
                        example: Polygon
                      coordinates:
                        description: Tableau de coordonnées formant le polygone
                        type: array
                        items:
                          type: array
                          items:
                            type: number
                    type: object
                  bbox:
                    description: >-
                      Boîte englobante (bounding box) de la parcelle au format
                      GeoJSON Polygon rectangulaire
                    properties:
                      type:
                        type: string
                        example: Polygon
                      coordinates:
                        description: >-
                          Tableau de coordonnées formant le rectangle englobant
                          [minLon,minLat], [maxLon,minLat], [maxLon,maxLat],
                          [minLon,maxLat], [minLon,minLat]
                        type: array
                        items:
                          type: array
                          items:
                            type: number
                    type: object
                type: object
                example:
                  cadastre_id: 75108000BO0025
                  municipalite:
                    code: '75108'
                    nom: Paris 8e Arrondissement
                    codes_postaux:
                      - '75008'
                  quartier:
                    code: '751080804'
                    nom: Champs-Elysées
                    type: Habitat
                  lieu_dit: null
                  prefixe: '000'
                  section: BO
                  numero: '0025'
                  superficie: 523.45
                  perimetre: 102.34
                  arpente: true
                  adresses:
                    - label: 8 Avenue des Champs-Élysées 75008 Paris
                      fiability: 90
                  detail:
                    piscines:
                      nombre: 0
                      surface_totale: null
                      forme: null
                    batiments_durs:
                      nombre: 2
                      surface_totale: 450.5
                    batiments_legers:
                      nombre: 0
                      surface_totale: null
                    surfaces:
                      jardin: 100
                      emprise_sol: 200.5
                      habitable: 350
                      habitable_calculee: false
                    hauteurs:
                      min: 8.5
                      max: 12
                    altitudes:
                      min: 45.2
                      max: 46.8
                    construction:
                      annee_min: 1890
                      annee_max: 1920
                      nombre_etages: 3
                    caracteristiques:
                      bati_type: 3
                      est_isolee: false
                      nb_parcelles_adjacentes: 4
                      nb_batiments_mitoyens: 2
                    risques:
                      argile: Moyen
                      radon: Faible
                    estimations:
                      prix_vente: 850000
                      prix_vente_ppm: 2428.57
                      prix_location: 2500
                      prix_location_ppm: 7.14
                  batiments:
                    - type: 1
                      type_label: Bâtiment dur
                      superficie: 200.5
                      perimetre: 60.2
                    - type: 1
                      type_label: Bâtiment dur
                      superficie: 250
                      perimetre: 65.8
                  zones_plu:
                    - titre: Zone Urbaine Mixte
                      description: 'Zone UB : Zone urbaine dense'
                      zone: U
                      type_zone: UB
                      surface: 523.45
                      perimetre: 102.34
                      documents:
                        partition: 75108_PLU_20210115
                        fichiers:
                          - titre: Règlement Zones UB
                            nom_fichier: 75108_reglement_UB.pdf
                            url: https://example.com/plu/75108_reglement_UB.pdf
                            categorie: Documents Règlementaires
                            date_creation: '2021-01-15'
                  dpes:
                    - numero_dpe: '2301E0123456'
                      type_dpe: 0
                      date_etablissement: '2023-03-15'
                      date_reception: '2023-03-20'
                      date_visite: '2023-03-10'
                      date_fin_validite: '2033-03-15'
                      version: '2.1'
                      etiquette_dpe: D
                      etiquette_ges: C
                      adresse: 8 Avenue des Champs-Élysées
                      bati_type: 3
                      type_batiment: maison
                      surface_habitable: 350
                      annee_construction: 1900
                      periode_construction: 1881-1914
                      nombre_niveau_logement: 2
                      hauteur_sous_plafond: 2.8
                      conso_energie: 220.5
                      conso_chauffage: 180
                      conso_ecs: 30.5
                      conso_refroidissement: 5
                      conso_eclairage: 5
                      emission_ges: 45.2
                      emission_ges_chauffage: 38
                      emission_ges_ecs: 7.2
                      cout_total: 3200
                      cout_chauffage: 2700
                      cout_ecs: 500
                  dvfs:
                    - id_mutation: 2022-12345
                      date_mutation: '2022-06-15'
                      nature_mutation: Vente
                      valeur_fonciere: 850000
                      vefa: false
                      code_type_bien: 111
                      libelle_type: UNE MAISON
                      bati_type: 3
                      nb_dispositions: 1
                      nb_lots: 1
                      nb_parcelles: 1
                      nb_parcelles_mutees: 1
                      nb_locaux: 1
                      nb_maisons: 1
                      nb_appartements: 0
                      nb_dependances: 0
                      nb_locaux_activite: 0
                      surface_terrain: 523.45
                      surface_batie: 350
                      surface_maisons: 350
                      surface_appartements: 0
                      surface_activite: 0
                  coproprietaires:
                    - immatriculation: ABC123456789
                      nom: Résidence du Parc
                      type_syndic: Professionnel
                      mandat: Mandat en cours
                      adresse_complete: 15 Avenue des Champs-Élysées 75008 Paris
                      adresse_comp1: Bâtiment A
                      adresse_comp2: null
                      adresse_comp3: null
                      nb_adresse_comp: 1
                      date_reglement: '2015-06-15'
                      residence_service: false
                      syndic_cooperatif: false
                      syndic_principal: true
                      num_syndic_principal: null
                      nb_asl: 0
                      nb_aful: 0
                      nb_union: 0
                      nb_lot: 45
                      nb_lot_hab_bur_com: 40
                      nb_lot_hab: 35
                      nb_lot_stationement: 45
                      nb_arrete_sante: 0
                      nb_arrete_peril: 0
                      nb_arrete_equipement: 0
                      syndic:
                        siren: '987654321'
                        denomination: SYNDIC EXEMPLE SAS
                  proprietaires:
                    - siren: '987654321'
                      denomination: SOCIETE LOCATAIRE
                      code_droit: P
                      libelle_code_droit: Propriétaire
                      forme_juridique: Société par actions simplifiée
                      forme_juridique_abregee: '5710'
                      type_bien: LOCAL
                      adresse_complete: 8 Avenue des Champs-Élysées 75008 Paris
                      adresse_numero: '8'
                      adresse_indice_repetition: null
                      adresse_nature_voie: Avenue
                      adresse_nom_voie: des Champs-Élysées
                      identification_local:
                        batiment: A
                        entree: '2'
                        niveau: '3'
                        porte: '301'
                      subdivision_fiscale: null
                      subdivision_nature_culture: null
                      subdivision_superficie: null
                  occupants:
                    - siret: '12345678900015'
                      siren: '123456789'
                      nic: '00015'
                      denomination_complete: ENTREPRISE EXEMPLE SAS
                      denomination_usuelle: null
                      enseigne_1: null
                      enseigne_2: null
                      enseigne_3: null
                      activite_principale: 7022Z
                      activite_principale_registre_metiers: null
                      nomenclature_activite_principale: NAFRev2
                      categorie_activite: Conseil pour les affaires et autres conseils de gestion
                      categorie_parent_activite: Conseil et assistance
                      naf_section:
                        code: M
                        label: Activités spécialisées, scientifiques et techniques
                      naf_division:
                        code: '70'
                        label: Activités des sièges sociaux ; conseil de gestion
                      naf_groupe:
                        code: '70.2'
                        label: Conseil de gestion
                      naf_classe:
                        code: '70.22'
                        label: >-
                          Conseil pour les affaires et autres conseils de
                          gestion
                      naf_sous_classe:
                        code: 70.22Z
                        label: >-
                          Conseil pour les affaires et autres conseils de
                          gestion
                      etat_administratif: Actif
                      caractere_employeur: true
                      tranche_effectifs: 11
                      annee_effectifs: 2023
                      date_creation: '2015-06-01'
                      date_debut: '2015-06-01'
                      date_dernier_traitement: '2024-01-15T10:30:00'
                      etablissement_siege: true
                      statut_diffusion: 0
                      adresse_complete: 8 Avenue des Champs-Élysées 75008 Paris
                      adresse_numero: '8'
                      adresse_indice_repetition: null
                      adresse_nom_voie: Avenue des Champs-Élysées
                      adresse_code_postal: '75008'
                  permis_construire:
                    - code: PC 075 108 22 12345
                      type_autorisation: PC
                      etat: Autorisé
                      date_autorisation: '2022-03-15'
                      date_doc: '2022-04-10'
                      date_daact: '2023-02-20'
                      nature_projet: Construction de maison individuelle
                      cat_dem: Particulier
                      siren_dem: null
                      denomination_dem: null
                      rec_archi: true
                      zone_op: null
                      extension: false
                      surelevation: false
                      nivsupp: 0
                      nb_niv_max: 2
                      utilisation: Habitation
                      res_princip_ou_second: Principale
                      type_annexe: null
                      residence: Individuelle
                      nb_chambres: null
                      nb_lgt_ind_crees: 1
                      nb_lgt_col_crees: 0
                      nb_lgt_demolis: 0
                      nb_lgt_1p: 0
                      nb_lgt_2p: 0
                      nb_lgt_3p: 0
                      nb_lgt_4p: 1
                      nb_lgt_5p: 0
                      nb_lgt_6p_plus: 0
                      nb_lgt_pret_loc_social: 0
                      surf_hab_avant: 0
                      surf_hab_creee: 120.5
                      surf_hab_issue_transfo: 0
                      surf_hab_demolie: 0
                      surf_hab_transformee: 0
                      surf_autre_avant: 0
                      surf_autre_creee: 25
                      surf_autre_issue_transfo: 0
                      surf_autre_demolie: 0
                      surf_autre_transformee: 0
                  monuments_historiques:
                    - ref_merimee: PA00088799
                      nom: Arc de Triomphe
                      distance: 250.5
                  consommations:
                    electricite:
                      - annee: 2022
                        conso_residentielle: 5500
                        conso_professionnelle: 12000
                        conso_totale: 17500
                    gaz:
                      - annee: 2022
                        conso_residentielle: 8500
                        conso_professionnelle: 0
                        conso_totale: 8500
                  statistiques:
                    nombre_dpes: 1
                    nombre_dvfs: 1
                    nombre_batiments: 2
                    nombre_coproprietaires: 1
                    nombre_proprietaires: 1
                    nombre_occupants: 1
                    nombre_permis: 1
                    nombre_monuments_historiques: 1
                  centre:
                    type: Point
                    coordinates:
                      - 2.3522
                      - 48.8566
                  contour:
                    type: Polygon
                    coordinates:
                      - - - 2.352
                          - 48.8564
                        - - 2.3524
                          - 48.8564
                        - - 2.3524
                          - 48.8568
                        - - 2.352
                          - 48.8568
                        - - 2.352
                          - 48.8564
                  bbox:
                    type: Polygon
                    coordinates:
                      - - - 2.352
                          - 48.8564
                        - - 2.3524
                          - 48.8564
                        - - 2.3524
                          - 48.8568
                        - - 2.352
                          - 48.8568
                        - - 2.352
                          - 48.8564
            application/geo+json:
              schema:
                title: Format GeoJSON
                description: Format GeoJSON Feature (format=geojson)
                properties:
                  type:
                    type: string
                    example: Feature
                  geometry:
                    description: >-
                      Géométrie principale de la parcelle (Point si
                      geometrie=centre, Polygon/MultiPolygon si
                      geometrie=contour, Polygon si geometrie=bbox)
                    properties:
                      type:
                        type: string
                        example: Polygon
                      coordinates:
                        description: Tableau de coordonnées selon le type de géométrie
                        type: array
                        items:
                          type: array
                          items:
                            type: number
                    type: object
                  properties:
                    description: >-
                      Toutes les propriétés de la parcelle. Les autres
                      géométries (centre, contour, bbox) non utilisées dans
                      'geometry' sont incluses ici comme propriétés
                      supplémentaires.
                    properties:
                      cadastre_id:
                        description: >-
                          Identifiant cadastral de la parcelle (voir format JSON
                          pour description complète)
                        type: string
                        example: 75108000BO0025
                      section:
                        description: >-
                          Code de la section cadastrale (voir format JSON pour
                          description complète)
                        type: string
                        example: BO
                      numero:
                        description: >-
                          Numéro de parcelle (voir format JSON pour description
                          complète)
                        type: string
                        example: '0025'
                      prefixe:
                        description: >-
                          Préfixe de la parcelle (voir format JSON pour
                          description complète)
                        type: string
                        example: '000'
                      superficie:
                        description: >-
                          Superficie de la parcelle en m² (voir format JSON pour
                          description complète)
                        type: number
                        example: 523.45
                      perimetre:
                        description: >-
                          Périmètre de la parcelle en m (voir format JSON pour
                          description complète)
                        type: number
                        example: 102.34
                      arpente:
                        description: >-
                          Parcelle arpentée par un géomètre-expert (voir format
                          JSON pour description complète)
                        type: boolean
                        example: true
                      municipalite:
                        description: >-
                          Informations sur la commune (voir format JSON pour
                          description complète)
                        type: object
                      quartier:
                        description: >-
                          Informations sur le quartier IRIS (voir format JSON
                          pour description complète)
                        type: object
                      lieu_dit:
                        description: >-
                          Nom du lieu-dit (voir format JSON pour description
                          complète)
                        type: string
                      adresses:
                        description: >-
                          Adresses postales associées (voir format JSON pour
                          description complète)
                        type: array
                        items:
                          type: object
                      detail:
                        description: >-
                          Détails complets de la parcelle (voir format JSON pour
                          description complète)
                        type: object
                      batiments:
                        description: >-
                          Liste des bâtiments sur la parcelle (voir format JSON
                          pour description complète)
                        type: array
                        items:
                          type: object
                      zones_plu:
                        description: >-
                          Zones PLU - Plan Local d'Urbanisme (voir format JSON
                          pour description complète)
                        type: array
                        items:
                          type: object
                      dpes:
                        description: >-
                          Diagnostics de performance énergétique (voir format
                          JSON pour description complète)
                        type: array
                        items:
                          type: object
                      dvfs:
                        description: >-
                          Transactions immobilières - Demandes de Valeurs
                          Foncières (voir format JSON pour description complète)
                        type: array
                        items:
                          type: object
                      coproprietaires:
                        description: >-
                          Copropriétés associées (voir format JSON pour
                          description complète)
                        type: array
                        items:
                          type: object
                      proprietaires:
                        description: >-
                          Propriétaires - personnes morales (voir format JSON
                          pour description complète)
                        type: array
                        items:
                          type: object
                      occupants:
                        description: >-
                          Occupants - Établissements SIRENE (voir format JSON
                          pour description complète)
                        type: array
                        items:
                          type: object
                      permis_construire:
                        description: >-
                          Permis de construire et autorisations d'urbanisme
                          (voir format JSON pour description complète)
                        type: array
                        items:
                          type: object
                      monuments_historiques:
                        description: >-
                          Monuments historiques à proximité - base Mérimée (voir
                          format JSON pour description complète)
                        type: array
                        items:
                          type: object
                      consommations:
                        description: >-
                          Consommations énergétiques réelles - Enedis/GRDF (voir
                          format JSON pour description complète)
                        type: object
                      statistiques:
                        description: >-
                          Statistiques agrégées - compteurs (voir format JSON
                          pour description complète)
                        type: object
                      centre:
                        description: >-
                          Coordonnées du centre géographique (présent uniquement
                          si geometrie != centre)
                        properties:
                          type:
                            type: string
                            example: Point
                          coordinates:
                            description: Tableau [longitude, latitude]
                            type: array
                            items:
                              type: number
                            example:
                              - 2.3522
                              - 48.8566
                        type: object
                      contour:
                        description: >-
                          Contour géographique complet (présent uniquement si
                          geometrie != contour)
                        properties:
                          type:
                            type: string
                            example: Polygon
                          coordinates:
                            description: Tableau de coordonnées formant le polygone
                            type: array
                            items:
                              type: array
                              items:
                                type: number
                        type: object
                      bbox:
                        description: >-
                          Boîte englobante (présent uniquement si geometrie !=
                          bbox)
                        properties:
                          type:
                            type: string
                            example: Polygon
                          coordinates:
                            description: >-
                              Tableau de coordonnées formant le rectangle
                              englobant
                            type: array
                            items:
                              type: array
                              items:
                                type: number
                        type: object
                    type: object
                type: object
                example:
                  type: Feature
                  geometry:
                    type: Polygon
                    coordinates:
                      - - - 2.352
                          - 48.8564
                        - - 2.3524
                          - 48.8564
                        - - 2.3524
                          - 48.8568
                        - - 2.352
                          - 48.8568
                        - - 2.352
                          - 48.8564
                  properties:
                    cadastre_id: 75108000BO0025
                    municipalite:
                      code: '75108'
                      nom: Paris 8e Arrondissement
                      codes_postaux:
                        - '75008'
                    quartier:
                      code: '751080804'
                      nom: Champs-Elysées
                      type: Habitat
                    lieu_dit: null
                    prefixe: '000'
                    section: BO
                    numero: '0025'
                    superficie: 523.45
                    perimetre: 102.34
                    arpente: true
                    adresses:
                      - label: 8 Avenue des Champs-Élysées 75008 Paris
                        fiability: 90
                    detail:
                      piscines:
                        nombre: 0
                        surface_totale: null
                        forme: null
                      batiments_durs:
                        nombre: 2
                        surface_totale: 450.5
                      batiments_legers:
                        nombre: 0
                        surface_totale: null
                      surfaces:
                        jardin: 100
                        emprise_sol: 200.5
                        habitable: 350
                        habitable_calculee: false
                      hauteurs:
                        min: 8.5
                        max: 12
                      altitudes:
                        min: 45.2
                        max: 46.8
                      construction:
                        annee_min: 1890
                        annee_max: 1920
                        nombre_etages: 3
                      caracteristiques:
                        bati_type: 3
                        est_isolee: false
                        nb_parcelles_adjacentes: 4
                        nb_batiments_mitoyens: 2
                      risques:
                        argile: Moyen
                        radon: Faible
                      estimations:
                        prix_vente: 850000
                        prix_vente_ppm: 2428.57
                        prix_location: 2500
                        prix_location_ppm: 7.14
                    batiments:
                      - type: 1
                        type_label: Bâtiment dur
                        superficie: 200.5
                        perimetre: 60.2
                      - type: 1
                        type_label: Bâtiment dur
                        superficie: 250
                        perimetre: 65.8
                    zones_plu:
                      - titre: Zone Urbaine Mixte
                        description: 'Zone UB : Zone urbaine dense'
                        zone: U
                        type_zone: UB
                        surface: 523.45
                        perimetre: 102.34
                        documents:
                          partition: 75108_PLU_20210115
                          fichiers:
                            - titre: Règlement Zones UB
                              nom_fichier: 75108_reglement_UB.pdf
                              url: https://example.com/plu/75108_reglement_UB.pdf
                              categorie: Documents Règlementaires
                              date_creation: '2021-01-15'
                    dpes:
                      - numero_dpe: '2301E0123456'
                        type_dpe: 0
                        date_etablissement: '2023-03-15'
                        date_reception: '2023-03-20'
                        date_visite: '2023-03-10'
                        date_fin_validite: '2033-03-15'
                        version: '2.1'
                        etiquette_dpe: D
                        etiquette_ges: C
                        adresse: 8 Avenue des Champs-Élysées
                        bati_type: 3
                        type_batiment: immeuble
                        surface_habitable: 350
                        annee_construction: 1900
                        periode_construction: 1881-1914
                        nombre_niveau_logement: 2
                        hauteur_sous_plafond: 2.8
                        conso_energie: 220.5
                        conso_chauffage: 180
                        conso_ecs: 30.5
                        conso_refroidissement: 5
                        conso_eclairage: 5
                        emission_ges: 45.2
                        emission_ges_chauffage: 38
                        emission_ges_ecs: 7.2
                        cout_total: 3200
                        cout_chauffage: 2700
                        cout_ecs: 500
                    dvfs:
                      - id_mutation: 2022-12345
                        date_mutation: '2022-06-15'
                        nature_mutation: Vente
                        valeur_fonciere: 850000
                        vefa: false
                        code_type_bien: 111
                        libelle_type: UNE MAISON
                        bati_type: 3
                        nb_dispositions: 1
                        nb_lots: 1
                        nb_parcelles: 1
                        nb_parcelles_mutees: 1
                        nb_locaux: 1
                        nb_maisons: 1
                        nb_appartements: 0
                        nb_dependances: 0
                        nb_locaux_activite: 0
                        surface_terrain: 523.45
                        surface_batie: 350
                        surface_maisons: 350
                        surface_appartements: 0
                        surface_activite: 0
                    coproprietaires:
                      - immatriculation: ABC123456789
                        nom: Résidence du Parc
                        type_syndic: Professionnel
                        mandat: Mandat en cours
                        adresse_complete: 15 Avenue des Champs-Élysées 75008 Paris
                        adresse_comp1: Bâtiment A
                        adresse_comp2: null
                        adresse_comp3: null
                        nb_adresse_comp: 1
                        date_reglement: '2015-06-15'
                        residence_service: false
                        syndic_cooperatif: false
                        syndic_principal: true
                        num_syndic_principal: null
                        nb_asl: 0
                        nb_aful: 0
                        nb_union: 0
                        nb_lot: 45
                        nb_lot_hab_bur_com: 40
                        nb_lot_hab: 35
                        nb_lot_stationement: 45
                        nb_arrete_sante: 0
                        nb_arrete_peril: 0
                        nb_arrete_equipement: 0
                        syndic:
                          siren: '987654321'
                          denomination: SYNDIC EXEMPLE SAS
                    proprietaires:
                      - siren: '987654321'
                        denomination: SOCIETE LOCATAIRE
                        code_droit: P
                        libelle_code_droit: Propriétaire
                        forme_juridique: Société par actions simplifiée
                        forme_juridique_abregee: '5710'
                        type_bien: LOCAL
                        adresse_complete: 8 Avenue des Champs-Élysées 75008 Paris
                        adresse_numero: '8'
                        adresse_indice_repetition: null
                        adresse_nature_voie: Avenue
                        adresse_nom_voie: des Champs-Élysées
                        identification_local:
                          batiment: A
                          entree: '2'
                          niveau: '3'
                          porte: '301'
                        subdivision_fiscale: null
                        subdivision_nature_culture: null
                        subdivision_superficie: null
                    occupants:
                      - siret: '12345678900015'
                        siren: '123456789'
                        nic: '00015'
                        denomination_complete: ENTREPRISE EXEMPLE SAS
                        denomination_usuelle: null
                        enseigne_1: null
                        enseigne_2: null
                        enseigne_3: null
                        activite_principale: 7022Z
                        activite_principale_registre_metiers: null
                        nomenclature_activite_principale: NAFRev2
                        categorie_activite: >-
                          Conseil pour les affaires et autres conseils de
                          gestion
                        categorie_parent_activite: Conseil et assistance
                        naf_section:
                          code: M
                          label: Activités spécialisées, scientifiques et techniques
                        naf_division:
                          code: '70'
                          label: Activités des sièges sociaux ; conseil de gestion
                        naf_groupe:
                          code: '70.2'
                          label: Conseil de gestion
                        naf_classe:
                          code: '70.22'
                          label: >-
                            Conseil pour les affaires et autres conseils de
                            gestion
                        naf_sous_classe:
                          code: 70.22Z
                          label: >-
                            Conseil pour les affaires et autres conseils de
                            gestion
                        etat_administratif: Actif
                        caractere_employeur: true
                        tranche_effectifs: 11
                        annee_effectifs: 2023
                        date_creation: '2015-06-01'
                        date_debut: '2015-06-01'
                        date_dernier_traitement: '2024-01-15T10:30:00'
                        etablissement_siege: true
                        statut_diffusion: 0
                        adresse_complete: 8 Avenue des Champs-Élysées 75008 Paris
                        adresse_numero: '8'
                        adresse_indice_repetition: null
                        adresse_nom_voie: Avenue des Champs-Élysées
                        adresse_code_postal: '75008'
                    permis_construire:
                      - code: PC 075 108 22 12345
                        type_autorisation: PC
                        etat: Autorisé
                        date_autorisation: '2022-03-15'
                        date_doc: '2022-04-10'
                        date_daact: '2023-02-20'
                        nature_projet: Construction de maison individuelle
                        cat_dem: Particulier
                        siren_dem: null
                        denomination_dem: null
                        rec_archi: true
                        zone_op: null
                        extension: false
                        surelevation: false
                        nivsupp: 0
                        nb_niv_max: 2
                        utilisation: Habitation
                        res_princip_ou_second: Principale
                        type_annexe: null
                        residence: Individuelle
                        nb_chambres: null
                        nb_lgt_ind_crees: 1
                        nb_lgt_col_crees: 0
                        nb_lgt_demolis: 0
                        nb_lgt_1p: 0
                        nb_lgt_2p: 0
                        nb_lgt_3p: 0
                        nb_lgt_4p: 1
                        nb_lgt_5p: 0
                        nb_lgt_6p_plus: 0
                        nb_lgt_pret_loc_social: 0
                        surf_hab_avant: 0
                        surf_hab_creee: 120.5
                        surf_hab_issue_transfo: 0
                        surf_hab_demolie: 0
                        surf_hab_transformee: 0
                        surf_autre_avant: 0
                        surf_autre_creee: 25
                        surf_autre_issue_transfo: 0
                        surf_autre_demolie: 0
                        surf_autre_transformee: 0
                    monuments_historiques:
                      - ref_merimee: PA00088799
                        nom: Arc de Triomphe
                        distance: 250.5
                    consommations:
                      electricite:
                        - annee: 2022
                          conso_residentielle: 5500
                          conso_professionnelle: 12000
                          conso_totale: 17500
                      gaz:
                        - annee: 2022
                          conso_residentielle: 8500
                          conso_professionnelle: 0
                          conso_totale: 8500
                    statistiques:
                      nombre_dpes: 1
                      nombre_dvfs: 1
                      nombre_batiments: 2
                      nombre_coproprietaires: 1
                      nombre_proprietaires: 1
                      nombre_occupants: 1
                      nombre_permis: 1
                      nombre_monuments_historiques: 1
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.352
                            - 48.8564
                          - - 2.3524
                            - 48.8564
                          - - 2.3524
                            - 48.8568
                          - - 2.352
                            - 48.8568
                          - - 2.352
                            - 48.8564
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune parcelle trouvée
      security:
        - bearer:
            - '*'
  /api/v1/parcelles/previsualisation/{cadastre_id}:
    get:
      tags:
        - Parcelles
      summary: Générer une prévisualisation SVG d'une parcelle
      operationId: getParcelPreview
      parameters:
        - name: cadastre_id
          in: path
          description: >-
            Identifiant(s) cadastral(aux) de la/des parcelle(s) (séparés par des
            virgules)
          required: true
          schema:
            type: string
            example: 75101000AD0001,75101000AE0001,75101000AC0002,75101000AB0002
        - name: theme
          in: query
          description: >-
            Thème de rendu (défaut: realisme_terrain)


            **THÈMES DE PRÉVISUALISATION (Rendu réaliste/coloré) :**

            - `realisme_terrain` : Rendu réaliste avec textures terrain (par
            défaut)

            - `verre_noyer_nuit` : Ambiance nocturne avec tons verre et noyer

            - `riviera_sable_teck` : Palette riviera aux tons sable et teck

            - `mediterraneen_azur` : Style méditerranéen avec tons azur

            - `chalet_hautes_cimes` : Ambiance chalet montagnard

            - `countryside_charm` : Charme champêtre et rural

            - `coastal_azure` : Côte azur avec tons bleu océan

            - `nordique_ton_pierre` : Style nordique avec tons pierre naturelle

            - `corporate_monochrome` : Design sobre monochrome corporate

            - `modern_flat` : Design plat moderne et épuré

            - `nuit_etoilee` : Ambiance nuit étoilée

            - `isometric_urban` : Vue isométrique urbaine

            - `vibrant_orchard` : Verger vibrant aux couleurs vives

            - `foret_vivante` : Forêt luxuriante et verdoyante

            - `old` : Style ancien/vintage

            - `sunset_paradise` : Paradis aux couleurs du coucher de soleil

            - `garden_paradise` : Jardin paradisiaque

            - `japanese_zen` : Zen japonais épuré

            - `real` : Toitures ardoise réaliste

            - `classic` : Lotissement traditionnel avec tuiles

            - `flat` : Illustration ludique et colorée

            - `simple` : Flat avec verdure simple

            - `neon` : Style néon sur fond noir


            **THÈMES PLAN (Fond blanc/technique) :**

            - `plan_millimetre` : Plan technique millimétré précis

            - `cadastre_plan` : Plan cadastral officiel

            - `architecte_blueprint` : Blueprint d'architecte classique

            - `architecte_noir_blanc` : Plan architecte noir et blanc

            - `scandinave_pure` : Épuré scandinave minimaliste

            - `art_deco_gold` : Art déco avec touches dorées

            - `boheme_naturel` : Style bohème aux tons naturels

            - `hachures_atelier` : Hachures techniques d'atelier

            - `cadastral_ancien` : Cadastre ancien historique

            - `topographique_contour` : Plan topographique avec courbes

            - `nautique_marine` : Style carte marine/nautique

            - `urbanisme_modern` : Urbanisme moderne et technique

            - `minimal_gris_perle` : Minimaliste gris perle

            - `commercial_premium` : Présentation commerciale premium

            - `notarial_officiel` : Document notarial officiel

            - `promoteur_modern` : Style promoteur immobilier moderne

            - `plan` : Plan beige avec lignes

            - `trace` : Contour au stylo tracé

            - `tech_futuriste` : Technologique futuriste

            - `circuit_imprime` : Style circuit imprimé électronique
          required: false
          schema:
            type: string
            default: realisme_terrain
        - name: width
          in: query
          description: 'Largeur du SVG en pixels (défaut: 800, min: 10, max: 10000)'
          required: false
          schema:
            type: integer
            default: 800
        - name: height
          in: query
          description: 'Hauteur du SVG en pixels (défaut: 800, min: 10, max: 10000)'
          required: false
          schema:
            type: integer
            default: 800
        - name: dpi
          in: query
          description: 'Résolution du SVG en DPI (défaut: 96, min: 80, max: 300)'
          required: false
          schema:
            type: integer
            default: 96
            maximum: 300
            minimum: 80
        - name: afficher_surface
          in: query
          description: 'Afficher la surface de la parcelle (défaut: false)'
          required: false
          schema:
            type: boolean
            default: false
        - name: afficher_mesures
          in: query
          description: 'Afficher les mesures et dimensions (défaut: false)'
          required: false
          schema:
            type: boolean
            default: false
        - name: afficher_perimetre
          in: query
          description: 'Afficher le périmètre de la parcelle (défaut: false)'
          required: false
          schema:
            type: boolean
            default: false
        - name: afficher_coordonnees
          in: query
          description: 'Afficher les coordonnées géographiques (défaut: false)'
          required: false
          schema:
            type: boolean
            default: false
        - name: afficher_numero_parcelle
          in: query
          description: 'Afficher le numéro de parcelle cadastrale (défaut: false)'
          required: false
          schema:
            type: boolean
            default: false
        - name: afficher_echelle
          in: query
          description: 'Afficher l''échelle graphique (défaut: false)'
          required: false
          schema:
            type: boolean
            default: false
        - name: echelle
          in: query
          description: >-
            Échelle de rendu de la carte (défaut: auto). Valeurs possibles:
            'auto' ou un entier parmi 50, 100, 200, 300, 400, 500, 750, 1000,
            1500, 2000, 3000, 5000, 10000. L'échelle représente le dénominateur
            (ex: 500 = échelle 1/500)
          required: false
          schema:
            type: string
            default: auto
            enum:
              - auto
              - '50'
              - '100'
              - '200'
              - '300'
              - '400'
              - '500'
              - '750'
              - '1000'
              - '1500'
              - '2000'
              - '3000'
              - '5000'
              - '10000'
      responses:
        '200':
          description: >-
            Succès - Retourne une image SVG de la prévisualisation de la
            parcelle
          content:
            image/svg+xml:
              schema:
                type: string
                format: binary
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune parcelle trouvée
      security:
        - bearer:
            - '*'
  /api/v1/regions:
    get:
      tags:
        - Données territoriales
      summary: Rechercher des régions françaises
      description: >-
        Permet de rechercher des régions par différents critères : coordonnées
        GPS, nom, code INSEE, ou filtres sur la superficie. Les résultats
        peuvent être retournés au format JSON ou GeoJSON.
      operationId: getRegions
      parameters:
        - name: code
          in: query
          description: Code INSEE de la région (2 chiffres).
          required: false
          schema:
            type: string
            example: ''
        - name: nom
          in: query
          description: Nom de la région (recherche par similarité).
          required: false
          schema:
            type: string
            example: Île-de-France
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher la région
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher la région
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=nom,code,superficie
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - nom
                - code
                - superficie
                - perimetre
                - centre
                - contour
                - bbox
            default:
              - nom
              - code
              - superficie
              - centre
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: nom
            enum:
              - nom
              - code
              - superficie
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 10.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 10
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    code:
                      description: Code INSEE de la région
                      type: string
                      example: '11'
                    nom:
                      description: Nom officiel de la région
                      type: string
                      example: Île-de-France
                    superficie:
                      description: Superficie de la région en m²
                      type: number
                      example: 12011968000
                    perimetre:
                      description: Périmètre de la région en m
                      type: number
                      example: 890123.45
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    contour:
                      description: >-
                        Contour géographique de la région (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante de la région (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - code: '11'
                    nom: Île-de-France
                    superficie: 12011968000
                    perimetre: 890123.45
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 1.4463
                            - 48.1205
                          - - 3.5579
                            - 48.1205
                          - - 3.5579
                            - 49.2415
                          - - 1.4463
                            - 49.2415
                          - - 1.4463
                            - 48.1205
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 1.4463
                            - 48.1205
                          - - 3.5579
                            - 48.1205
                          - - 3.5579
                            - 49.2415
                          - - 1.4463
                            - 49.2415
                          - - 1.4463
                            - 48.1205
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de la région (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            code:
                              description: Code INSEE de la région
                              type: string
                              example: '11'
                            nom:
                              description: Nom officiel de la région
                              type: string
                              example: Île-de-France
                            superficie:
                              description: Superficie de la région en m²
                              type: number
                              example: 12011968000
                            perimetre:
                              description: Périmètre de la région en m
                              type: number
                              example: 890123.45
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.3522
                                    - 48.8566
                              type: object
                            bbox:
                              description: Boîte englobante de la région (GeoJSON Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 1.4463
                              - 48.1205
                            - - 3.5579
                              - 48.1205
                            - - 3.5579
                              - 49.2415
                            - - 1.4463
                              - 49.2415
                            - - 1.4463
                              - 48.1205
                      properties:
                        code: '11'
                        nom: Île-de-France
                        superficie: 12011968000
                        perimetre: 890123.45
                        centre:
                          type: Point
                          coordinates:
                            - 2.3522
                            - 48.8566
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 1.4463
                                - 48.1205
                              - - 3.5579
                                - 48.1205
                              - - 3.5579
                                - 49.2415
                              - - 1.4463
                                - 49.2415
                              - - 1.4463
                                - 48.1205
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune région trouvée
      security:
        - bearer:
            - '*'
  /api/v1/departements:
    get:
      tags:
        - Données territoriales
      summary: Rechercher des départements français
      description: >-
        Permet de rechercher des départements par différents critères :
        coordonnées GPS, nom, code INSEE, code région, ou filtres sur la
        superficie. Les résultats peuvent être retournés au format JSON ou
        GeoJSON.
      operationId: getDepartments
      parameters:
        - name: code
          in: query
          description: 'Code INSEE du département (2 chiffres, ex: 75 pour Paris).'
          required: false
          schema:
            type: string
            example: ''
        - name: nom
          in: query
          description: Nom du département (recherche par similarité).
          required: false
          schema:
            type: string
            example: Paris
        - name: code_region
          in: query
          description: >-
            Code INSEE de la région parente (filtre les départements appartenant
            à cette région).
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher le département
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher le département
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=nom,code,region
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - nom
                - code
                - region
                - superficie
                - perimetre
                - centre
                - contour
                - bbox
            default:
              - nom
              - code
              - superficie
              - centre
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: nom
            enum:
              - nom
              - code
              - superficie
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant)
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 10.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 10
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    code:
                      description: Code INSEE du département
                      type: string
                      example: '75'
                    nom:
                      description: Nom officiel du département
                      type: string
                      example: Paris
                    superficie:
                      description: Superficie du département en m²
                      type: number
                      example: 105400000
                    perimetre:
                      description: Périmètre du département en m
                      type: number
                      example: 54321.78
                    region:
                      description: Informations sur la région parente
                      properties:
                        code:
                          type: string
                          example: '11'
                        nom:
                          type: string
                          example: Île-de-France
                      type: object
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    contour:
                      description: >-
                        Contour géographique du département (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante du département (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - code: '75'
                    nom: Paris
                    superficie: 105400000
                    perimetre: 54321.78
                    region:
                      code: '11'
                      nom: Île-de-France
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.2241
                            - 48.8155
                          - - 2.4699
                            - 48.8155
                          - - 2.4699
                            - 48.9022
                          - - 2.2241
                            - 48.9022
                          - - 2.2241
                            - 48.8155
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.2241
                            - 48.8155
                          - - 2.4699
                            - 48.8155
                          - - 2.4699
                            - 48.9022
                          - - 2.2241
                            - 48.9022
                          - - 2.2241
                            - 48.8155
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie du département (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            code:
                              description: Code INSEE du département
                              type: string
                              example: '75'
                            nom:
                              description: Nom officiel du département
                              type: string
                              example: Paris
                            superficie:
                              description: Superficie du département en m²
                              type: number
                              example: 105400000
                            perimetre:
                              description: Périmètre du département en m
                              type: number
                              example: 54321.78
                            region:
                              description: Informations sur la région parente
                              properties:
                                code:
                                  type: string
                                  example: '11'
                                nom:
                                  type: string
                                  example: Île-de-France
                              type: object
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.3522
                                    - 48.8566
                              type: object
                            bbox:
                              description: >-
                                Boîte englobante du département (GeoJSON
                                Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 2.2241
                              - 48.8155
                            - - 2.4699
                              - 48.8155
                            - - 2.4699
                              - 48.9022
                            - - 2.2241
                              - 48.9022
                            - - 2.2241
                              - 48.8155
                      properties:
                        code: '75'
                        nom: Paris
                        superficie: 105400000
                        perimetre: 54321.78
                        region:
                          code: '11'
                          nom: Île-de-France
                        centre:
                          type: Point
                          coordinates:
                            - 2.3522
                            - 48.8566
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.2241
                                - 48.8155
                              - - 2.4699
                                - 48.8155
                              - - 2.4699
                                - 48.9022
                              - - 2.2241
                                - 48.9022
                              - - 2.2241
                                - 48.8155
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun département trouvé
      security:
        - bearer:
            - '*'
  /api/v1/municipalities:
    get:
      tags:
        - Données territoriales
      summary: Rechercher des communes françaises
      description: >-
        Permet de rechercher des communes par différents critères : coordonnées
        GPS, nom, code INSEE, code postal, code région, code département, statut
        RNU. Les résultats peuvent être retournés au format JSON ou GeoJSON.
      operationId: getMunicipalities
      parameters:
        - name: code
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: ''
        - name: nom
          in: query
          description: Nom de la commune (recherche par similarité).
          required: false
          schema:
            type: string
            example: Paris
        - name: code_postal
          in: query
          description: Code postal (5 chiffres) pour filtrer les communes.
          required: false
          schema:
            type: string
            example: ''
        - name: est_rnu
          in: query
          description: Indique si la commune est soumise au Règlement National d'Urbanisme.
          required: false
          schema:
            type: boolean
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher la commune
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher la commune
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=nom,code,departement
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - nom
                - code
                - codes_postaux
                - superficie
                - population
                - departement
                - region
                - est_rnu
                - perimetre
                - centre
                - contour
                - bbox
            default:
              - nom
              - code
              - codes_postaux
              - population
              - superficie
              - centre
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: nom
            enum:
              - nom
              - code
              - superficie
              - population
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 20.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 20
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    code:
                      description: Code INSEE de la commune
                      type: string
                      example: '75056'
                    nom:
                      description: Nom officiel de la commune
                      type: string
                      example: Paris
                    codes_postaux:
                      description: Liste des codes postaux de la commune
                      type: array
                      items:
                        type: string
                      example:
                        - '75001'
                        - '75002'
                        - '75003'
                    departement:
                      description: Informations sur le département parent
                      properties:
                        code:
                          type: string
                          example: '75'
                        nom:
                          type: string
                          example: Paris
                      type: object
                    region:
                      description: Informations sur la région parente
                      properties:
                        code:
                          type: string
                          example: '11'
                        nom:
                          type: string
                          example: Île-de-France
                      type: object
                    population:
                      description: Population municipale
                      type: integer
                      example: 2187526
                    superficie:
                      description: Superficie de la commune en m²
                      type: number
                      example: 105400000
                    est_rnu:
                      description: Commune soumise au RNU
                      type: boolean
                      example: false
                    perimetre:
                      description: Périmètre de la commune en m
                      type: number
                      example: 54322.12
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    contour:
                      description: >-
                        Contour géographique de la commune (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante de la commune (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - code: '75056'
                    nom: Paris
                    codes_postaux:
                      - '75001'
                      - '75002'
                      - '75003'
                    departement:
                      code: '75'
                      nom: Paris
                    region:
                      code: '11'
                      nom: Île-de-France
                    population: 2187526
                    superficie: 105400000
                    est_rnu: false
                    perimetre: 54322.12
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.2241
                            - 48.8155
                          - - 2.4699
                            - 48.8155
                          - - 2.4699
                            - 48.9022
                          - - 2.2241
                            - 48.9022
                          - - 2.2241
                            - 48.8155
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.2241
                            - 48.8155
                          - - 2.4699
                            - 48.8155
                          - - 2.4699
                            - 48.9022
                          - - 2.2241
                            - 48.9022
                          - - 2.2241
                            - 48.8155
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de la commune (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            code:
                              description: Code INSEE de la commune
                              type: string
                              example: '75056'
                            nom:
                              description: Nom officiel de la commune
                              type: string
                              example: Paris
                            codes_postaux:
                              description: Liste des codes postaux de la commune
                              type: array
                              items:
                                type: string
                              example:
                                - '75001'
                                - '75002'
                                - '75003'
                            departement:
                              description: Informations sur le département parent
                              properties:
                                code:
                                  type: string
                                  example: '75'
                                nom:
                                  type: string
                                  example: Paris
                              type: object
                            region:
                              description: Informations sur la région parente
                              properties:
                                code:
                                  type: string
                                  example: '11'
                                nom:
                                  type: string
                                  example: Île-de-France
                              type: object
                            population:
                              description: Population municipale
                              type: integer
                              example: 2187526
                            superficie:
                              description: Superficie de la commune en m²
                              type: number
                              example: 105400000
                            est_rnu:
                              description: Commune soumise au RNU
                              type: boolean
                              example: false
                            perimetre:
                              description: Périmètre de la commune en m
                              type: number
                              example: 54322.12
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.3522
                                    - 48.8566
                              type: object
                            bbox:
                              description: Boîte englobante de la commune (GeoJSON Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 2.2241
                              - 48.8155
                            - - 2.4699
                              - 48.8155
                            - - 2.4699
                              - 48.9022
                            - - 2.2241
                              - 48.9022
                            - - 2.2241
                              - 48.8155
                      properties:
                        code: '75056'
                        nom: Paris
                        codes_postaux:
                          - '75001'
                          - '75002'
                          - '75003'
                        departement:
                          code: '75'
                          nom: Paris
                        region:
                          code: '11'
                          nom: Île-de-France
                        population: 2187526
                        superficie: 105400000
                        est_rnu: false
                        perimetre: 54322.12
                        centre:
                          type: Point
                          coordinates:
                            - 2.3522
                            - 48.8566
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.2241
                                - 48.8155
                              - - 2.4699
                                - 48.8155
                              - - 2.4699
                                - 48.9022
                              - - 2.2241
                                - 48.9022
                              - - 2.2241
                                - 48.8155
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune commune trouvée
      security:
        - bearer:
            - '*'
  /api/v1/sections:
    get:
      tags:
        - Données territoriales
      summary: Rechercher des sections cadastrales
      description: >-
        Permet de rechercher des sections cadastrales par différents critères :
        coordonnées GPS, code de section, code postal, code INSEE de la commune,
        code département, code région. Les résultats peuvent être retournés au
        format JSON ou GeoJSON.
      operationId: getSections
      parameters:
        - name: code
          in: query
          description: 'Code de la section cadastrale (ex: AB, A, 01).'
          required: false
          schema:
            type: string
            example: AB
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres) pour filtrer les sections.
          required: false
          schema:
            type: string
            example: '75056'
        - name: code_postal
          in: query
          description: Code postal (5 chiffres) pour filtrer les sections cadastrales.
          required: false
          schema:
            type: string
            example: ''
        - name: code_departement
          in: query
          description: Code INSEE du département (2 chiffres) pour filtrer les sections.
          required: false
          schema:
            type: string
            example: ''
        - name: code_region
          in: query
          description: Code INSEE de la région (2 chiffres) pour filtrer les sections.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher la section
            cadastrale contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher la section
            cadastrale contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=nom,municipalite,departement
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - code
                - municipalite
                - departement
                - region
                - superficie
                - perimetre
                - centre
                - contour
                - bbox
            default:
              - code
              - superficie
              - centre
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: code
            enum:
              - code
              - superficie
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 20.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 20
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    code:
                      description: Code de la section cadastrale
                      type: string
                      example: AB
                    superficie:
                      description: Superficie de la section en m²
                      type: number
                      example: 523456.78
                    perimetre:
                      description: Périmètre de la section en m
                      type: number
                      example: 3210.45
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          type: string
                          example: '75056'
                        nom:
                          type: string
                          example: Paris
                        codes_postaux:
                          description: Liste des codes postaux de la commune
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                      type: object
                    departement:
                      description: Informations sur le département
                      properties:
                        code:
                          type: string
                          example: '75'
                        nom:
                          type: string
                          example: Paris
                      type: object
                    region:
                      description: Informations sur la région
                      properties:
                        code:
                          type: string
                          example: '11'
                        nom:
                          type: string
                          example: Île-de-France
                      type: object
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    contour:
                      description: >-
                        Contour géographique de la section (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante de la section (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - code: AB
                    superficie: 523456.78
                    perimetre: 3210.45
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                    departement:
                      code: '75'
                      nom: Paris
                    region:
                      code: '11'
                      nom: Île-de-France
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de la section cadastrale (Point si
                            geometrie=centre, Polygon/MultiPolygon si
                            geometrie=contour, Polygon si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            code:
                              description: Code de la section cadastrale
                              type: string
                              example: AB
                            superficie:
                              description: Superficie de la section en m²
                              type: number
                              example: 523456.78
                            perimetre:
                              description: Périmètre de la section en m
                              type: number
                              example: 3210.45
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  type: string
                                  example: '75056'
                                nom:
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: Liste des codes postaux de la commune
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                              type: object
                            departement:
                              description: Informations sur le département
                              properties:
                                code:
                                  type: string
                                  example: '75'
                                nom:
                                  type: string
                                  example: Paris
                              type: object
                            region:
                              description: Informations sur la région
                              properties:
                                code:
                                  type: string
                                  example: '11'
                                nom:
                                  type: string
                                  example: Île-de-France
                              type: object
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.3522
                                    - 48.8566
                              type: object
                            bbox:
                              description: Boîte englobante de la section (GeoJSON Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 2.32
                              - 48.85
                            - - 2.37
                              - 48.85
                            - - 2.37
                              - 48.87
                            - - 2.32
                              - 48.87
                            - - 2.32
                              - 48.85
                      properties:
                        code: AB
                        superficie: 523456.78
                        perimetre: 3210.45
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                        departement:
                          code: '75'
                          nom: Paris
                        region:
                          code: '11'
                          nom: Île-de-France
                        centre:
                          type: Point
                          coordinates:
                            - 2.3522
                            - 48.8566
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.32
                                - 48.85
                              - - 2.37
                                - 48.85
                              - - 2.37
                                - 48.87
                              - - 2.32
                                - 48.87
                              - - 2.32
                                - 48.85
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune section trouvée
      security:
        - bearer:
            - '*'
  /api/v1/quartiers:
    get:
      tags:
        - Données territoriales
      summary: Rechercher des quartiers (IRIS)
      description: >-
        Permet de rechercher des quartiers IRIS par différents critères :
        coordonnées GPS, code IRIS, nom, type d'IRIS, code postal, code INSEE de
        la commune, code département, code région. Les résultats peuvent être
        retournés au format JSON ou GeoJSON.
      operationId: getDistricts
      parameters:
        - name: code
          in: query
          description: 'Code IRIS du quartier (ex: 751012316).'
          required: false
          schema:
            type: string
            example: ''
        - name: nom
          in: query
          description: Nom du quartier (recherche par similarité).
          required: false
          schema:
            type: string
            example: ''
        - name: type
          in: query
          description: >-
            Type d'IRIS du quartier (classification INSEE).


            **Liste complète des types possibles :**


            - `H` - IRIS d'habitat : Zone résidentielle homogène, en général
            entre 1 800 et 5 000 habitants, avec des limites appuyées sur les
            grandes coupures urbaines

            - `A` - IRIS d'activité : Regroupe au moins 1 000 salariés et compte
            au moins deux fois plus d'emplois salariés que de population
            résidente

            - `D` - IRIS divers : Grandes zones spécifiques peu habitées comme
            parcs de loisirs, zones portuaires ou forêts

            - `Z` - Pas d'IRIS : Code utilisé pour les communes non découpées en
            IRIS
          required: false
          schema:
            type: string
            enum:
              - H
              - A
              - D
              - Z
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres) pour filtrer les quartiers.
          required: false
          schema:
            type: string
            example: '75056'
        - name: code_postal
          in: query
          description: Code postal (5 chiffres) pour filtrer les quartiers.
          required: false
          schema:
            type: string
            example: ''
        - name: code_departement
          in: query
          description: Code INSEE du département (2 chiffres) pour filtrer les quartiers.
          required: false
          schema:
            type: string
            example: ''
        - name: code_region
          in: query
          description: Code INSEE de la région (2 chiffres) pour filtrer les quartiers.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher le quartier
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher le quartier
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=code,nom,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - code
                - nom
                - type
                - municipalite
                - departement
                - region
                - superficie
                - perimetre
                - centre
                - contour
                - bbox
            default:
              - code
              - nom
              - superficie
              - centre
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: code
            enum:
              - code
              - nom
              - superficie
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 20.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 20
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    code:
                      description: Code IRIS du quartier
                      type: string
                      example: '751012316'
                    nom:
                      description: Nom du quartier
                      type: string
                      example: Montparnasse
                    type:
                      description: >-
                        Type de quartier (H=Habitat, A=Activité, D=Divers, Z=Non
                        découpé)
                      type: string
                      example: H
                    superficie:
                      description: Superficie du quartier en m²
                      type: number
                      example: 125000.5
                    perimetre:
                      description: Périmètre du quartier en m
                      type: number
                      example: 1450.75
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          type: string
                          example: '75056'
                        nom:
                          type: string
                          example: Paris
                        codes_postaux:
                          description: Liste des codes postaux de la commune
                          type: array
                          items:
                            type: string
                          example:
                            - '75014'
                      type: object
                    departement:
                      description: Informations sur le département
                      properties:
                        code:
                          type: string
                          example: '75'
                        nom:
                          type: string
                          example: Paris
                      type: object
                    region:
                      description: Informations sur la région
                      properties:
                        code:
                          type: string
                          example: '11'
                        nom:
                          type: string
                          example: Île-de-France
                      type: object
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.32
                            - 48.84
                      type: object
                    contour:
                      description: >-
                        Contour géographique du quartier (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante du quartier (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - code: '751012316'
                    nom: Montparnasse
                    type: H
                    superficie: 125000.5
                    perimetre: 1450.75
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75014'
                    departement:
                      code: '75'
                      nom: Paris
                    region:
                      code: '11'
                      nom: Île-de-France
                    centre:
                      type: Point
                      coordinates:
                        - 2.32
                        - 48.84
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.31
                            - 48.835
                          - - 2.33
                            - 48.835
                          - - 2.33
                            - 48.845
                          - - 2.31
                            - 48.845
                          - - 2.31
                            - 48.835
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.31
                            - 48.835
                          - - 2.33
                            - 48.835
                          - - 2.33
                            - 48.845
                          - - 2.31
                            - 48.845
                          - - 2.31
                            - 48.835
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie du quartier (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            code:
                              description: Code IRIS du quartier
                              type: string
                              example: '751012316'
                            nom:
                              description: Nom du quartier
                              type: string
                              example: Montparnasse
                            type:
                              description: >-
                                Type de quartier (H=Habitat, A=Activité,
                                D=Divers, Z=Non découpé)
                              type: string
                              example: H
                            superficie:
                              description: Superficie du quartier en m²
                              type: number
                              example: 125000.5
                            perimetre:
                              description: Périmètre du quartier en m
                              type: number
                              example: 1450.75
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  type: string
                                  example: '75056'
                                nom:
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: Liste des codes postaux de la commune
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75014'
                              type: object
                            departement:
                              description: Informations sur le département
                              properties:
                                code:
                                  type: string
                                  example: '75'
                                nom:
                                  type: string
                                  example: Paris
                              type: object
                            region:
                              description: Informations sur la région
                              properties:
                                code:
                                  type: string
                                  example: '11'
                                nom:
                                  type: string
                                  example: Île-de-France
                              type: object
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.32
                                    - 48.84
                              type: object
                            bbox:
                              description: Boîte englobante du quartier (GeoJSON Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 2.31
                              - 48.835
                            - - 2.33
                              - 48.835
                            - - 2.33
                              - 48.845
                            - - 2.31
                              - 48.845
                            - - 2.31
                              - 48.835
                      properties:
                        code: '751012316'
                        nom: Montparnasse
                        type: H
                        superficie: 125000.5
                        perimetre: 1450.75
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75014'
                        departement:
                          code: '75'
                          nom: Paris
                        region:
                          code: '11'
                          nom: Île-de-France
                        centre:
                          type: Point
                          coordinates:
                            - 2.32
                            - 48.84
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.31
                                - 48.835
                              - - 2.33
                                - 48.835
                              - - 2.33
                                - 48.845
                              - - 2.31
                                - 48.845
                              - - 2.31
                                - 48.835
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun quartier trouvé
      security:
        - bearer:
            - '*'
  /api/v1/epci:
    get:
      tags:
        - Données territoriales
      summary: >-
        Rechercher des EPCI (Établissements publics de coopération
        intercommunale)
      description: >-
        Permet de rechercher des EPCI par différents critères : coordonnées GPS,
        code SIREN, nom, nature. Les résultats peuvent être retournés au format
        JSON ou GeoJSON.
      operationId: getEpcis
      parameters:
        - name: code
          in: query
          description: Code SIREN de l'EPCI (9 chiffres).
          required: false
          schema:
            type: string
            example: ''
        - name: nom
          in: query
          description: Nom de l'EPCI (recherche par similarité).
          required: false
          schema:
            type: string
            example: Métropole du Grand Paris
        - name: nature
          in: query
          description: >-
            Nature juridique de l'EPCI (classification INSEE). Accepte plusieurs
            valeurs séparées par des virgules (ex: '1,3').


            **Liste complète des natures possibles :**


            - `0` - Indéfini : Nature juridique non précisée ou en cours de
            définition

            - `1` - Métropole : EPCI à fiscalité propre regroupant plus de 400
            000 habitants

            - `2` - Communauté urbaine : EPCI à fiscalité propre regroupant plus
            de 250 000 habitants

            - `3` - Communauté d'agglomération : EPCI à fiscalité propre
            regroupant plus de 50 000 habitants

            - `4` - Communauté de communes : EPCI à fiscalité propre regroupant
            plusieurs communes

            - `5` - Etablissement public territorial (EPT) : Structure
            spécifique de la Métropole du Grand Paris
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher l'EPCI
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher l'EPCI
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=code,nom,nature
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - code
                - nom
                - nature
                - superficie
                - perimetre
                - centre
                - contour
                - bbox
            default:
              - code
              - nom
              - nature
              - superficie
              - centre
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: nom
            enum:
              - code
              - nom
              - nature
              - superficie
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 20.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 20
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    code:
                      description: Code SIREN de l'EPCI
                      type: string
                      example: '200054781'
                    nom:
                      description: Nom officiel de l'EPCI
                      type: string
                      example: Métropole du Grand Paris
                    nature:
                      description: Nature juridique de l'EPCI
                      type: string
                      example: Métropole
                    superficie:
                      description: Superficie de l'EPCI en m²
                      type: number
                      example: 814000000
                    perimetre:
                      description: Périmètre de l'EPCI en m
                      type: number
                      example: 156000
                    centre:
                      description: Coordonnées du centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    contour:
                      description: >-
                        Contour géographique de l'EPCI (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone
                          type: array
                          items:
                            type: number
                      type: object
                    bbox:
                      description: Boîte englobante de l'EPCI (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          description: Tableau de coordonnées du polygone bbox
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - code: '200054781'
                    nom: Métropole du Grand Paris
                    nature: Métropole
                    superficie: 814000000
                    perimetre: 156000
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.2241
                            - 48.8155
                          - - 2.4699
                            - 48.8155
                          - - 2.4699
                            - 48.9022
                          - - 2.2241
                            - 48.9022
                          - - 2.2241
                            - 48.8155
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.2241
                            - 48.8155
                          - - 2.4699
                            - 48.8155
                          - - 2.4699
                            - 48.9022
                          - - 2.2241
                            - 48.9022
                          - - 2.2241
                            - 48.8155
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de l'EPCI (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Polygon
                            coordinates:
                              description: Tableau de coordonnées
                              type: array
                              items:
                                type: number
                          type: object
                        properties:
                          properties:
                            code:
                              description: Code SIREN de l'EPCI
                              type: string
                              example: '200054781'
                            nom:
                              description: Nom officiel de l'EPCI
                              type: string
                              example: Métropole du Grand Paris
                            nature:
                              description: Nature juridique de l'EPCI
                              type: string
                              example: Métropole
                            superficie:
                              description: Superficie de l'EPCI en m²
                              type: number
                              example: 814000000
                            perimetre:
                              description: Périmètre de l'EPCI en m
                              type: number
                              example: 156000
                            centre:
                              description: >-
                                Coordonnées du centre géographique (GeoJSON
                                Point)
                              properties:
                                type:
                                  type: string
                                  example: Point
                                coordinates:
                                  type: array
                                  items:
                                    type: number
                                  example:
                                    - 2.3522
                                    - 48.8566
                              type: object
                            bbox:
                              description: Boîte englobante de l'EPCI (GeoJSON Polygon)
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  description: Tableau de coordonnées du polygone bbox
                                  type: array
                                  items:
                                    type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Polygon
                        coordinates:
                          - - - 2.2241
                              - 48.8155
                            - - 2.4699
                              - 48.8155
                            - - 2.4699
                              - 48.9022
                            - - 2.2241
                              - 48.9022
                            - - 2.2241
                              - 48.8155
                      properties:
                        code: '200054781'
                        nom: Métropole du Grand Paris
                        nature: Métropole
                        superficie: 814000000
                        perimetre: 156000
                        centre:
                          type: Point
                          coordinates:
                            - 2.3522
                            - 48.8566
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.2241
                                - 48.8155
                              - - 2.4699
                                - 48.8155
                              - - 2.4699
                                - 48.9022
                              - - 2.2241
                                - 48.9022
                              - - 2.2241
                                - 48.8155
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun EPCI trouvé
      security:
        - bearer:
            - '*'
  /api/v1/dpes:
    get:
      tags:
        - Données foncières & immobilières
      summary: Rechercher des Diagnostics de Performance Énergétique (DPE)
      description: >-
        Permet de rechercher des DPE par différents critères : coordonnées GPS,
        code postal, étiquettes énergétiques, type de bâtiment, année de
        construction, consommation énergétique, codes INSEE. Les résultats
        peuvent être retournés au format JSON ou GeoJSON avec pagination par
        curseur.
      operationId: getDpes
      parameters:
        - name: numero_dpe
          in: query
          description: >-
            Numéro unique du DPE. Accepte plusieurs valeurs séparées par des
            virgules (ex: '2312345678901,2312345678902').
          required: false
          schema:
            type: string
            example: ''
        - name: type_dpe
          in: query
          description: >-
            Type de DPE. Accepte plusieurs valeurs séparées par des virgules
            (ex: '0,1' ou '0,1,2').


            **Liste complète des types possibles :**


            - `0` - Existant : DPE pour un logement existant

            - `1` - Neuf : DPE pour une construction neuve

            - `2` - Tertiaire : DPE pour un bâtiment tertiaire
          required: false
          schema:
            type: integer
            example: ''
        - name: etiquette_dpe
          in: query
          description: >-
            Étiquette de performance énergétique. Accepte plusieurs valeurs
            séparées par des virgules (ex: 'A,B,C').


            **Liste complète des étiquettes possibles :**


            - `A` - Très performant : Consommation ≤ 70 kWh/m²/an (logements
            neufs ou très bien isolés)

            - `B` - Performant : Consommation entre 71 et 110 kWh/m²/an
            (logements bien isolés)

            - `C` - Assez performant : Consommation entre 111 et 180 kWh/m²/an
            (logements correctement isolés)

            - `D` - Moyennement performant : Consommation entre 181 et 250
            kWh/m²/an (isolation moyenne)

            - `E` - Peu performant : Consommation entre 251 et 330 kWh/m²/an
            (isolation faible)

            - `F` - Très peu performant : Consommation entre 331 et 420
            kWh/m²/an (isolation très faible)

            - `G` - Extrêmement peu performant : Consommation > 420 kWh/m²/an
            (passoire thermique)
          required: false
          schema:
            type: string
            example: ''
        - name: etiquette_ges
          in: query
          description: >-
            Étiquette d'émission de gaz à effet de serre (GES). Accepte
            plusieurs valeurs séparées par des virgules (ex: 'D,E,F').


            **Liste complète des étiquettes possibles :**


            - `A` - Très faible émission : Émission ≤ 6 kg CO2/m²/an (logements
            très écologiques)

            - `B` - Faible émission : Émission entre 7 et 11 kg CO2/m²/an
            (logements écologiques)

            - `C` - Émission modérée : Émission entre 12 et 30 kg CO2/m²/an
            (logements assez écologiques)

            - `D` - Émission moyenne : Émission entre 31 et 50 kg CO2/m²/an
            (impact environnemental moyen)

            - `E` - Émission importante : Émission entre 51 et 70 kg CO2/m²/an
            (impact environnemental élevé)

            - `F` - Émission très importante : Émission entre 71 et 100 kg
            CO2/m²/an (impact environnemental très élevé)

            - `G` - Émission extrêmement importante : Émission > 100 kg
            CO2/m²/an (logement très polluant)
          required: false
          schema:
            type: string
            example: ''
        - name: type_batiment
          in: query
          description: >-
            Type de bâtiment. Accepte plusieurs valeurs séparées par des
            virgules (ex: 'appartement,maison').


            **Liste complète des types possibles :**


            - `appartement` - Appartement : Logement dans un immeuble collectif

            - `maison` - Maison : Logement individuel

            - `immeuble` - Immeuble : Bâtiment collectif complet
          required: false
          schema:
            type: string
            example: ''
        - name: bati_type
          in: query
          description: >-
            Type de bâti calculé. Accepte plusieurs valeurs séparées par des
            virgules (ex: '1,7,13').


            **Liste complète des types possibles :**


            **Global :**

            - `0` - Bâtiment : Maison/Appartement/Autres


            **Maisons :**

            - `1` - Maison

            - `2` - Maison 1 pièce/studio

            - `3` - Maison 2 pièces

            - `4` - Maison 3 pièces

            - `5` - Maison 4 pièces

            - `6` - Maison 5 pièces et plus


            **Appartements :**

            - `7` - Appartement

            - `8` - Appartement 1 pièce/studio

            - `9` - Appartement 2 pièces

            - `10` - Appartement 3 pièces

            - `11` - Appartement 4 pièces

            - `12` - Appartement 5 pièces et plus


            **Bâtiments et locaux :**

            - `13` - Immeuble : Bâtiment/Immeuble

            - `14` - Activité : Local d'activités

            - `15` - Dépendance


            **Terrains :**

            - `16` - Terrain à bâtir

            - `17` - Terrain
          required: false
          schema:
            type: string
            example: ''
        - name: date_etablissement_min
          in: query
          description: Date minimale d'établissement du DPE (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_etablissement_max
          in: query
          description: Date maximale d'établissement du DPE (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_reception_dpe_min
          in: query
          description: Date minimale de réception du DPE (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_reception_dpe_max
          in: query
          description: Date maximale de réception du DPE (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: annee_construction_min
          in: query
          description: Année minimale de construction du bâtiment.
          required: false
          schema:
            type: integer
            example: ''
        - name: annee_construction_max
          in: query
          description: Année maximale de construction du bâtiment.
          required: false
          schema:
            type: integer
            example: ''
        - name: surface_habitable_min
          in: query
          description: Surface habitable minimale en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_habitable_max
          in: query
          description: Surface habitable maximale en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: conso_energie_min
          in: query
          description: Consommation énergétique minimale en kWh/m²/an.
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: conso_energie_max
          in: query
          description: Consommation énergétique maximale en kWh/m²/an.
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: emission_ges_min
          in: query
          description: Émission de GES minimale en kg CO2/m²/an.
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: emission_ges_max
          in: query
          description: Émission de GES maximale en kg CO2/m²/an.
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: cout_total_min
          in: query
          description: Coût total minimal en € par an
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: cout_total_max
          in: query
          description: Coût total maximal en € par an
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: code_postal
          in: query
          description: Code postal (5 chiffres) pour filtrer les DPE.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher les DPE liés à
            une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher les DPE liés à
            une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: code_parcelle
          in: query
          description: >-
            Code cadastral de la parcelle (Identifiant Cadastral - 14
            caractères). Accepte plusieurs valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: '75056'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Note : le champ 'parcelles'
            est limité à un maximum de 10 parcelles par DPE. Exemple :
            champs=numero_dpe,etiquette_dpe,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - numero_dpe
                - type_dpe
                - date_etablissement
                - date_reception
                - date_visite
                - date_fin_validite
                - version
                - etiquette_dpe
                - etiquette_ges
                - adresse
                - type_batiment
                - bati_type
                - annee_construction
                - periode_construction
                - surface_habitable
                - nombre_niveau_logement
                - hauteur_sous_plafond
                - conso_energie
                - conso_chauffage
                - conso_ecs
                - conso_refroidissement
                - conso_eclairage
                - emission_ges
                - emission_ges_chauffage
                - emission_ges_ecs
                - cout_total
                - cout_chauffage
                - cout_ecs
                - parcelles
                - municipalite
                - centre
            default:
              - numero_dpe
              - date_reception
              - etiquette_dpe
              - etiquette_ges
              - type_batiment
              - bati_type
              - annee_construction
              - surface_habitable
              - conso_energie
              - emission_ges
              - cout_total
              - municipalite
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: date_reception
            enum:
              - numero_dpe
              - date_etablissement
              - date_reception
              - date_visite
              - etiquette_dpe
              - etiquette_ges
              - annee_construction
              - surface_habitable
              - conso_energie
              - emission_ges
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: desc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON. Pour les DPE, seul 'centre' est disponible (point du DPE),
            car un DPE n'a pas de géométrie propre. Ce paramètre est ignoré en
            format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    numero_dpe:
                      description: Numéro unique du DPE
                      type: string
                      example: '2312345678901'
                    type_dpe:
                      description: 'Type de DPE : 0=Existant, 1=Neuf, 2=Tertiaire'
                      type: integer
                      example: '0'
                    date_etablissement:
                      description: Date d'établissement du DPE
                      type: string
                      format: date
                      example: '2023-06-15'
                    date_reception:
                      description: Date de réception du DPE
                      type: string
                      format: date
                      example: '2023-06-16'
                    date_visite:
                      description: Date de visite
                      type: string
                      format: date
                      example: '2023-06-10'
                    date_fin_validite:
                      description: Date de fin de validité
                      type: string
                      format: date
                      example: '2033-06-15'
                    version:
                      description: Version du DPE
                      type: string
                      example: '2.4'
                    etiquette_dpe:
                      description: Étiquette énergétique (A à G)
                      type: string
                      example: C
                    etiquette_ges:
                      description: Étiquette GES (A à G)
                      type: string
                      example: D
                    adresse:
                      description: Adresse complète du bien
                      type: string
                      example: 10 rue de la République 75001 Paris
                    type_batiment:
                      description: Type de bâtiment
                      type: string
                      example: appartement
                    bati_type:
                      description: Type de bâti calculé (0-17)
                      type: integer
                      example: 7
                    annee_construction:
                      description: Année de construction
                      type: integer
                      example: 1980
                    periode_construction:
                      description: Période de construction
                      type: string
                      example: 1971-1980
                    surface_habitable:
                      description: Surface habitable en m²
                      type: number
                      example: 75.5
                    nombre_niveau_logement:
                      description: Nombre de niveaux du logement
                      type: integer
                      example: 1
                    hauteur_sous_plafond:
                      description: Hauteur sous plafond en m
                      type: number
                      example: 2.5
                    conso_energie:
                      description: Consommation énergétique totale en kWh/m²/an
                      type: number
                      example: 185.4
                    conso_chauffage:
                      description: Consommation chauffage en kWh/m²/an
                      type: number
                      example: 150.2
                    conso_ecs:
                      description: Consommation eau chaude sanitaire en kWh/m²/an
                      type: number
                      example: 25.3
                    conso_refroidissement:
                      description: Consommation refroidissement en kWh/m²/an
                      type: number
                      example: 5.9
                    conso_eclairage:
                      description: Consommation éclairage en kWh/m²/an
                      type: number
                      example: 4
                    emission_ges:
                      description: Émission totale de GES en kg CO2/m²/an
                      type: number
                      example: 32.8
                    emission_ges_chauffage:
                      description: Émission GES chauffage en kg CO2/m²/an
                      type: number
                      example: 28.5
                    emission_ges_ecs:
                      description: Émission GES eau chaude sanitaire en kg CO2/m²/an
                      type: number
                      example: 4.3
                    cout_total:
                      description: Coût total annuel en €
                      type: number
                      example: 1450
                    cout_chauffage:
                      description: Coût annuel chauffage en €
                      type: number
                      example: 1180
                    cout_ecs:
                      description: Coût annuel eau chaude sanitaire en €
                      type: number
                      example: 270
                    parcelles:
                      description: Liste des parcelles cadastrales
                      type: array
                      items:
                        properties:
                          code:
                            type: string
                          section:
                            type: string
                          numero:
                            type: string
                          superficie:
                            type: number
                        type: object
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          type: string
                        nom:
                          type: string
                        codes_postaux:
                          type: array
                          items:
                            type: string
                      type: object
                    centre:
                      description: Géométrie GeoJSON du point du DPE
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - numero_dpe: '2312345678901'
                    type_dpe: 0
                    date_etablissement: '2023-06-15'
                    date_reception: '2023-06-16'
                    date_visite: '2023-06-10'
                    date_fin_validite: '2033-06-15'
                    version: '2.4'
                    etiquette_dpe: C
                    etiquette_ges: D
                    adresse: 10 rue de la République 75001 Paris
                    type_batiment: appartement
                    bati_type: 7
                    annee_construction: 1980
                    periode_construction: 1971-1980
                    surface_habitable: 75.5
                    nombre_niveau_logement: 1
                    hauteur_sous_plafond: 2.5
                    conso_energie: 185.4
                    conso_chauffage: 150.2
                    conso_ecs: 25.3
                    conso_refroidissement: 5.9
                    conso_eclairage: 4
                    emission_ges: 32.8
                    emission_ges_chauffage: 28.5
                    emission_ges_ecs: 4.3
                    cout_total: 1450
                    cout_chauffage: 1180
                    cout_ecs: 270
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 450.5
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: Géométrie du DPE (Point)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            numero_dpe:
                              description: Numéro unique du DPE
                              type: string
                              example: '2312345678901'
                            type_dpe:
                              description: 'Type de DPE : 0=Existant, 1=Neuf, 2=Tertiaire'
                              type: integer
                              example: '0'
                            date_etablissement:
                              description: Date d'établissement du DPE
                              type: string
                              format: date
                              example: '2023-06-15'
                            date_reception:
                              description: Date de réception du DPE
                              type: string
                              format: date
                              example: '2023-06-16'
                            date_visite:
                              description: Date de visite
                              type: string
                              format: date
                              example: '2023-06-10'
                            date_fin_validite:
                              description: Date de fin de validité
                              type: string
                              format: date
                              example: '2033-06-15'
                            version:
                              description: Version du DPE
                              type: string
                              example: '2.4'
                            etiquette_dpe:
                              description: Étiquette énergétique (A à G)
                              type: string
                              example: C
                            etiquette_ges:
                              description: Étiquette GES (A à G)
                              type: string
                              example: D
                            adresse:
                              description: Adresse complète du bien
                              type: string
                              example: 10 rue de la République 75001 Paris
                            type_batiment:
                              description: Type de bâtiment
                              type: string
                              example: appartement
                            bati_type:
                              description: Type de bâti calculé (0-17)
                              type: integer
                              example: 7
                            annee_construction:
                              description: Année de construction
                              type: integer
                              example: 1980
                            periode_construction:
                              description: Période de construction
                              type: string
                              example: 1971-1980
                            surface_habitable:
                              description: Surface habitable en m²
                              type: number
                              example: 75.5
                            nombre_niveau_logement:
                              description: Nombre de niveaux du logement
                              type: integer
                              example: 1
                            hauteur_sous_plafond:
                              description: Hauteur sous plafond en m
                              type: number
                              example: 2.5
                            conso_energie:
                              description: Consommation énergétique totale en kWh/m²/an
                              type: number
                              example: 185.4
                            conso_chauffage:
                              description: Consommation chauffage en kWh/m²/an
                              type: number
                              example: 150.2
                            conso_ecs:
                              description: Consommation eau chaude sanitaire en kWh/m²/an
                              type: number
                              example: 25.3
                            conso_refroidissement:
                              description: Consommation refroidissement en kWh/m²/an
                              type: number
                              example: 5.9
                            conso_eclairage:
                              description: Consommation éclairage en kWh/m²/an
                              type: number
                              example: 4
                            emission_ges:
                              description: Émission totale de GES en kg CO2/m²/an
                              type: number
                              example: 32.8
                            emission_ges_chauffage:
                              description: Émission GES chauffage en kg CO2/m²/an
                              type: number
                              example: 28.5
                            emission_ges_ecs:
                              description: >-
                                Émission GES eau chaude sanitaire en kg
                                CO2/m²/an
                              type: number
                              example: 4.3
                            cout_total:
                              description: Coût total annuel en €
                              type: number
                              example: 1450
                            cout_chauffage:
                              description: Coût annuel chauffage en €
                              type: number
                              example: 1180
                            cout_ecs:
                              description: Coût annuel eau chaude sanitaire en €
                              type: number
                              example: 270
                            parcelles:
                              description: Liste des parcelles cadastrales
                              type: array
                              items:
                                properties:
                                  code:
                                    type: string
                                  section:
                                    type: string
                                  numero:
                                    type: string
                                  superficie:
                                    type: number
                                type: object
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  type: string
                                nom:
                                  type: string
                                codes_postaux:
                                  type: array
                                  items:
                                    type: string
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        numero_dpe: '2312345678901'
                        type_dpe: '0'
                        date_etablissement: '2023-06-15'
                        date_reception: '2023-06-16'
                        date_visite: '2023-06-10'
                        date_fin_validite: '2033-06-15'
                        version: '2.4'
                        etiquette_dpe: C
                        etiquette_ges: D
                        adresse: 10 rue de la République 75001 Paris
                        type_batiment: appartement
                        bati_type: 7
                        annee_construction: 1980
                        periode_construction: 1971-1980
                        surface_habitable: 75.5
                        nombre_niveau_logement: 1
                        hauteur_sous_plafond: 2.5
                        conso_energie: 185.4
                        conso_chauffage: 150.2
                        conso_ecs: 25.3
                        conso_refroidissement: 5.9
                        conso_eclairage: 4
                        emission_ges: 32.8
                        emission_ges_chauffage: 28.5
                        emission_ges_ecs: 4.3
                        cout_total: 1450
                        cout_chauffage: 1180
                        cout_ecs: 270
                        parcelles:
                          - code: 750010001AB0001
                            section: AB
                            numero: '0001'
                            superficie: 450.5
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75003'
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun DPE trouvé
      security:
        - bearer:
            - '*'
  /api/v1/dvfs:
    get:
      tags:
        - Données foncières & immobilières
      summary: Rechercher des transactions immobilières (Demandes de Valeurs Foncières)
      description: >-
        Permet de rechercher des transactions immobilières (DVF) par différents
        critères : coordonnées GPS, code postal, type de bien, valeur foncière,
        surfaces, dates de mutation, codes INSEE. Les résultats peuvent être
        retournés au format JSON ou GeoJSON avec pagination par curseur.
      operationId: getDvfs
      parameters:
        - name: code
          in: query
          description: >-
            Identifiant interne unique de la transaction DVF. Accepte plusieurs
            valeurs séparées par des virgules (ex: '2023-12345,2023-12346').
          required: false
          schema:
            type: string
            example: ''
        - name: code_type_bien
          in: query
          description: >-
            Code du type de bien vendu. Accepte plusieurs valeurs séparées par
            des virgules (ex: '111,121,131').


            **Liste complète des codes possibles :**


            **Activité et indéterminé :**

            - `14` - ACTIVITE

            - `101` - BATI - INDETERMINE : Vefa sans descriptif

            - `102` - BATI - INDETERMINE : Vente avec volume(s)


            **Maisons :**

            - `110` - MAISON - INDETERMINEE

            - `111` - UNE MAISON

            - `112` - DES MAISONS


            **Appartements :**

            - `120` - APPARTEMENT INDETERMINE

            - `121` - UN APPARTEMENT

            - `122` - DEUX APPARTEMENTS


            **Dépendances :**

            - `131` - UNE DEPENDANCE

            - `132` - DES DEPENDANCES


            **Bâti mixte :**

            - `151` - BATI MIXTE - LOGEMENTS

            - `152` - BATI MIXTE - LOGEMENT/ACTIVITE


            **Terrains non bâtis :**

            - `20` - TERRAIN NON BATIS INDETERMINE

            - `21` - TERRAIN DE TYPE TAB (Terrain à bâtir)


            **Terrains artificialisés :**

            - `221` - TERRAIN D'AGREMENT

            - `222` - TERRAIN D'EXTRACTION

            - `223` - TERRAIN DE TYPE RESEAU

            - `229` - TERRAIN ARTIFICIALISE MIXTE


            **Terrains naturels :**

            - `232` - TERRAIN FORESTIER

            - `233` - TERRAIN LANDES ET EAUX

            - `239` - TERRAIN NATUREL MIXTE


            **Terrains agricoles :**

            - `2311` - TERRAIN VITICOLE

            - `2312` - TERRAIN VERGER

            - `2313` - TERRAIN DE TYPE TERRE ET PRE

            - `2319` - TERRAIN AGRICOLE MIXTE
          required: false
          schema:
            type: string
            example: ''
        - name: valeur_fonciere_min
          in: query
          description: Valeur foncière minimale de la transaction en euros.
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: valeur_fonciere_max
          in: query
          description: Valeur foncière maximale de la transaction en euros.
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_habitable_min
          in: query
          description: Surface habitable minimale en m² (calculée selon le type de bien).
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_habitable_max
          in: query
          description: Surface habitable maximale en m² (calculée selon le type de bien).
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_terrain_min
          in: query
          description: Surface de terrain minimale en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_terrain_max
          in: query
          description: Surface de terrain maximale en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: date_mutation_min
          in: query
          description: >-
            Date de mutation minimale (format AAAA-MM-JJ) - date de signature de
            l'acte de vente.
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_mutation_max
          in: query
          description: >-
            Date de mutation maximale (format AAAA-MM-JJ) - date de signature de
            l'acte de vente.
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: nature_mutation
          in: query
          description: >-
            Nature de la mutation. Accepte plusieurs valeurs séparées par des
            virgules (ex: '3,4').


            **Liste complète des natures possibles :**


            - `0` - Adjudication : Vente aux enchères publiques

            - `1` - Echange : Échange de biens immobiliers

            - `2` - Expropriation : Acquisition forcée pour cause d'utilité
            publique

            - `3` - Vente : Vente classique

            - `4` - Vente en l'état futur d'achèvement : Vente VEFA (logement
            vendu avant achèvement des travaux)

            - `5` - Vente terrain à bâtir : Vente d'un terrain constructible
          required: false
          schema:
            type: string
            example: ''
        - name: vefa
          in: query
          description: Indicateur VEFA (Vente en l'État Futur d'Achèvement).
          required: false
          schema:
            type: boolean
        - name: nb_lots_min
          in: query
          description: Nombre minimal de lots dans la mutation
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lots_max
          in: query
          description: Nombre maximal de lots dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_parcelles_min
          in: query
          description: Nombre minimal de parcelles dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_parcelles_max
          in: query
          description: Nombre maximal de parcelles dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_locaux_min
          in: query
          description: Nombre minimal de locaux ayant muté.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_locaux_max
          in: query
          description: Nombre maximal de locaux ayant muté.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_maisons_min
          in: query
          description: Nombre minimal de maisons dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_maisons_max
          in: query
          description: Nombre maximal de maisons dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_appartements_min
          in: query
          description: Nombre minimal d'appartements dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_appartements_max
          in: query
          description: Nombre maximal d'appartements dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_dependances_min
          in: query
          description: Nombre minimal de dépendances dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_dependances_max
          in: query
          description: Nombre maximal de dépendances dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_locaux_activite_min
          in: query
          description: Nombre minimal de locaux d'activité dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_locaux_activite_max
          in: query
          description: Nombre maximal de locaux d'activité dans la mutation.
          required: false
          schema:
            type: integer
            example: ''
        - name: surface_batie_min
          in: query
          description: Surface bâtie totale minimale en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_batie_max
          in: query
          description: Surface bâtie totale maximale en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_maisons_min
          in: query
          description: Surface minimale des maisons en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_maisons_max
          in: query
          description: Surface maximale des maisons en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_appartements_min
          in: query
          description: Surface minimale des appartements en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_appartements_max
          in: query
          description: Surface maximale des appartements en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_activite_min
          in: query
          description: Surface minimale des locaux d'activité en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: surface_activite_max
          in: query
          description: Surface maximale des locaux d'activité en m².
          required: false
          schema:
            type: number
            format: float
            example: ''
        - name: bati_type
          in: query
          description: >-
            Type de bâti calculé. Accepte plusieurs valeurs séparées par des
            virgules (ex: '1,7,13').


            **Liste complète des types possibles :**


            **Global :**

            - `0` - Bâtiment : Maison/Appartement/Autres


            **Maisons :**

            - `1` - Maison

            - `2` - Maison 1 pièce/studio

            - `3` - Maison 2 pièces

            - `4` - Maison 3 pièces

            - `5` - Maison 4 pièces

            - `6` - Maison 5 pièces et plus


            **Appartements :**

            - `7` - Appartement

            - `8` - Appartement 1 pièce/studio

            - `9` - Appartement 2 pièces

            - `10` - Appartement 3 pièces

            - `11` - Appartement 4 pièces

            - `12` - Appartement 5 pièces et plus


            **Bâtiments et locaux :**

            - `13` - Immeuble : Bâtiment/Immeuble

            - `14` - Activité : Local d'activités

            - `15` - Dépendance


            **Terrains :**

            - `16` - Terrain à bâtir

            - `17` - Terrain
          required: false
          schema:
            type: string
            example: ''
        - name: code_postal
          in: query
          description: Code postal (5 chiffres) pour filtrer les transactions.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher les
            transactions liées à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher les
            transactions liées à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: code_parcelle
          in: query
          description: >-
            Code cadastral de la parcelle (Identifiant Cadastral - 14
            caractères). Accepte plusieurs valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: '75056'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Note : le champ 'parcelles'
            est limité à un maximum de 10 parcelles par DVF. Exemple :
            champs=id_mutation,date_mutation,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - id_mutation
                - date_mutation
                - nature_mutation
                - valeur_fonciere
                - vefa
                - code_type_bien
                - libelle_type
                - bati_type
                - nb_dispositions
                - nb_lots
                - nb_parcelles
                - nb_parcelles_mutees
                - nb_locaux
                - nb_maisons
                - nb_appartements
                - nb_dependances
                - nb_locaux_activite
                - surface_terrain
                - surface_batie
                - surface_maisons
                - surface_appartements
                - surface_activite
                - parcelles
                - municipalite
                - centre
            default:
              - id_mutation
              - date_mutation
              - nature_mutation
              - bati_type
              - surface_batie
              - valeur_fonciere
              - municipalite
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: date_mutation
            enum:
              - id_mutation
              - date_mutation
              - nature_mutation
              - bati_type
              - code_type_bien
              - valeur_fonciere
              - surface_batie
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: desc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON. Pour les DVF, seul 'centre' est disponible (point central
            de la parcelle), car une transaction DVF n'a pas de géométrie
            propre. Ce paramètre est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    id_mutation:
                      description: Identifiant unique de la mutation
                      type: string
                      example: 2023-12345
                    date_mutation:
                      description: Date de signature de l'acte
                      type: string
                      format: date
                      example: '2023-06-15'
                    nature_mutation:
                      description: Nature de la mutation
                      type: string
                      example: Vente
                    valeur_fonciere:
                      description: Prix de la transaction en euros
                      type: number
                      example: 350000
                    vefa:
                      description: Indicateur VEFA (0=Non, 1=Oui)
                      type: integer
                      example: 0
                    code_type_bien:
                      description: Code du type de bien
                      type: integer
                      example: 121
                    libelle_type:
                      description: Libellé du type de bien
                      type: string
                      example: UN APPARTEMENT
                    bati_type:
                      description: Type de bâti calculé (0-17)
                      type: integer
                      example: 7
                    nb_dispositions:
                      description: Nombre de dispositions
                      type: integer
                      example: 1
                    nb_lots:
                      description: Nombre de lots
                      type: integer
                      example: 1
                    nb_parcelles:
                      description: Nombre de parcelles
                      type: integer
                      example: 1
                    nb_parcelles_mutees:
                      description: Nombre de parcelles mutées
                      type: integer
                      example: 1
                    nb_locaux:
                      description: Nombre de locaux
                      type: integer
                      example: 1
                    nb_maisons:
                      description: Nombre de maisons
                      type: integer
                      example: 0
                    nb_appartements:
                      description: Nombre d'appartements
                      type: integer
                      example: 1
                    nb_dependances:
                      description: Nombre de dépendances
                      type: integer
                      example: 0
                    nb_locaux_activite:
                      description: Nombre de locaux d'activité
                      type: integer
                      example: 0
                    surface_terrain:
                      description: Surface de terrain en m²
                      type: number
                      example: 0
                    surface_batie:
                      description: Surface bâtie totale en m²
                      type: number
                      example: 75.5
                    surface_maisons:
                      description: Surface des maisons en m²
                      type: number
                      example: 0
                    surface_appartements:
                      description: Surface des appartements en m²
                      type: number
                      example: 75.5
                    surface_activite:
                      description: Surface des locaux d'activité en m²
                      type: number
                      example: 0
                    parcelles:
                      description: Liste des parcelles concernées par la transaction
                      type: array
                      items:
                        properties:
                          code:
                            description: Code cadastral
                            type: string
                            example: 750010001AB0001
                          section:
                            description: Section
                            type: string
                            example: AB
                          numero:
                            description: Numéro
                            type: string
                            example: '0001'
                          superficie:
                            description: Superficie en m²
                            type: number
                            example: 450.5
                        type: object
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          description: Code INSEE
                          type: string
                          example: '75056'
                        nom:
                          description: Nom de la commune
                          type: string
                          example: Paris
                        codes_postaux:
                          description: Codes postaux
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                            - '75002'
                            - '75003'
                      type: object
                    centre:
                      description: Géométrie GeoJSON du point central
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          description: Coordonnées [lon, lat]
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                  type: object
                example:
                  - id_mutation: 2023-12345
                    date_mutation: '2023-06-15'
                    nature_mutation: Vente
                    valeur_fonciere: 350000
                    vefa: 0
                    code_type_bien: 121
                    libelle_type: UN APPARTEMENT
                    bati_type: 7
                    nb_dispositions: 1
                    nb_lots: 1
                    nb_parcelles: 1
                    nb_parcelles_mutees: 1
                    nb_locaux: 1
                    nb_maisons: 0
                    nb_appartements: 1
                    nb_dependances: 0
                    nb_locaux_activite: 0
                    surface_terrain: 0
                    surface_batie: 75.5
                    surface_maisons: 0
                    surface_appartements: 75.5
                    surface_activite: 0
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 450.5
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de la transaction DVF (toujours un Point -
                            centre de la parcelle)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            id_mutation:
                              description: Identifiant unique de la mutation
                              type: string
                              example: 2023-12345
                            date_mutation:
                              description: Date de signature de l'acte
                              type: string
                              format: date
                              example: '2023-06-15'
                            nature_mutation:
                              description: Nature de la mutation
                              type: string
                              example: Vente
                            valeur_fonciere:
                              description: Prix de la transaction en euros
                              type: number
                              example: 350000
                            vefa:
                              description: Indicateur VEFA (0=Non, 1=Oui)
                              type: integer
                              example: 0
                            code_type_bien:
                              description: Code du type de bien
                              type: integer
                              example: 121
                            libelle_type:
                              description: Libellé du type de bien
                              type: string
                              example: UN APPARTEMENT
                            bati_type:
                              description: Type de bâti calculé (0-17)
                              type: integer
                              example: 7
                            nb_dispositions:
                              description: Nombre de dispositions
                              type: integer
                              example: 1
                            nb_lots:
                              description: Nombre de lots
                              type: integer
                              example: 1
                            nb_parcelles:
                              description: Nombre de parcelles
                              type: integer
                              example: 1
                            nb_parcelles_mutees:
                              description: Nombre de parcelles mutées
                              type: integer
                              example: 1
                            nb_locaux:
                              description: Nombre de locaux
                              type: integer
                              example: 1
                            nb_maisons:
                              description: Nombre de maisons
                              type: integer
                              example: 0
                            nb_appartements:
                              description: Nombre d'appartements
                              type: integer
                              example: 1
                            nb_dependances:
                              description: Nombre de dépendances
                              type: integer
                              example: 0
                            nb_locaux_activite:
                              description: Nombre de locaux d'activité
                              type: integer
                              example: 0
                            surface_terrain:
                              description: Surface de terrain en m²
                              type: number
                              example: 0
                            surface_batie:
                              description: Surface bâtie totale en m²
                              type: number
                              example: 75.5
                            surface_maisons:
                              description: Surface des maisons en m²
                              type: number
                              example: 0
                            surface_appartements:
                              description: Surface des appartements en m²
                              type: number
                              example: 75.5
                            surface_activite:
                              description: Surface des locaux d'activité en m²
                              type: number
                              example: 0
                            parcelles:
                              description: >-
                                Liste des parcelles concernées par la
                                transaction
                              type: array
                              items:
                                properties:
                                  code:
                                    description: Code cadastral complet
                                    type: string
                                    example: 750010001AB0001
                                  section:
                                    description: Code de la section
                                    type: string
                                    example: AB
                                  numero:
                                    description: Numéro de parcelle
                                    type: string
                                    example: '0001'
                                  superficie:
                                    description: Superficie de la parcelle en m²
                                    type: number
                                    example: 450.5
                                type: object
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  description: Code INSEE
                                  type: string
                                  example: '75056'
                                nom:
                                  description: Nom de la commune
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: Liste des codes postaux
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                                    - '75002'
                                    - '75003'
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        id_mutation: 2023-12345
                        date_mutation: '2023-06-15'
                        nature_mutation: Vente
                        valeur_fonciere: 350000
                        vefa: 0
                        code_type_bien: 121
                        libelle_type: UN APPARTEMENT
                        bati_type: 7
                        nb_dispositions: 1
                        nb_lots: 1
                        nb_parcelles: 1
                        nb_parcelles_mutees: 1
                        nb_locaux: 1
                        nb_maisons: 0
                        nb_appartements: 1
                        nb_dependances: 0
                        nb_locaux_activite: 0
                        surface_terrain: 0
                        surface_batie: 75.5
                        surface_maisons: 0
                        surface_appartements: 75.5
                        surface_activite: 0
                        parcelles:
                          - code: 750010001AB0001
                            section: AB
                            numero: '0001'
                            superficie: 450.5
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75003'
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune transaction trouvée
      security:
        - bearer:
            - '*'
  /api/v1/plu:
    get:
      tags:
        - Données foncières & immobilières
      summary: Rechercher des zones PLU avec leurs documents associés
      description: >-
        Permet de rechercher des zones d'urbanisme (PLU) avec les documents et
        fichiers associés par différents critères : coordonnées GPS, code
        postal, type de zone, codes INSEE. Chaque zone retourne le document PLU
        parent et ses fichiers. Les résultats peuvent être retournés au format
        JSON ou GeoJSON avec pagination par curseur.
      operationId: getPlus
      parameters:
        - name: zone
          in: query
          description: >-
            Zone PLU principale. Accepte plusieurs valeurs séparées par des
            virgules. La recherche est insensible à la casse (u = U).


            **Liste complète des zones possibles :**


            - `A` - Zone Agricole : Secteurs à protéger en raison du potentiel
            agronomique, biologique ou économique des terres agricoles

            - `Ah` - Zone Agricole avec habitat diffus : Sous-zone A permettant
            l'habitat diffus en milieu agricole

            - `AUc` - Zone À Urbaniser - Centre : Secteur destiné à
            l'urbanisation future, généralement situé en centre-ville

            - `AUs` - Zone À Urbaniser - Secteur : Secteur destiné à
            l'urbanisation future, généralement en périphérie

            - `N` - Zone Naturelle : Secteurs à protéger en raison de la qualité
            des sites, des milieux naturels ou des paysages

            - `Nd` - Zone Naturelle avec densification : Sous-zone N permettant
            une densification limitée

            - `Nh` - Zone Naturelle avec habitat diffus : Sous-zone N permettant
            l'habitat diffus en milieu naturel

            - `U` - Zone Urbaine : Secteurs déjà urbanisés où les équipements
            publics existants permettent d'admettre immédiatement des
            constructions
          required: false
          schema:
            type: string
            example: ''
        - name: type_zone
          in: query
          description: >-
            Type de zone PLU spécifique (ex: UBa, AUs, U1e, N, etc.). Accepte
            plusieurs valeurs séparées par des virgules (ex: 'UBa,AUs,U1e'). La
            recherche est insensible à la casse (uba = UBa).
          required: false
          schema:
            type: string
            example: ''
        - name: code_postal
          in: query
          description: Code postal (5 chiffres) pour filtrer les zones PLU
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher les zones PLU
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher les zones PLU
            contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: code_parcelle
          in: query
          description: >-
            Code cadastral de la parcelle (Identifiant Cadastral - 14
            caractères). Accepte plusieurs valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: '75056'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Note : le champ 'parcelles'
            est limité à un maximum de 10 parcelles par zone PLU. Exemple :
            champs=zone,titre,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - titre
                - description
                - zone
                - type_zone
                - surface
                - perimetre
                - documents
                - parcelles
                - municipalite
                - bbox
                - centre
                - contour
            default:
              - titre
              - description
              - zone
              - type_zone
              - surface
              - documents
              - municipalite
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: zone
            enum:
              - surface
              - zone
              - type_zone
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement : 'centre' pour le point central, 'contour' pour
            le polygone complet, 'bbox' pour la boîte englobante. Ce paramètre
            est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
              - contour
              - bbox
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    titre:
                      description: Titre de la zone
                      type: string
                      example: Zone d'extension urbaine
                    description:
                      description: Description longue de la zone
                      type: string
                      example: >-
                        Zone d'habitat ou les constructions d'habitations
                        collectives sont élevées
                    type_zone:
                      description: Type de zone (U, AU, A, N, etc.)
                      type: string
                      example: U
                    zone:
                      description: Zone (Uba, AUs, U1e etc.)
                      type: string
                      example: Uba
                    surface:
                      description: Surface en m²
                      type: number
                      example: 125000.5
                    perimetre:
                      description: Périmètre en m
                      type: number
                      example: 1500.8
                    parcelles:
                      description: >-
                        Liste des parcelles cadastrales dans la zone PLU
                        (limitée à 10 parcelles)
                      type: array
                      items:
                        properties:
                          code:
                            description: Code cadastral de la parcelle
                            type: string
                            example: 750010001AB0001
                          section:
                            description: Code section
                            type: string
                            example: AB
                          numero:
                            description: Numéro de parcelle
                            type: string
                            example: '0001'
                          superficie:
                            description: Superficie en m²
                            type: number
                            example: 450.5
                        type: object
                    documents:
                      description: Document PLU parent avec fichiers associés
                      properties:
                        partition:
                          description: Partition du document PLU
                          type: string
                          example: DU_75056
                        fichiers:
                          type: array
                          items:
                            type: object
                      type: object
                    municipalite:
                      properties:
                        code:
                          type: string
                        nom:
                          type: string
                        codes_postaux:
                          type: array
                          items:
                            type: string
                      type: object
                    centre:
                      description: Point central géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                    bbox:
                      description: Boîte englobante (GeoJSON Polygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          type: array
                          items:
                            type: number
                      type: object
                    contour:
                      description: >-
                        Contour complet de la zone (GeoJSON
                        Polygon/MultiPolygon)
                      properties:
                        type:
                          type: string
                          example: Polygon
                        coordinates:
                          type: array
                          items:
                            type: number
                      type: object
                  type: object
                example:
                  - titre: Zone d'extension urbaine
                    description: >-
                      Zone d'habitat ou les constructions d'habitations
                      collectives sont élevées
                    type_zone: U
                    zone: Uba
                    surface: 125000.5
                    perimetre: 1500.8
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 450.5
                      - code: 750010001AB0002
                        section: AB
                        numero: '0002'
                        superficie: 320.8
                    documents:
                      partition: DU_75056
                      fichiers:
                        - code: '1'
                          titre: Règlement zone UBa
                          nom_fichier: reglement_uba.pdf
                          url: https://example.com/reglement_uba.pdf
                          categorie: Documents Règlementaires
                          date_creation: '2023-01-15'
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
                    bbox:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
                    contour:
                      type: Polygon
                      coordinates:
                        - - - 2.32
                            - 48.85
                          - - 2.37
                            - 48.85
                          - - 2.37
                            - 48.87
                          - - 2.32
                            - 48.87
                          - - 2.32
                            - 48.85
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de la zone PLU (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour, Polygon
                            si geometrie=bbox)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            titre:
                              description: Titre de la zone
                              type: string
                              example: Zone d'extension urbaine
                            description:
                              description: Description longue de la zone
                              type: string
                              example: >-
                                Zone d'habitat ou les constructions
                                d'habitations collectives sont élevées
                            type_zone:
                              description: Type de zone (U, AU, A, N, etc.)
                              type: string
                              example: U
                            zone:
                              description: Zone (Uba, AUs, U1e etc.)
                              type: string
                              example: Uba
                            surface:
                              description: Surface en m²
                              type: number
                              example: 125000.5
                            perimetre:
                              description: Périmètre en m
                              type: number
                              example: 1500.8
                            parcelles:
                              description: >-
                                Liste des parcelles cadastrales dans la zone PLU
                                (limitée à 10 parcelles)
                              type: array
                              items:
                                properties:
                                  code:
                                    description: Code cadastral de la parcelle
                                    type: string
                                    example: 750010001AB0001
                                  section:
                                    description: Code section
                                    type: string
                                    example: AB
                                  numero:
                                    description: Numéro de parcelle
                                    type: string
                                    example: '0001'
                                  superficie:
                                    description: Superficie en m²
                                    type: number
                                    example: 450.5
                                type: object
                            documents:
                              description: Document PLU parent avec ses fichiers associés
                              properties:
                                partition:
                                  description: Partition du document PLU
                                  type: string
                                  example: DU_75056
                                fichiers:
                                  description: Liste des fichiers PDF/documents liés au PLU
                                  type: array
                                  items:
                                    properties:
                                      titre:
                                        description: Titre du fichier
                                        type: string
                                        example: Règlement zone UBa
                                      nom_fichier:
                                        description: Nom du fichier
                                        type: string
                                        example: reglement_uba.pdf
                                      url:
                                        description: URL de téléchargement
                                        type: string
                                        format: uri
                                        example: https://example.com/reglement_uba.pdf
                                      categorie:
                                        description: >-
                                          Catégorie du document PLU basée sur le
                                          nom du fichier
                                        type: string
                                        example: Documents Règlementaires
                                      date_creation:
                                        description: Date de création du fichier
                                        type: string
                                        format: date
                                        example: '2023-01-15'
                                    type: object
                              type: object
                            municipalite:
                              properties:
                                code:
                                  type: string
                                  example: '75056'
                                nom:
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                                    - '75002'
                                    - '75003'
                              type: object
                            contour:
                              description: Contour de la zone PLU au format GeoJSON Polygon
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  type: array
                                  items:
                                    type: array
                                    items:
                                      type: array
                                      items:
                                        type: number
                              type: object
                            bbox:
                              description: >-
                                Boîte englobante de la zone PLU au format
                                GeoJSON Polygon
                              properties:
                                type:
                                  type: string
                                  example: Polygon
                                coordinates:
                                  type: array
                                  items:
                                    type: array
                                    items:
                                      type: array
                                      items:
                                        type: number
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        titre: Zone d'extension urbaine
                        description: >-
                          Zone d'habitat ou les constructions d'habitations
                          collectives sont élevées
                        type_zone: U
                        zone: UBa
                        surface: 125000.5
                        perimetre: 1500.8
                        parcelles:
                          - code: 750010001AB0001
                            section: AB
                            numero: '0001'
                            superficie: 450.5
                          - code: 750010001AB0002
                            section: AB
                            numero: '0002'
                            superficie: 320.8
                        documents:
                          partition: DU_75056
                          fichiers:
                            - titre: Règlement zone UBa
                              nom_fichier: reglement_uba.pdf
                              url: https://example.com/reglement_uba.pdf
                              categorie: Documents Règlementaires
                              date_creation: '2023-01-15'
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75003'
                        contour:
                          type: Polygon
                          coordinates:
                            - - - 2.35
                                - 48.855
                              - - 2.355
                                - 48.855
                              - - 2.355
                                - 48.858
                              - - 2.35
                                - 48.858
                              - - 2.35
                                - 48.855
                        bbox:
                          type: Polygon
                          coordinates:
                            - - - 2.35
                                - 48.855
                              - - 2.355
                                - 48.855
                              - - 2.355
                                - 48.858
                              - - 2.35
                                - 48.858
                              - - 2.35
                                - 48.855
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun PLU trouvé
      security:
        - bearer:
            - '*'
  /api/v1/permis:
    get:
      tags:
        - Données foncières & immobilières
      summary: Rechercher des permis de construire et autres autorisations d'urbanisme
      description: >-
        Permet de rechercher des permis de construire et autres autorisations
        d'urbanisme par différents critères : coordonnées GPS, code postal,
        type, état, codes INSEE. Les résultats peuvent être retournés au format
        JSON ou GeoJSON.
      operationId: getPermits
      parameters:
        - name: code
          in: query
          description: >-
            Numéro du permis de construire ou d'une autre autorisation
            d'urbanisme. Accepte plusieurs valeurs séparées par des virgules
            (ex: '075056220010001,075056220010002').
          required: false
          schema:
            type: string
            example: ''
        - name: type_autorisation
          in: query
          description: >-
            Type d'autorisation depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs séparées par des virgules.


            **Liste complète des types possibles :**


            - `0` - Non communiqué : Type de permis non précisé

            - `1` - Permis de construire de logement (PC) : Autorisation pour
            construire des logements neufs

            - `2` - Déclaration préalable de travaux de logement (DP) : Pour
            travaux de logement de faible ampleur

            - `3` - Permis de construire de local (PC) : Autorisation pour
            construire des locaux commerciaux, industriels ou professionnels

            - `4` - Déclaration préalable de travaux de local (DP) : Pour
            travaux de local de faible ampleur

            - `5` - Permis d'aménager (PA) : Pour aménager un terrain
            (lotissement, camping, etc.)

            - `6` - Permis de démolir : Autorisation de démolir une construction
            existante
          required: false
          schema:
            type: string
            example: ''
        - name: etat
          in: query
          description: >-
            État d'avancement du projet depuis le 1er Janvier 2013. Accepte
            plusieurs valeurs séparées par des virgules.


            **Liste complète des états possibles :**


            - `0` - Non communiqué : État du permis non précisé

            - `2` - Autorisé : Permis délivré et autorisé

            - `4` - Annulé : Permis annulé ou refusé

            - `5` - Commencé : Travaux commencés (DOC - Déclaration d'Ouverture
            de Chantier)

            - `6` - Terminé : Travaux terminés (DAACT - Déclaration Attestant
            l'Achèvement et la Conformité des Travaux)
          required: false
          schema:
            type: string
            example: ''
        - name: date_autorisation_min
          in: query
          description: Date minimale d'autorisation (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_autorisation_max
          in: query
          description: Date maximale d'autorisation (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_doc_min
          in: query
          description: Date minimale d'ouverture de chantier (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_doc_max
          in: query
          description: Date maximale d'ouverture de chantier (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_daact_min
          in: query
          description: Date minimale d'achèvement des travaux (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: date_daact_max
          in: query
          description: Date maximale d'achèvement des travaux (format AAAA-MM-JJ).
          required: false
          schema:
            type: string
            format: date
            example: ''
        - name: cat_dem
          in: query
          description: >-
            Catégorie du demandeur du permis depuis le 1er Janvier 2013. Accepte
            plusieurs valeurs séparées par des virgules.


            **Liste complète des catégories possibles :**


            **Particuliers :**

            - `10` - Particuliers SAI (Sans Autre Indication) : Particuliers non
            catégorisés

            - `11` - Particuliers purs : Personnes physiques individuelles

            - `12` - SCI de particuliers : Sociétés Civiles Immobilières de
            particuliers


            **Bailleurs sociaux :**

            - `20` - Bailleurs sociaux SAI : Bailleurs sociaux non catégorisés

            - `21` - Organismes HLM : Office public de l'habitat, entreprises
            sociales pour l'habitat

            - `22` - EPL (Entreprises Publiques Locales) : SEM, SPL
            d'aménagement ou de construction

            - `23` - Autres organismes : Collecteurs d'Action Logement,
            associations, fondations


            **Promoteurs :**

            - `30` - Promoteurs : Promoteurs immobiliers non catégorisés

            - `31` - Promoteurs reconnus : Promoteurs immobiliers professionnels
            reconnus

            - `32` - SCI ou supports de programmes : Supports juridiques de
            programmes immobiliers

            - `33` - Autres professionnels : Constructeurs de maisons
            individuelles, lotisseurs


            **Administrations publiques :**

            - `40` - Administrations publiques : Administrations non
            catégorisées

            - `41` - État et ODAC : État et Organismes Divers d'Administration
            Centrale

            - `42` - Départements et régions : Collectivités territoriales de
            niveau supérieur

            - `43` - Communes et EPIC : Communes et Établissements Publics à
            caractère Industriel et Commercial


            **Autres :**

            - `50` - Autres sociétés : Sociétés commerciales, industrielles ou
            de services

            - `80` - Sans objet : Catégorie non applicable

            - `90` - Non déterminé : Catégorie du demandeur non précisée
          required: false
          schema:
            type: string
            example: ''
        - name: siren_dem
          in: query
          description: >-
            Numéro SIREN du demandeur (9 chiffres). Accepte plusieurs valeurs
            séparées par des virgules (ex: '123456789,987654321').
          required: false
          schema:
            type: string
            example: ''
        - name: rec_archi
          in: query
          description: Indicateur de recours à un architecte.
          required: false
          schema:
            type: boolean
        - name: zone_op
          in: query
          description: >-
            Code zone opératoire. Accepte plusieurs valeurs séparées par des
            virgules (ex: '1,2').


            **Liste complète des zones possibles :**


            - `1` - Lotissement : Terrain divisé en lots destinés à la
            construction

            - `2` - ZAC : Zone d'Aménagement Concerté

            - `3` - AFU : Association Foncière Urbaine

            - `4` - Hors zones : Projet situé hors de toute zone opératoire
          required: false
          schema:
            type: string
            example: ''
        - name: nature_projet
          in: query
          description: >-
            Nature du projet depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs séparées par des virgules.


            **Liste complète des natures possibles :**


            - `0` - Destruction de construction : Démolition totale ou partielle
            d'une construction existante

            - `1` - Nouvelle construction : Construction d'un bâtiment neuf sur
            terrain nu

            - `2` - Transformation sans extension ni diminution : Modification
            intérieure sans changement de surface

            - `3` - Transformation avec extension : Modification avec
            augmentation de la surface

            - `4` - Transformation avec diminution : Modification avec réduction
            de la surface

            - `5` - Extension sans transformation : Agrandissement sans
            modification de l'existant

            - `6` - Diminution sans transformation : Réduction de surface sans
            modification de l'existant

            - `7` - Non communiqué : Nature du permis non précisée
          required: false
          schema:
            type: string
            example: ''
        - name: extension
          in: query
          description: Indicateur d'extension.
          required: false
          schema:
            type: boolean
        - name: surelevation
          in: query
          description: Indicateur de surélévation.
          required: false
          schema:
            type: boolean
        - name: nivsupp
          in: query
          description: Indicateur de création de niveau(x) supplémentaire(s).
          required: false
          schema:
            type: boolean
        - name: nb_niv_max_min
          in: query
          description: Nombre minimal de niveaux du bâtiment le plus élevé.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_niv_max_max
          in: query
          description: Nombre maximal de niveaux du bâtiment le plus élevé.
          required: false
          schema:
            type: integer
            example: ''
        - name: utilisation
          in: query
          description: >-
            Utilisation visée du bien après construction ou rénovation. Accepte
            plusieurs valeurs séparées par des virgules (ex: '2,3,4').


            **Liste complète des utilisations possibles :**


            - `1` - Occupation personnelle : Le demandeur occupera le bien

            - `2` - Vente : Le bien sera mis en vente

            - `3` - Location : Le bien sera mis en location

            - `4` - Vente-Location : Usage mixte vente et location

            - `5` - Non rempli : Information non communiquée
          required: false
          schema:
            type: string
            example: ''
        - name: res_princip_ou_second
          in: query
          description: >-
            Type d'habitation du logement. Accepte plusieurs valeurs séparées
            par des virgules (ex: '1,2').


            **Liste complète des types possibles :**


            - `1` - Résidence principale : Logement occupé habituellement par le
            propriétaire

            - `2` - Résidence secondaire : Logement occupé occasionnellement
            (vacances, week-end)

            - `3` - Non rempli : Information non communiquée
          required: false
          schema:
            type: string
            example: ''
        - name: type_annexe
          in: query
          description: >-
            Type d'annexe prévu dans le projet de construction. Accepte
            plusieurs valeurs séparées par des virgules (ex: '1,2,3').


            **Liste complète des types possibles :**


            - `1` - Piscine

            - `2` - Garage

            - `3` - Véranda

            - `4` - Abri de jardin

            - `5` - Autre : Annexe d'un autre type

            - `6` - Plusieurs : Plusieurs types d'annexes

            - `7` - Aucune : Aucune annexe prévue
          required: false
          schema:
            type: string
            example: ''
        - name: residence
          in: query
          description: >-
            Type de résidence spécialisée ou collective. Accepte plusieurs
            valeurs séparées par des virgules (ex: '2,5').


            **Liste complète des types possibles :**


            - `1` - Résidence pour personnes âgées : EHPAD, résidence seniors

            - `2` - Résidence étudiante : Logements dédiés aux étudiants

            - `3` - Résidence de tourisme : Résidence hôtelière, résidence de
            vacances

            - `4` - Résidence hôtelière sociale : Hébergement temporaire pour
            personnes en difficulté

            - `5` - Résidence sociale : Logements accompagnés pour personnes en
            insertion

            - `6` - Résidence pour personnes handicapées : Logements adaptés aux
            handicaps

            - `7` - Autre : Résidence spécialisée d'un autre type

            - `8` - Mixte : Résidence combinant plusieurs types

            - `9` - Non rempli : Information non communiquée
          required: false
          schema:
            type: string
            example: ''
        - name: nb_chambres_min
          in: query
          description: Nombre minimal de chambres (hôtels et hébergements).
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_chambres_max
          in: query
          description: Nombre maximal de chambres (hôtels et hébergements).
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_ind_crees_min
          in: query
          description: Nombre minimal de logements individuels créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_ind_crees_max
          in: query
          description: Nombre maximal de logements individuels créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_col_crees_min
          in: query
          description: Nombre minimal de logements collectifs créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_col_crees_max
          in: query
          description: Nombre maximal de logements collectifs créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_demolis_min
          in: query
          description: Nombre minimal de logements démolis.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_demolis_max
          in: query
          description: Nombre maximal de logements démolis.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_1p_min
          in: query
          description: Nombre minimal de logements de 1 pièce (studios/T1) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_1p_max
          in: query
          description: Nombre maximal de logements de 1 pièce (studios/T1) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_2p_min
          in: query
          description: Nombre minimal de logements de 2 pièces (T2) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_2p_max
          in: query
          description: Nombre maximal de logements de 2 pièces (T2) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_3p_min
          in: query
          description: Nombre minimal de logements de 3 pièces (T3) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_3p_max
          in: query
          description: Nombre maximal de logements de 3 pièces (T3) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_4p_min
          in: query
          description: Nombre minimal de logements de 4 pièces (T4) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_4p_max
          in: query
          description: Nombre maximal de logements de 4 pièces (T4) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_5p_min
          in: query
          description: Nombre minimal de logements de 5 pièces (T5) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_5p_max
          in: query
          description: Nombre maximal de logements de 5 pièces (T5) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_6p_plus_min
          in: query
          description: Nombre minimal de logements de 6 pièces et plus (T6+) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_6p_plus_max
          in: query
          description: Nombre maximal de logements de 6 pièces et plus (T6+) créés.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_pret_loc_social_min
          in: query
          description: Nombre minimal de logements locatifs sociaux.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lgt_pret_loc_social_max
          in: query
          description: Nombre maximal de logements locatifs sociaux.
          required: false
          schema:
            type: integer
            example: ''
        - name: surf_hab_min
          in: query
          description: >-
            Surface de plancher habitation minimale (en m²). Filtre sur la somme
            des surfaces : surf_hab_avant + surf_hab_creee +
            surf_hab_issue_transfo
          required: false
          schema:
            type: number
            example: ''
        - name: surf_hab_max
          in: query
          description: >-
            Surface de plancher habitation maximale (en m²). Filtre sur la somme
            des surfaces : surf_hab_avant + surf_hab_creee +
            surf_hab_issue_transfo
          required: false
          schema:
            type: number
            example: ''
        - name: surf_autre_min
          in: query
          description: >-
            Surface de plancher autre (non résidentiel) minimale (en m²). Filtre
            sur la somme des surfaces : surf_autre_avant + surf_autre_creee +
            surf_autre_issue_transfo
          required: false
          schema:
            type: number
            example: ''
        - name: surf_autre_max
          in: query
          description: >-
            Surface de plancher autre (non résidentiel) maximale (en m²). Filtre
            sur la somme des surfaces : surf_autre_avant + surf_autre_creee +
            surf_autre_issue_transfo
          required: false
          schema:
            type: number
            example: ''
        - name: surf_totale_min
          in: query
          description: >-
            Surface totale minimale du projet (en m²). Filtre sur la somme de
            toutes les surfaces (habitation + autre).
          required: false
          schema:
            type: number
            example: ''
        - name: surf_totale_max
          in: query
          description: >-
            Surface totale maximale du projet (en m²). Filtre sur la somme de
            toutes les surfaces (habitation + autre).
          required: false
          schema:
            type: number
            example: ''
        - name: code_postal
          in: query
          description: Code postal (5 chiffres) pour filtrer les permis.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher les permis liés
            à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher les permis
            liés à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: code_parcelle
          in: query
          description: >-
            Code cadastral de la parcelle (Identifiant Cadastral - 14
            caractères). Accepte plusieurs valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: '75056'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Note : le champ 'parcelles'
            est limité à un maximum de 10 parcelles par permis. Exemple :
            champs=code,type,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - code
                - type_autorisation
                - etat
                - date_autorisation
                - date_doc
                - date_daact
                - cat_dem
                - siren_dem
                - denomination_dem
                - rec_archi
                - zone_op
                - nature_projet
                - extension
                - surelevation
                - nivsupp
                - nb_niv_max
                - utilisation
                - res_princip_ou_second
                - type_annexe
                - residence
                - nb_chambres
                - nb_lgt_ind_crees
                - nb_lgt_col_crees
                - nb_lgt_demolis
                - nb_lgt_1p
                - nb_lgt_2p
                - nb_lgt_3p
                - nb_lgt_4p
                - nb_lgt_5p
                - nb_lgt_6p_plus
                - nb_lgt_pret_loc_social
                - surf_hab_avant
                - surf_hab_creee
                - surf_hab_issue_transfo
                - surf_hab_demolie
                - surf_hab_transformee
                - surf_autre_avant
                - surf_autre_creee
                - surf_autre_issue_transfo
                - surf_autre_demolie
                - surf_autre_transformee
                - parcelles
                - municipalite
                - centre
            default:
              - code
              - type_autorisation
              - etat
              - date_autorisation
              - date_doc
              - date_daact
              - cat_dem
              - siren_dem
              - denomination_dem
              - rec_archi
              - zone_op
              - nature_projet
              - extension
              - surelevation
              - nivsupp
              - nb_niv_max
              - utilisation
              - res_princip_ou_second
              - type_annexe
              - residence
              - nb_chambres
              - nb_lgt_ind_crees
              - nb_lgt_col_crees
              - nb_lgt_demolis
              - surf_hab_avant
              - surf_hab_creee
              - surf_hab_issue_transfo
              - surf_hab_demolie
              - surf_hab_transformee
              - surf_autre_avant
              - surf_autre_creee
              - surf_autre_issue_transfo
              - surf_autre_demolie
              - surf_autre_transformee
              - municipalite
        - name: champ_tri
          in: query
          description: Champ utilisé pour trier les résultats.
          required: false
          schema:
            type: string
            default: date_autorisation
            enum:
              - code
              - type_autorisation
              - etat
              - date_autorisation
              - date_doc
              - date_daact
              - cat_dem
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: desc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement. Pour les permis, seul 'centre' est disponible
            (point central de la parcelle principale), car un permis n'a pas de
            géométrie propre. Ce paramètre est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    code:
                      description: Numéro du permis de construire
                      type: string
                      example: PC075056-2023-00123
                    type_autorisation:
                      description: Type d'autorisation
                      type: string
                      example: '1'
                    etat:
                      description: État d'avancement
                      type: string
                      example: '2'
                    date_autorisation:
                      description: Date réelle d'autorisation du permis
                      type: string
                      format: date
                      example: '2023-09-20'
                    date_doc:
                      description: Date réelle de DOC (Déclaration d'Ouverture de Chantier)
                      type: string
                      format: date
                      example: '2023-09-25'
                    date_daact:
                      description: >-
                        Date réelle de DAACT (Déclaration d'Achèvement et de
                        Conformité des Travaux)
                      type: string
                      format: date
                      example: '2024-03-15'
                    cat_dem:
                      description: Catégorie du demandeur
                      type: integer
                      example: 31
                    siren_dem:
                      description: Numéro SIREN du demandeur
                      type: string
                      example: '123456789'
                    denomination_dem:
                      description: Dénomination du demandeur
                      type: string
                      example: Example Denomination
                    rec_archi:
                      description: Recours à un architecte
                      type: boolean
                      example: true
                    zone_op:
                      description: Code zone opératoire
                      type: integer
                      example: 4
                    nature_projet:
                      description: Nature du projet
                      type: integer
                      example: 1
                    extension:
                      description: Indicateur d'extension
                      type: boolean
                      example: false
                    surelevation:
                      description: Indicateur de surélévation
                      type: boolean
                      example: false
                    nivsupp:
                      description: Indicateur de niveau(x) supplémentaire(s)
                      type: boolean
                      example: false
                    nb_niv_max:
                      description: Nombre de niveaux du bâtiment le plus élevé
                      type: integer
                      example: 3
                    utilisation:
                      description: Utilisation visée
                      type: integer
                      example: 2
                    res_princip_ou_second:
                      description: Type d'habitation
                      type: integer
                      example: 1
                    type_annexe:
                      description: Type d'annexe
                      type: integer
                      example: 7
                    residence:
                      description: Type de résidence
                      type: integer
                      example: 9
                    nb_chambres:
                      description: Nombre de chambres
                      type: integer
                      example: null
                    nb_lgt_ind_crees:
                      description: Nombre de logements individuels créés
                      type: integer
                      example: 0
                    nb_lgt_col_crees:
                      description: Nombre de logements collectifs créés
                      type: integer
                      example: 5
                    nb_lgt_demolis:
                      description: Nombre de logements démolis
                      type: integer
                      example: 0
                    nb_lgt_1p:
                      description: Nombre de logements de 1 pièce
                      type: integer
                      example: 1
                    nb_lgt_2p:
                      description: Nombre de logements de 2 pièces
                      type: integer
                      example: 2
                    nb_lgt_3p:
                      description: Nombre de logements de 3 pièces
                      type: integer
                      example: 1
                    nb_lgt_4p:
                      description: Nombre de logements de 4 pièces
                      type: integer
                      example: 1
                    nb_lgt_5p:
                      description: Nombre de logements de 5 pièces
                      type: integer
                      example: 0
                    nb_lgt_6p_plus:
                      description: Nombre de logements de 6 pièces et plus
                      type: integer
                      example: 0
                    nb_lgt_pret_loc_social:
                      description: Nombre de logements locatifs sociaux
                      type: integer
                      example: 2
                    surf_hab_avant:
                      description: Surface habitation avant travaux en m²
                      type: number
                      example: 0
                    surf_hab_creee:
                      description: Surface habitation créée en m²
                      type: number
                      example: 420.5
                    surf_hab_issue_transfo:
                      description: Surface habitation issue de transformation en m²
                      type: number
                      example: 0
                    surf_hab_demolie:
                      description: Surface habitation démolie en m²
                      type: number
                      example: 0
                    surf_hab_transformee:
                      description: Surface habitation transformée en m²
                      type: number
                      example: 0
                    surf_autre_avant:
                      description: Surface autre (non résidentiel) avant travaux en m²
                      type: number
                      example: 0
                    surf_autre_creee:
                      description: Surface autre créée en m²
                      type: number
                      example: 50.2
                    surf_autre_issue_transfo:
                      description: Surface autre issue de transformation en m²
                      type: number
                      example: 0
                    surf_autre_demolie:
                      description: Surface autre démolie en m²
                      type: number
                      example: 0
                    surf_autre_transformee:
                      description: Surface autre transformée en m²
                      type: number
                      example: 0
                    parcelles:
                      description: Liste des parcelles cadastrales concernées par le permis
                      type: array
                      items:
                        properties:
                          code:
                            description: Code cadastral de la parcelle
                            type: string
                            example: 750010001AB0001
                          section:
                            description: Code section
                            type: string
                            example: AB
                          numero:
                            description: Numéro de parcelle
                            type: string
                            example: '0001'
                          superficie:
                            description: Superficie en m²
                            type: number
                            example: 450.5
                        type: object
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          description: Code INSEE de la commune
                          type: string
                          example: '75056'
                        nom:
                          description: Nom de la commune
                          type: string
                          example: Paris
                        codes_postaux:
                          description: Liste de tous les codes postaux de la commune
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                            - '75002'
                            - '75003'
                      type: object
                    centre:
                      description: >-
                        Coordonnées du centre géographique de la parcelle
                        principale (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                  type: object
                example:
                  - code: PC075056-2023-00123
                    type_autorisation: '1'
                    etat: '2'
                    date_autorisation: '2023-09-20'
                    date_doc: '2023-09-25'
                    date_daact: '2024-03-15'
                    cat_dem: 31
                    siren_dem: '123456789'
                    denomination_dem: Example Denomination
                    rec_archi: true
                    zone_op: 4
                    nature_projet: 1
                    extension: false
                    surelevation: false
                    nivsupp: false
                    nb_niv_max: 3
                    utilisation: 2
                    res_princip_ou_second: 1
                    type_annexe: 7
                    residence: 9
                    nb_chambres: null
                    nb_lgt_ind_crees: 0
                    nb_lgt_col_crees: 5
                    nb_lgt_demolis: 0
                    nb_lgt_1p: 1
                    nb_lgt_2p: 2
                    nb_lgt_3p: 1
                    nb_lgt_4p: 1
                    nb_lgt_5p: 0
                    nb_lgt_6p_plus: 0
                    nb_lgt_pret_loc_social: 2
                    surf_hab_avant: 0
                    surf_hab_creee: 420.5
                    surf_hab_issue_transfo: 0
                    surf_hab_demolie: 0
                    surf_hab_transformee: 0
                    surf_autre_avant: 0
                    surf_autre_creee: 50.2
                    surf_autre_issue_transfo: 0
                    surf_autre_demolie: 0
                    surf_autre_transformee: 0
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 450.5
                      - code: 750010001AB0002
                        section: AB
                        numero: '0002'
                        superficie: 320.8
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie du permis (Point si geometrie=centre,
                            Polygon/MultiPolygon si geometrie=contour)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            code:
                              description: Numéro du permis de construire
                              type: string
                              example: PC075056-2023-00123
                            type_autorisation:
                              description: Type d'autorisation
                              type: string
                              example: '1'
                            etat:
                              description: État d'avancement
                              type: string
                              example: '2'
                            date_autorisation:
                              description: Date réelle d'autorisation du permis
                              type: string
                              format: date
                              example: '2023-09-20'
                            date_doc:
                              description: >-
                                Date réelle de DOC (Déclaration d'Ouverture de
                                Chantier)
                              type: string
                              format: date
                              example: '2023-09-25'
                            date_daact:
                              description: >-
                                Date réelle de DAACT (Déclaration d'Achèvement
                                et de Conformité des Travaux)
                              type: string
                              format: date
                              example: '2024-03-15'
                            cat_dem:
                              description: Catégorie du demandeur
                              type: integer
                              example: 31
                            siren_dem:
                              description: Numéro SIREN du demandeur
                              type: string
                              example: '123456789'
                            denomination_dem:
                              description: Dénomination du demandeur
                              type: string
                              example: Example Denomination
                            rec_archi:
                              description: Recours à un architecte
                              type: boolean
                              example: true
                            zone_op:
                              description: Code zone opératoire
                              type: integer
                              example: 4
                            nature_projet:
                              description: Nature du projet
                              type: integer
                              example: 1
                            extension:
                              description: Indicateur d'extension
                              type: boolean
                              example: false
                            surelevation:
                              description: Indicateur de surélévation
                              type: boolean
                              example: false
                            nivsupp:
                              description: Indicateur de niveau(x) supplémentaire(s)
                              type: boolean
                              example: false
                            nb_niv_max:
                              description: Nombre de niveaux du bâtiment le plus élevé
                              type: integer
                              example: 3
                            utilisation:
                              description: Utilisation visée
                              type: integer
                              example: 2
                            res_princip_ou_second:
                              description: Type d'habitation
                              type: integer
                              example: 1
                            type_annexe:
                              description: Type d'annexe
                              type: integer
                              example: 7
                            residence:
                              description: Type de résidence
                              type: integer
                              example: 9
                            nb_chambres:
                              description: Nombre de chambres
                              type: integer
                              example: null
                            nb_lgt_ind_crees:
                              description: Nombre de logements individuels créés
                              type: integer
                              example: 0
                            nb_lgt_col_crees:
                              description: Nombre de logements collectifs créés
                              type: integer
                              example: 5
                            nb_lgt_demolis:
                              description: Nombre de logements démolis
                              type: integer
                              example: 0
                            nb_lgt_1p:
                              description: Nombre de logements de 1 pièce
                              type: integer
                              example: 1
                            nb_lgt_2p:
                              description: Nombre de logements de 2 pièces
                              type: integer
                              example: 2
                            nb_lgt_3p:
                              description: Nombre de logements de 3 pièces
                              type: integer
                              example: 1
                            nb_lgt_4p:
                              description: Nombre de logements de 4 pièces
                              type: integer
                              example: 1
                            nb_lgt_5p:
                              description: Nombre de logements de 5 pièces
                              type: integer
                              example: 0
                            nb_lgt_6p_plus:
                              description: Nombre de logements de 6 pièces et plus
                              type: integer
                              example: 0
                            nb_lgt_pret_loc_social:
                              description: Nombre de logements locatifs sociaux
                              type: integer
                              example: 2
                            surf_hab_avant:
                              description: Surface habitation avant travaux en m²
                              type: number
                              example: 0
                            surf_hab_creee:
                              description: Surface habitation créée en m²
                              type: number
                              example: 420.5
                            surf_hab_issue_transfo:
                              description: Surface habitation issue de transformation en m²
                              type: number
                              example: 0
                            surf_hab_demolie:
                              description: Surface habitation démolie en m²
                              type: number
                              example: 0
                            surf_hab_transformee:
                              description: Surface habitation transformée en m²
                              type: number
                              example: 0
                            surf_autre_avant:
                              description: >-
                                Surface autre (non résidentiel) avant travaux en
                                m²
                              type: number
                              example: 0
                            surf_autre_creee:
                              description: Surface autre créée en m²
                              type: number
                              example: 50.2
                            surf_autre_issue_transfo:
                              description: Surface autre issue de transformation en m²
                              type: number
                              example: 0
                            surf_autre_demolie:
                              description: Surface autre démolie en m²
                              type: number
                              example: 0
                            surf_autre_transformee:
                              description: Surface autre transformée en m²
                              type: number
                              example: 0
                            parcelles:
                              description: >-
                                Liste des parcelles cadastrales concernées par
                                le permis
                              type: array
                              items:
                                properties:
                                  code:
                                    description: Code cadastral de la parcelle
                                    type: string
                                    example: 750010001AB0001
                                  section:
                                    description: Code section
                                    type: string
                                    example: AB
                                  numero:
                                    description: Numéro de parcelle
                                    type: string
                                    example: '0001'
                                  superficie:
                                    description: Superficie en m²
                                    type: number
                                    example: 450.5
                                type: object
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  description: Code INSEE de la commune
                                  type: string
                                  example: '75056'
                                nom:
                                  description: Nom de la commune
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: >-
                                    Liste de tous les codes postaux de la
                                    commune
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                                    - '75002'
                                    - '75003'
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        code: PC075056-2023-00123
                        type_autorisation: '1'
                        etat: '2'
                        date_autorisation: '2023-09-20'
                        date_doc: '2023-09-25'
                        date_daact: '2024-03-15'
                        cat_dem: 31
                        siren_dem: '123456789'
                        denomination_dem: Example Denomination
                        rec_archi: true
                        zone_op: 4
                        nature_projet: 1
                        extension: false
                        surelevation: false
                        nivsupp: false
                        nb_niv_max: 3
                        utilisation: 2
                        res_princip_ou_second: 1
                        type_annexe: 7
                        residence: 9
                        nb_chambres: null
                        nb_lgt_ind_crees: 0
                        nb_lgt_col_crees: 5
                        nb_lgt_demolis: 0
                        nb_lgt_1p: 1
                        nb_lgt_2p: 2
                        nb_lgt_3p: 1
                        nb_lgt_4p: 1
                        nb_lgt_5p: 0
                        nb_lgt_6p_plus: 0
                        nb_lgt_pret_loc_social: 2
                        surf_hab_avant: 0
                        surf_hab_creee: 420.5
                        surf_hab_issue_transfo: 0
                        surf_hab_demolie: 0
                        surf_hab_transformee: 0
                        surf_autre_avant: 0
                        surf_autre_creee: 50.2
                        surf_autre_issue_transfo: 0
                        surf_autre_demolie: 0
                        surf_autre_transformee: 0
                        parcelles:
                          - code: 750010001AB0001
                            section: AB
                            numero: '0001'
                            superficie: 450.5
                          - code: 750010001AB0002
                            section: AB
                            numero: '0002'
                            superficie: 320.8
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75003'
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun permis trouvé
      security:
        - bearer:
            - '*'
  /api/v1/proprietaires:
    get:
      tags:
        - Données foncières & immobilières
      summary: Rechercher des propriétaires (personnes morales)
      description: >-
        Permet de rechercher des propriétaires personnes morales (entreprises,
        sociétés, etc.) par différents critères : SIREN, dénomination, code
        postal, parcelles cadastrales, codes INSEE. Les résultats peuvent être
        retournés au format JSON ou GeoJSON.
      operationId: getOwners
      parameters:
        - name: siren
          in: query
          description: >-
            Numéro SIREN du propriétaire (9 chiffres) - identifiant unique de
            l'entreprise. Accepte plusieurs valeurs séparées par des virgules
            (ex: '123456789,987654321').
          required: false
          schema:
            type: string
            example: ''
        - name: denomination
          in: query
          description: Dénomination sociale du propriétaire (recherche par similarité).
          required: false
          schema:
            type: string
            example: ''
        - name: code_droit
          in: query
          description: >-
            Code de droit du propriétaire sur le bien. Accepte plusieurs valeurs
            séparées par des virgules (ex: 'P,U,N').


            **Liste complète des codes possibles :**


            **Propriété pleine ou démembrée :**

            - `P` - Propriétaire : Pleine propriété du bien

            - `U` - Usufruitier : Droit d'usage et de percevoir les revenus du
            bien

            - `N` - Nu-propriétaire : Propriétaire sans droit d'usage ni de
            revenus


            **Baux et locations :**

            - `B` - Bailleur : Propriétaire qui loue le bien

            - `R` - Preneur : Locataire du bien

            - `V` - Bailleur à réhabilitation : Propriétaire dans le cadre d'un
            bail à réhabilitation

            - `W` - Preneur à réhabilitation : Locataire dans le cadre d'un bail
            à réhabilitation

            - `A` - Locataire-Attributaire : Locataire avec attribution
            spécifique

            - `E` - Emphytéote : Titulaire d'un bail emphytéotique (bail de
            longue durée 18-99 ans)

            - `K` - Antichrésiste : Créancier bénéficiant d'un droit
            d'antichrèse


            **Gestion et administration :**

            - `F` - Foncier : Propriétaire foncier

            - `T` - Tenuyer : Titulaire d'une tenure

            - `D` - Domanier : Relevant du domaine public

            - `G` - Gérant/Mandataire : Personne gérant le bien pour le compte
            d'autrui

            - `Q` - Gestionnaire : Personne assurant la gestion du bien

            - `S` - Syndic : Syndic de copropriété

            - `Z` - Gestion État : Bien géré par l'État


            **Occupation et usage :**

            - `H` - Associé : Associé disposant d'un droit sur le bien

            - `O` - Occupation temporaire : Occupation temporaire du domaine
            public

            - `L` - Fonctionnaire logé : Fonctionnaire bénéficiant d'un logement
            de fonction

            - `J` - Jeune agriculteur : Jeune agriculteur bénéficiaire

            - `M` - Occupant Mayotte : Statut spécifique à Mayotte


            **Cas particuliers :**

            - `X` - La Poste propriétaire : La Poste en tant que propriétaire

            - `Y` - La Poste occupant : La Poste en tant qu'occupant

            - `C` - Fiduciaire : Propriétaire dans le cadre d'une fiducie
          required: false
          schema:
            type: string
            example: ''
        - name: forme_juridique
          in: query
          description: >-
            Code de la forme juridique de la société (ex: 5710 pour SAS, 5498
            pour SARL). Filtre les propriétaires selon leur statut juridique.
            Accepte plusieurs valeurs séparées par des virgules (ex:
            '5710,5498').
          required: false
          schema:
            type: string
            example: ''
        - name: type_bien
          in: query
          description: >-
            Type de bien possédé par le propriétaire.


            **Liste complète des types possibles :**


            - `0` - LOCAL : Bien bâti (appartement, maison, local commercial,
            etc.)

            - `1` - PARCELLE : Terrain non bâti (parcelle cadastrale sans
            construction)
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
            example: ''
        - name: code_postal
          in: query
          description: >-
            Code postal (5 chiffres) pour filtrer les propriétaires par
            localisation de leurs biens.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher les
            propriétaires liés à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher les
            propriétaires liés à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: code_parcelle
          in: query
          description: >-
            Code cadastral de la parcelle (Identifiant Cadastral - 14
            caractères). Accepte plusieurs valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: '75056'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Note : le champ 'parcelles'
            est limité à un maximum de 10 parcelles par propriétaire. Exemple :
            champs=siren,denomination,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - siren
                - denomination
                - code_droit
                - libelle_code_droit
                - forme_juridique
                - forme_juridique_abregee
                - type_bien
                - adresse_complete
                - adresse_numero
                - adresse_indice_repetition
                - adresse_nature_voie
                - adresse_nom_voie
                - identification_local
                - subdivision_fiscale
                - subdivision_nature_culture
                - subdivision_superficie
                - parcelles
                - municipalite
                - centre
            default:
              - siren
              - denomination
              - code_droit
              - libelle_code_droit
              - municipalite
        - name: champ_tri
          in: query
          description: >-
            Champ utilisé pour trier les résultats. Si vous triez sur
            'denomination' ET que vous avez aussi le filtre 'denomination'
            activé, le tri se fera automatiquement par similarité au lieu d'un
            tri alphabétique classique. Utilisez 'DESC' pour obtenir les
            résultats les plus similaires en premier, 'ASC' pour les moins
            similaires.
          required: false
          schema:
            type: string
            default: siren
            enum:
              - siren
              - denomination
              - type_bien
              - forme_juridique
              - forme_juridique_abregee
              - adresse_numero
              - adresse_nom_voie
              - adresse_nature_voie
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement. Pour les propriétaires, seul 'centre' est
            disponible (point central de la première parcelle), car un
            propriétaire n'a pas de géométrie propre. Ce paramètre est ignoré en
            format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    siren:
                      description: Numéro SIREN du propriétaire
                      type: string
                      example: '123456789'
                    denomination:
                      description: Dénomination sociale du propriétaire
                      type: string
                      example: SOCIETE EXEMPLE SAS
                    code_droit:
                      description: Code de droit (P=Propriétaire, U=Usufruitier, etc.)
                      type: string
                      example: P
                    libelle_code_droit:
                      description: Libellé lisible du code de droit
                      type: string
                      example: Propriétaire
                    forme_juridique:
                      description: Forme juridique complète de la société
                      type: string
                      example: Société par actions simplifiée
                    forme_juridique_abregee:
                      description: Code abrégé de la forme juridique
                      type: string
                      example: '5710'
                    type_bien:
                      description: 'Type de bien : LOCAL (bâti) ou PARCELLE (non-bâti)'
                      type: string
                      example: LOCAL
                    adresse_complete:
                      description: Adresse complète du bien (champ calculé)
                      type: string
                      example: 15 Bis Avenue des Champs-Élysées
                    adresse_numero:
                      description: Numéro de voirie
                      type: string
                      example: '15'
                    adresse_indice_repetition:
                      description: Indice de répétition (Bis, Ter, etc.)
                      type: string
                      example: Bis
                    adresse_nature_voie:
                      description: Nature de la voie (rue, avenue, boulevard, etc.)
                      type: string
                      example: Avenue
                    adresse_nom_voie:
                      description: Nom de la voie
                      type: string
                      example: des Champs-Élysées
                    identification_local:
                      description: >-
                        Identification du local (uniquement pour
                        type_bien=LOCAL)
                      properties:
                        batiment:
                          type: string
                          example: A
                        entree:
                          type: string
                          example: '2'
                        niveau:
                          type: string
                          example: '3'
                        porte:
                          type: integer
                          example: 12
                      type: object
                    subdivision_fiscale:
                      description: Subdivision fiscale (uniquement pour type_bien=PARCELLE)
                      type: string
                      example: A
                    subdivision_nature_culture:
                      description: >-
                        Nature de culture de la subdivision fiscale (uniquement
                        pour type_bien=PARCELLE)
                      type: string
                      example: Terres
                    subdivision_superficie:
                      description: >-
                        Superficie de la subdivision fiscale en centiares
                        (uniquement pour type_bien=PARCELLE)
                      type: integer
                      example: 15000
                    parcelles:
                      description: >-
                        Liste des parcelles cadastrales du propriétaire (limitée
                        à 10 parcelles)
                      type: array
                      items:
                        properties:
                          code:
                            description: Code cadastral de la parcelle
                            type: string
                            example: 750010001AB0001
                          section:
                            description: Code section
                            type: string
                            example: AB
                          numero:
                            description: Numéro de parcelle
                            type: string
                            example: '0001'
                          superficie:
                            description: Superficie en m²
                            type: number
                            example: 450.5
                        type: object
                    municipalite:
                      description: Informations sur la commune (première parcelle)
                      properties:
                        code:
                          description: Code INSEE de la commune
                          type: string
                          example: '75056'
                        nom:
                          description: Nom de la commune
                          type: string
                          example: Paris
                        codes_postaux:
                          description: Liste de tous les codes postaux de la commune
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                            - '75002'
                            - '75003'
                      type: object
                    centre:
                      description: >-
                        Coordonnées du centre géographique de la première
                        parcelle (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                  type: object
                example:
                  - siren: '123456789'
                    denomination: SOCIETE EXEMPLE SAS
                    code_droit: P
                    libelle_code_droit: Propriétaire
                    forme_juridique: Société par actions simplifiée
                    forme_juridique_abregee: '5710'
                    type_bien: LOCAL
                    adresse_complete: 15 Bis Avenue des Champs-Élysées
                    adresse_numero: '15'
                    adresse_indice_repetition: Bis
                    adresse_nature_voie: Avenue
                    adresse_nom_voie: des Champs-Élysées
                    identification_local:
                      batiment: A
                      entree: '2'
                      niveau: '3'
                      porte: 12
                    subdivision_fiscale: J
                    subdivision_nature_culture: S
                    subdivision_superficie: 450.5
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 450.5
                      - code: 750010001AB0002
                        section: AB
                        numero: '0002'
                        superficie: 320.8
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie du propriétaire (Point si geometrie=centre
                            - centre de la première parcelle)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            siren:
                              description: Numéro SIREN du propriétaire
                              type: string
                              example: '123456789'
                            denomination:
                              description: Dénomination sociale du propriétaire
                              type: string
                              example: SOCIETE EXEMPLE SAS
                            code_droit:
                              description: >-
                                Code de droit (P=Propriétaire, U=Usufruitier,
                                etc.)
                              type: string
                              example: P
                            libelle_code_droit:
                              description: Libellé lisible du code de droit
                              type: string
                              example: Propriétaire
                            forme_juridique:
                              description: Forme juridique complète de la société
                              type: string
                              example: Société par actions simplifiée
                            forme_juridique_abregee:
                              description: Code abrégé de la forme juridique
                              type: string
                              example: '5710'
                            type_bien:
                              description: >-
                                Type de bien : LOCAL (bâti) ou PARCELLE
                                (non-bâti)
                              type: string
                              example: LOCAL
                            adresse_complete:
                              description: Adresse complète du bien (champ calculé)
                              type: string
                              example: 15 Bis Avenue des Champs-Élysées
                            adresse_numero:
                              description: Numéro de voirie
                              type: string
                              example: '15'
                            adresse_indice_repetition:
                              description: Indice de répétition (Bis, Ter, etc.)
                              type: string
                              example: Bis
                            adresse_nature_voie:
                              description: Nature de la voie (rue, avenue, boulevard, etc.)
                              type: string
                              example: Avenue
                            adresse_nom_voie:
                              description: Nom de la voie
                              type: string
                              example: des Champs-Élysées
                            identification_local:
                              description: >-
                                Identification du local (uniquement pour
                                type_bien=LOCAL)
                              properties:
                                batiment:
                                  type: string
                                  example: A
                                entree:
                                  type: string
                                  example: '2'
                                niveau:
                                  type: string
                                  example: '3'
                                porte:
                                  type: integer
                                  example: 12
                              type: object
                            subdivision_fiscale:
                              description: >-
                                Subdivision fiscale (uniquement pour
                                type_bien=PARCELLE)
                              type: string
                              example: A
                            subdivision_nature_culture:
                              description: >-
                                Nature de culture de la subdivision fiscale
                                (uniquement pour type_bien=PARCELLE)
                              type: string
                              example: Terres
                            subdivision_superficie:
                              description: >-
                                Superficie de la subdivision fiscale en
                                centiares (uniquement pour type_bien=PARCELLE)
                              type: integer
                              example: 15000
                            parcelles:
                              description: >-
                                Liste des parcelles cadastrales du propriétaire
                                (limitée à 10 parcelles)
                              type: array
                              items:
                                properties:
                                  code:
                                    description: Code cadastral de la parcelle
                                    type: string
                                    example: 750010001AB0001
                                  section:
                                    description: Code section
                                    type: string
                                    example: AB
                                  numero:
                                    description: Numéro de parcelle
                                    type: string
                                    example: '0001'
                                  superficie:
                                    description: Superficie en m²
                                    type: number
                                    example: 450.5
                                type: object
                            municipalite:
                              description: Informations sur la commune (première parcelle)
                              properties:
                                code:
                                  description: Code INSEE de la commune
                                  type: string
                                  example: '75056'
                                nom:
                                  description: Nom de la commune
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: >-
                                    Liste de tous les codes postaux de la
                                    commune
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                                    - '75002'
                                    - '75003'
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        siren: '123456789'
                        denomination: SOCIETE EXEMPLE SAS
                        code_droit: P
                        libelle_code_droit: Propriétaire
                        forme_juridique: Société par actions simplifiée
                        forme_juridique_abregee: '5710'
                        type_bien: LOCAL
                        adresse_complete: 15 Bis Avenue des Champs-Élysées
                        adresse_numero: '15'
                        adresse_indice_repetition: Bis
                        adresse_nature_voie: Avenue
                        adresse_nom_voie: des Champs-Élysées
                        identification_local:
                          batiment: A
                          entree: '2'
                          niveau: '3'
                          porte: '12'
                        subdivision_fiscale: J
                        subdivision_nature_culture: S
                        subdivision_superficie: 450.5
                        parcelles:
                          - code: 750010001AB0001
                            section: AB
                            numero: '0001'
                            superficie: 450.5
                          - code: 750010001AB0002
                            section: AB
                            numero: '0002'
                            superficie: 320.8
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75003'
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun propriétaire trouvé
      security:
        - bearer:
            - '*'
  /api/v1/coproprietes:
    get:
      tags:
        - Données foncières & immobilières
      summary: Rechercher des copropriétés
      description: >-
        Permet de rechercher des copropriétés immatriculées au registre national
        des copropriétés. Les résultats peuvent être filtrés par localisation
        (code postal, commune, parcelle), caractéristiques (nombre de lots, type
        de syndic) ou statut (mandat, arrêtés). Les résultats peuvent être
        retournés au format JSON ou GeoJSON.
      operationId: getCoOwners
      parameters:
        - name: immatriculation
          in: query
          description: >-
            Numéro d'immatriculation de la copropriété au registre national
            (identifiant unique). Accepte plusieurs valeurs séparées par des
            virgules (ex: '123456789012,987654321098').
          required: false
          schema:
            type: string
            example: ''
        - name: nom
          in: query
          description: Nom d'usage de la copropriété (recherche par similarité).
          required: false
          schema:
            type: string
            example: ''
        - name: type_syndic
          in: query
          description: >-
            Type de syndic gérant la copropriété. Accepte plusieurs valeurs
            séparées par des virgules (ex: '1,2').


            **Liste complète des types possibles :**


            - `1` - Bénévole : Syndic non professionnel (copropriétaire élu)

            - `2` - Professionnel : Syndic professionnel (société ou agent
            immobilier)

            - `3` - Non connu : Type de syndic non renseigné
          required: false
          schema:
            type: string
            example: ''
        - name: mandat
          in: query
          description: >-
            Statut du mandat du syndic. Accepte plusieurs valeurs séparées par
            des virgules (ex: '1,3').


            **Liste complète des statuts possibles :**


            - `1` - Mandat en cours : Le syndic a un mandat actif et valide

            - `2` - Pas de mandat en cours : Aucun syndic actuellement en
            fonction

            - `3` - Mandat expiré avec successeur déclaré : Mandat terminé avec
            nouveau syndic désigné

            - `4` - Mandat expiré sans successeur déclaré : Mandat terminé sans
            désignation de nouveau syndic
          required: false
          schema:
            type: string
            example: ''
        - name: residence_service
          in: query
          description: Résidence-services (article 41 de la loi du 10 juillet 1965).
          required: false
          schema:
            type: boolean
        - name: syndic_cooperatif
          in: query
          description: Syndicat coopératif (article 14 de la loi de 1965).
          required: false
          schema:
            type: boolean
        - name: syndic_principal
          in: query
          description: >-
            Syndicat principal (true) ou secondaire (false) selon l'article 27
            de la loi de 1965.
          required: false
          schema:
            type: boolean
        - name: nb_lot_min
          in: query
          description: Nombre minimum de lots total.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lot_max
          in: query
          description: Nombre maximum de lots total.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lot_hab_min
          in: query
          description: Nombre minimum de lots d'habitation.
          required: false
          schema:
            type: integer
            example: ''
        - name: nb_lot_hab_max
          in: query
          description: Nombre maximum de lots d'habitation.
          required: false
          schema:
            type: integer
            example: ''
        - name: code_postal
          in: query
          description: >-
            Code postal (5 chiffres) pour filtrer les copropriétés par
            localisation.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher les
            copropriétés liées à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher les
            copropriétés liées à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: code_parcelle
          in: query
          description: >-
            Code cadastral de la parcelle (Identifiant Cadastral - 14
            caractères). Accepte plusieurs valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: '75056'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Note : le champ 'parcelles'
            est limité à un maximum de 10 parcelles par copropriété. Exemple :
            champs=immatriculation,nom,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - immatriculation
                - nom
                - epci
                - type_syndic
                - mandat
                - adresse_complete
                - adresse_comp1
                - adresse_comp2
                - adresse_comp3
                - nb_adresse_comp
                - date_reglement
                - residence_service
                - syndic_cooperatif
                - syndic_principal
                - num_syndic_principal
                - nb_asl
                - nb_aful
                - nb_union
                - nb_lot
                - nb_lot_hab_bur_com
                - nb_lot_hab
                - nb_lot_stationement
                - nb_arrete_sante
                - nb_arrete_peril
                - nb_arrete_equipement
                - syndic
                - parcelles
                - municipalite
                - centre
            default:
              - immatriculation
              - nom
              - nb_lot
              - nb_lot_hab
              - municipalite
        - name: champ_tri
          in: query
          description: >-
            Champ utilisé pour trier les résultats. Si vous triez sur 'nom' ET
            que vous avez aussi le filtre 'nom' activé, le tri se fera
            automatiquement par similarité au lieu d'un tri alphabétique
            classique. Utilisez 'DESC' pour obtenir les résultats les plus
            similaires en premier, 'ASC' pour les moins similaires.
          required: false
          schema:
            type: string
            default: immatriculation
            enum:
              - immatriculation
              - nom
              - type_syndic
              - mandat
              - date_reglement
              - nb_lot
              - nb_lot_hab
              - nb_lot_stationement
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement. Pour les copropriétés, seul 'centre' est
            disponible (point géographique de la copropriété ou centre de la
            première parcelle). Ce paramètre est ignoré en format JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    immatriculation:
                      description: Numéro d'immatriculation au registre national
                      type: string
                      example: AA1234567
                    nom:
                      description: Nom d'usage de la copropriété
                      type: string
                      example: Résidence Les Jardins
                    epci:
                      description: >-
                        Code EPCI (Établissement Public de Coopération
                        Intercommunale)
                      type: string
                      example: '200054781'
                    type_syndic:
                      description: Type de syndic
                      type: string
                      example: Professionnel
                    mandat:
                      description: Statut du mandat
                      type: string
                      example: Mandat en cours
                    adresse_complete:
                      description: Adresse complète de la copropriété
                      type: string
                      example: 15 Avenue des Champs-Élysées 75008 Paris
                    adresse_comp1:
                      description: Complément d'adresse 1
                      type: string
                      example: Bâtiment A
                    adresse_comp2:
                      description: Complément d'adresse 2
                      type: string
                      example: null
                    adresse_comp3:
                      description: Complément d'adresse 3
                      type: string
                      example: null
                    nb_adresse_comp:
                      description: Nombre de compléments d'adresse
                      type: integer
                      example: 1
                    date_reglement:
                      description: Date du règlement de copropriété
                      type: string
                      format: date
                      example: '2015-06-15'
                    residence_service:
                      description: Résidence-services
                      type: boolean
                      example: false
                    syndic_cooperatif:
                      description: Syndicat coopératif
                      type: boolean
                      example: false
                    syndic_principal:
                      description: Syndicat principal
                      type: boolean
                      example: true
                    num_syndic_principal:
                      description: Numéro du syndicat principal si secondaire
                      type: string
                      example: null
                    nb_asl:
                      description: Nombre d'ASL
                      type: integer
                      example: 0
                    nb_aful:
                      description: Nombre d'AFUL
                      type: integer
                      example: 0
                    nb_union:
                      description: Nombre d'unions de syndicats
                      type: integer
                      example: 0
                    nb_lot:
                      description: Nombre total de lots
                      type: integer
                      example: 120
                    nb_lot_hab_bur_com:
                      description: Nombre de lots habitation/bureaux/commerces
                      type: integer
                      example: 100
                    nb_lot_hab:
                      description: Nombre de lots d'habitation
                      type: integer
                      example: 95
                    nb_lot_stationement:
                      description: Nombre de lots de stationnement
                      type: integer
                      example: 80
                    nb_arrete_sante:
                      description: Nombre d'arrêtés de mise en sécurité sanitaire
                      type: integer
                      example: 0
                    nb_arrete_peril:
                      description: Nombre d'arrêtés de péril
                      type: integer
                      example: 0
                    nb_arrete_equipement:
                      description: Nombre d'arrêtés d'équipement
                      type: integer
                      example: 0
                    syndic:
                      description: Informations sur le syndic
                      properties:
                        siren:
                          type: string
                          example: '123456789'
                        denomination:
                          type: string
                          example: SYNDIC PROFESSIONNEL SAS
                      type: object
                    parcelles:
                      description: Liste des parcelles cadastrales (limitée à 10)
                      type: array
                      items:
                        properties:
                          code:
                            type: string
                            example: 750010001AB0001
                          section:
                            type: string
                            example: AB
                          numero:
                            type: string
                            example: '0001'
                          superficie:
                            type: number
                            example: 1250.5
                        type: object
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          type: string
                          example: '75056'
                        nom:
                          type: string
                          example: Paris
                        codes_postaux:
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                            - '75008'
                      type: object
                    centre:
                      description: Centre géographique (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                  type: object
                example:
                  - immatriculation: AA1234567
                    nom: Résidence Les Jardins
                    epci: '200054781'
                    type_syndic: Professionnel
                    mandat: Mandat en cours
                    adresse_complete: 15 Avenue des Champs-Élysées 75008 Paris
                    adresse_comp1: Bâtiment A
                    adresse_comp2: null
                    adresse_comp3: null
                    nb_adresse_comp: 1
                    date_reglement: '2015-06-15'
                    residence_service: false
                    syndic_cooperatif: false
                    syndic_principal: true
                    num_syndic_principal: null
                    nb_asl: 0
                    nb_aful: 0
                    nb_union: 0
                    nb_lot: 120
                    nb_lot_hab_bur_com: 100
                    nb_lot_hab: 95
                    nb_lot_stationement: 80
                    nb_arrete_sante: 0
                    nb_arrete_peril: 0
                    nb_arrete_equipement: 0
                    syndic:
                      siren: '123456789'
                      denomination: SYNDIC PROFESSIONNEL SAS
                    parcelles:
                      - code: 750010001AB0001
                        section: AB
                        numero: '0001'
                        superficie: 1250.5
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75008'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de la copropriété (Point - centre
                            géographique)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            immatriculation:
                              description: Numéro d'immatriculation au registre
                              type: string
                              example: AA1234567
                            nom:
                              description: Nom d'usage de la copropriété
                              type: string
                              example: Résidence Les Jardins
                            epci:
                              description: >-
                                Code EPCI (Établissement public de coopération
                                intercommunale)
                              type: string
                              example: '200054781'
                            type_syndic:
                              description: >-
                                Type de syndic (Bénévole, Professionnel, Non
                                connu)
                              type: string
                              example: Professionnel
                            mandat:
                              description: Statut du mandat du syndic
                              type: string
                              example: Mandat en cours
                            adresse_complete:
                              description: >-
                                Adresse de référence (première adresse du
                                règlement de copropriété)
                              type: string
                              example: 15 Avenue des Champs-Élysées 75008 Paris
                            adresse_comp1:
                              description: Adresse complémentaire 1
                              type: string
                              example: ''
                            adresse_comp2:
                              description: Adresse complémentaire 2
                              type: string
                              example: ''
                            adresse_comp3:
                              description: Adresse complémentaire 3
                              type: string
                              example: ''
                            nb_adresse_comp:
                              description: Nombre d'adresses complémentaires
                              type: integer
                              example: 0
                            date_reglement:
                              description: Date du règlement de copropriété
                              type: string
                              format: date
                              example: '2015-06-15'
                            residence_service:
                              description: Résidence-services (article 41 loi 1965)
                              type: boolean
                              example: false
                            syndic_cooperatif:
                              description: Syndicat coopératif (article 14 loi 1965)
                              type: boolean
                              example: false
                            syndic_principal:
                              description: Syndicat principal (true) ou secondaire (false)
                              type: boolean
                              example: true
                            num_syndic_principal:
                              description: >-
                                Si secondaire, numéro d'immatriculation du
                                principal
                              type: string
                              example: ''
                            nb_asl:
                              description: Nombre d'ASL rattachées
                              type: integer
                              example: 0
                            nb_aful:
                              description: Nombre d'AFUL rattachées
                              type: integer
                              example: 0
                            nb_union:
                              description: Nombre d'unions de syndicats rattachées
                              type: integer
                              example: 0
                            nb_lot:
                              description: Nombre total de lots
                              type: integer
                              example: 120
                            nb_lot_hab_bur_com:
                              description: Nombre de lots habitation/bureaux/commerces
                              type: integer
                              example: 100
                            nb_lot_hab:
                              description: Nombre de lots d'habitation
                              type: integer
                              example: 95
                            nb_lot_stationement:
                              description: Nombre de lots de stationnement
                              type: integer
                              example: 80
                            nb_arrete_sante:
                              description: Nombre d'arrêtés santé publique en cours
                              type: integer
                              example: 0
                            nb_arrete_peril:
                              description: Nombre d'arrêtés de péril en cours
                              type: integer
                              example: 0
                            nb_arrete_equipement:
                              description: Nombre d'arrêtés équipements en cours
                              type: integer
                              example: 0
                            syndic:
                              description: Informations sur le syndic (personne morale)
                              properties:
                                siren:
                                  type: string
                                  example: '123456789'
                                denomination:
                                  type: string
                                  example: SYNDIC PROFESSIONNEL SAS
                              type: object
                            parcelles:
                              description: Liste des parcelles cadastrales (limitée à 10)
                              type: array
                              items:
                                properties:
                                  code:
                                    type: string
                                    example: 750010001AB0001
                                  section:
                                    type: string
                                    example: AB
                                  numero:
                                    type: string
                                    example: '0001'
                                  superficie:
                                    type: number
                                    example: 1250.5
                                type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        immatriculation: AA1234567
                        nom: Résidence Les Jardins
                        epci: '200054781'
                        type_syndic: Professionnel
                        mandat: Mandat en cours
                        adresse_complete: 15 Avenue des Champs-Élysées 75008 Paris
                        adresse_comp1: Bâtiment A
                        adresse_comp2: null
                        adresse_comp3: null
                        nb_adresse_comp: 1
                        date_reglement: '2015-06-15'
                        residence_service: false
                        syndic_cooperatif: false
                        syndic_principal: true
                        num_syndic_principal: null
                        nb_asl: 0
                        nb_aful: 0
                        nb_union: 0
                        nb_lot: 120
                        nb_lot_hab_bur_com: 100
                        nb_lot_hab: 95
                        nb_lot_stationement: 80
                        nb_arrete_sante: 0
                        nb_arrete_peril: 0
                        nb_arrete_equipement: 0
                        syndic:
                          siren: '123456789'
                          denomination: SYNDIC PROFESSIONNEL SAS
                        parcelles:
                          - code: 750010001AB0001
                            section: AB
                            numero: '0001'
                            superficie: 1250.5
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75008'
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucune copropriété trouvée
      security:
        - bearer:
            - '*'
  /api/v1/occupants:
    get:
      tags:
        - Données foncières & immobilières
      summary: Rechercher des occupants (établissements/entreprises)
      description: >-
        Permet de rechercher des occupants établissements (entreprises,
        commerces, etc.) présents sur les parcelles cadastrales par différents
        critères : SIRET, SIREN, dénomination, activité, code postal, parcelles
        cadastrales, codes INSEE. Les résultats peuvent être retournés au format
        JSON ou GeoJSON.
      operationId: getOccupants
      parameters:
        - name: siret
          in: query
          description: >-
            Numéro SIRET de l'établissement (14 chiffres) - identifiant unique
            de l'établissement. Accepte plusieurs valeurs séparées par des
            virgules (ex: '12345678901234,98765432109876').
          required: false
          schema:
            type: string
            example: ''
        - name: siren
          in: query
          description: >-
            Numéro SIREN de l'entreprise (9 chiffres) - identifiant unique de
            l'unité légale. Accepte plusieurs valeurs séparées par des virgules
            (ex: '123456789,987654321').
          required: false
          schema:
            type: string
            example: ''
        - name: denomination_complete
          in: query
          description: >-
            Dénomination complète de l'établissement (champ calculé - recherche
            par similarité).
          required: false
          schema:
            type: string
            example: ''
        - name: activite_principale
          in: query
          description: >-
            Code d'activité principale NAF/APE (ex: 10.71C pour boulangerie).
            Accepte plusieurs valeurs séparées par des virgules (ex:
            '10.71C,56.10A').
          required: false
          schema:
            type: string
            example: ''
        - name: etat_administratif
          in: query
          description: |-
            État administratif de l'établissement.

            **Liste complète des états possibles :**

            - `0` - Actif : Établissement en activité
            - `1` - Fermé : Établissement fermé ou radié
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
            example: '0'
        - name: etablissement_siege
          in: query
          description: >-
            Filtre pour les établissements siège uniquement (true) ou non-sièges
            (false).
          required: false
          schema:
            type: boolean
        - name: tranche_effectifs
          in: query
          description: >-
            Tranche d'effectifs salariés de l'établissement. Accepte plusieurs
            valeurs séparées par des virgules (ex: '11,12,21').


            **Liste complète des tranches possibles :**


            **Très petites structures :**

            - `0` - 0 salarié : Établissement sans salarié

            - `1` - 1 ou 2 salariés

            - `2` - 3 à 5 salariés

            - `3` - 6 à 9 salariés


            **Petites entreprises :**

            - `11` - 10 à 19 salariés

            - `12` - 20 à 49 salariés


            **Moyennes entreprises :**

            - `21` - 50 à 99 salariés

            - `22` - 100 à 199 salariés

            - `31` - 200 à 249 salariés

            - `32` - 250 à 499 salariés


            **Grandes entreprises :**

            - `41` - 500 à 999 salariés

            - `42` - 1 000 à 1 999 salariés

            - `51` - 2 000 à 4 999 salariés

            - `52` - 5 000 à 9 999 salariés

            - `53` - 10 000 salariés et plus
          required: false
          schema:
            type: string
            example: ''
        - name: code_postal
          in: query
          description: >-
            Code postal (5 chiffres) pour filtrer les occupants par
            localisation.
          required: false
          schema:
            type: string
            example: ''
        - name: lat
          in: query
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher les occupants
            liés à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 90
            minimum: -90
            example: ''
        - name: lon
          in: query
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher les occupants
            liés à une parcelle contenant ce point.
          required: false
          schema:
            type: number
            format: float
            maximum: 180
            minimum: -180
            example: ''
        - name: code_parcelle
          in: query
          description: >-
            Code cadastral de la parcelle (Identifiant Cadastral - 14
            caractères). Accepte plusieurs valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_section
          in: query
          description: >-
            Code de la section cadastrale (2 caractères). Accepte plusieurs
            valeurs séparées par des virgules.
          required: false
          schema:
            type: string
            example: ''
        - name: code_municipalite
          in: query
          description: Code INSEE de la commune (5 chiffres).
          required: false
          schema:
            type: string
            example: '75056'
        - name: champs
          in: query
          description: >-
            Liste des champs souhaités dans la réponse (séparés par des
            virgules). Si non spécifié, retourne les champs par défaut. Permet
            de personnaliser les données retournées. Exemple :
            champs=siret,siren,denomination_complete,municipalite
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - siret
                - siren
                - nic
                - denomination_complete
                - denomination_usuelle
                - enseigne_1
                - enseigne_2
                - enseigne_3
                - activite_principale
                - activite_principale_registre_metiers
                - nomenclature_activite_principale
                - categorie_activite
                - categorie_parent_activite
                - naf_section
                - naf_division
                - naf_groupe
                - naf_classe
                - naf_sous_classe
                - etat_administratif
                - caractere_employeur
                - tranche_effectifs
                - annee_effectifs
                - date_creation
                - date_debut
                - date_dernier_traitement
                - etablissement_siege
                - statut_diffusion
                - adresse_complete
                - adresse_numero
                - adresse_indice_repetition
                - adresse_nom_voie
                - adresse_code_postal
                - parcelle
                - municipalite
                - centre
            default:
              - siret
              - siren
              - denomination_complete
              - activite_principale
              - etat_administratif
              - municipalite
        - name: champ_tri
          in: query
          description: >-
            Champ utilisé pour trier les résultats. Si vous triez sur
            'denomination_complete' ET que vous avez aussi le filtre
            'denomination_complete' activé, le tri se fera automatiquement par
            similarité au lieu d'un tri alphabétique classique. Utilisez 'DESC'
            pour obtenir les résultats les plus similaires en premier, 'ASC'
            pour les moins similaires.
          required: false
          schema:
            type: string
            default: siret
            enum:
              - siret
              - siren
              - denomination_complete
              - activite_principale
              - etat_administratif
              - tranche_effectifs
              - date_creation
        - name: ordre_tri
          in: query
          description: Direction du tri (ascendant ou descendant).
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: limite
          in: query
          description: 'Nombre de résultats par page. Par défaut: 10. Maximum: 50.'
          required: false
          schema:
            type: integer
            default: 10
            maximum: 50
            minimum: 1
        - name: curseur
          in: query
          description: >-
            Curseur de pagination pour accéder à la page suivante. Utiliser la
            valeur retournée dans l'en-tête 'X-Pagination-Next-Cursor' de la
            réponse précédente.
          required: false
          schema:
            type: string
            example: ''
        - name: format
          in: query
          description: >-
            Format de réponse attendu : 'json' pour un tableau JSON simple,
            'geojson' pour un FeatureCollection GeoJSON.
          required: false
          schema:
            type: string
            default: json
            enum:
              - geojson
              - json
        - name: geometrie
          in: query
          description: >-
            Type de géométrie à utiliser pour la sortie géographique en format
            GeoJSON uniquement. Pour les occupants, seul 'centre' est disponible
            (point central de la parcelle). Ce paramètre est ignoré en format
            JSON.
          required: false
          schema:
            type: string
            default: centre
            enum:
              - centre
      responses:
        '200':
          description: Succès - Format varie selon le paramètre 'format' (geojson ou json)
          headers:
            X-Pagination-Limit:
              description: Nombre de résultats par page
              schema:
                type: integer
                example: 10
            X-Pagination-Cursor:
              description: Curseur actuel de pagination
              schema:
                type: string
                example: ''
            X-Pagination-Next-Cursor:
              description: >-
                Curseur pour la page suivante (vide s'il n'y a pas de page
                suivante)
              schema:
                type: string
                example: eyJpZCI6MTAwfQ==
            X-Pagination-Has-More:
              description: Indique s'il y a plus de résultats disponibles
              schema:
                type: string
                enum:
                  - 'true'
                  - 'false'
                example: 'true'
          content:
            application/json:
              schema:
                title: JSON Array
                description: Format JSON simple (format=json)
                type: array
                items:
                  properties:
                    siret:
                      description: Numéro SIRET de l'établissement (14 chiffres)
                      type: string
                      example: '12345678901234'
                    siren:
                      description: Numéro SIREN de l'unité légale (9 chiffres)
                      type: string
                      example: '123456789'
                    nic:
                      description: Numéro interne de classement (5 chiffres)
                      type: string
                      example: '01234'
                    denomination_complete:
                      description: Dénomination complète de l'établissement - Champ calculé
                      type: string
                      example: BOULANGERIE PATISSERIE PARIS
                    denomination_usuelle:
                      description: Dénomination usuelle (nom commercial)
                      type: string
                      example: null
                      nullable: true
                    enseigne_1:
                      description: Première enseigne
                      type: string
                      example: null
                      nullable: true
                    enseigne_2:
                      description: Deuxième enseigne
                      type: string
                      example: null
                      nullable: true
                    enseigne_3:
                      description: Troisième enseigne
                      type: string
                      example: null
                      nullable: true
                    activite_principale:
                      description: Code NAF/APE de l'activité principale
                      type: string
                      example: 10.71C
                    activite_principale_registre_metiers:
                      description: Code activité du registre des métiers
                      type: string
                      example: null
                      nullable: true
                    nomenclature_activite_principale:
                      description: Référentiel de l'APE (NAFRev2, etc.)
                      type: string
                      example: NAFRev2
                    categorie_activite:
                      description: Catégorie d'activité
                      type: string
                      example: Boulangerie
                    categorie_parent_activite:
                      description: Catégorie parent d'activité
                      type: string
                      example: Commerce
                    naf_section:
                      description: Section NAF (niveau 1)
                      properties:
                        code:
                          type: string
                          example: C
                        label:
                          type: string
                          example: Industrie manufacturière
                      type: object
                    naf_division:
                      description: Division NAF (niveau 2)
                      properties:
                        code:
                          type: string
                          example: '10'
                        label:
                          type: string
                          example: Industries alimentaires
                      type: object
                    naf_groupe:
                      description: Groupe NAF (niveau 3)
                      properties:
                        code:
                          type: string
                          example: '10.7'
                        label:
                          type: string
                          example: >-
                            Fabrication de produits de boulangerie-pâtisserie et
                            de pâtes alimentaires
                      type: object
                    naf_classe:
                      description: Classe NAF (niveau 4)
                      properties:
                        code:
                          type: string
                          example: '10.71'
                        label:
                          type: string
                          example: Boulangerie et boulangerie-pâtisserie
                      type: object
                    naf_sous_classe:
                      description: Sous-classe NAF (niveau 5)
                      properties:
                        code:
                          type: string
                          example: 10.71C
                        label:
                          type: string
                          example: Boulangerie et boulangerie-pâtisserie
                      type: object
                    etat_administratif:
                      description: 'État : Actif ou Fermé'
                      type: string
                      example: Actif
                    caractere_employeur:
                      description: Indique si l'établissement est employeur
                      type: boolean
                      example: true
                    tranche_effectifs:
                      description: >-
                        Tranche d'effectifs (0=0 salarié, 1=1 ou 2, 2=3 à 5, 3=6
                        à 9, 11=10 à 19, 12=20 à 49, etc.)
                      type: integer
                      example: 3
                      nullable: true
                    annee_effectifs:
                      description: Année de référence des effectifs
                      type: string
                      example: '2021'
                      nullable: true
                    date_creation:
                      description: Date de création (AAAA-MM-JJ)
                      type: string
                      format: date
                      example: '2015-01-01'
                    date_debut:
                      description: Date de début de période (AAAA-MM-JJ)
                      type: string
                      format: date
                      example: '2015-03-01'
                    date_dernier_traitement:
                      description: Date de dernière modification (ISO 8601)
                      type: string
                      format: date-time
                      example: '2023-11-30T10:17:50'
                    etablissement_siege:
                      description: Indique si c'est le siège
                      type: boolean
                      example: true
                    statut_diffusion:
                      description: >-
                        Statut de diffusion.


                        **Liste complète des statuts possibles :**


                        - `0` - Diffusion ouverte : Les données de
                        l'établissement sont publiques et diffusables

                        - `1` - Diffusion opposée : L'établissement s'est opposé
                        à la diffusion de ses données
                      type: integer
                      example: '0'
                    adresse_complete:
                      description: Adresse complète
                      type: string
                      example: 15 RUE DE RIVOLI 75001 PARIS
                    adresse_numero:
                      description: Numéro de voirie
                      type: integer
                      example: 15
                      nullable: true
                    adresse_indice_repetition:
                      description: Indice de répétition (bis, ter, etc.)
                      type: string
                      example: null
                      nullable: true
                    adresse_nom_voie:
                      description: Nom de la voie
                      type: string
                      example: RUE DE RIVOLI
                    adresse_code_postal:
                      description: Code postal
                      type: string
                      example: '75001'
                    parcelle:
                      description: Informations sur la parcelle cadastrale
                      properties:
                        code:
                          description: Code cadastral complet (14 caractères)
                          type: string
                          example: 750560000AB0123
                        section:
                          description: Section cadastrale
                          type: string
                          example: AB
                        numero:
                          description: Numéro de parcelle
                          type: string
                          example: '0123'
                        superficie:
                          description: Superficie de la parcelle en m²
                          type: number
                          format: float
                          example: 1250.5
                      type: object
                    municipalite:
                      description: Informations sur la commune
                      properties:
                        code:
                          description: Code INSEE de la commune
                          type: string
                          example: '75056'
                        nom:
                          description: Nom de la commune
                          type: string
                          example: Paris
                        codes_postaux:
                          description: Liste de tous les codes postaux de la commune
                          type: array
                          items:
                            type: string
                          example:
                            - '75001'
                            - '75002'
                            - '75003'
                            - '75004'
                      type: object
                    centre:
                      description: >-
                        Coordonnées du centre géographique de la parcelle
                        (GeoJSON Point)
                      properties:
                        type:
                          type: string
                          example: Point
                        coordinates:
                          type: array
                          items:
                            type: number
                          example:
                            - 2.3522
                            - 48.8566
                      type: object
                  type: object
                example:
                  - siret: '12345678901234'
                    siren: '123456789'
                    nic: '01234'
                    denomination_complete: BOULANGERIE PATISSERIE PARIS
                    denomination_usuelle: null
                    enseigne_1: null
                    enseigne_2: null
                    enseigne_3: null
                    activite_principale: 10.71C
                    activite_principale_registre_metiers: null
                    nomenclature_activite_principale: NAFRev2
                    categorie_activite: Boulangerie
                    categorie_parent_activite: Commerce
                    naf_section:
                      code: C
                      label: Industrie manufacturière
                    naf_division:
                      code: '10'
                      label: Industries alimentaires
                    naf_groupe:
                      code: '10.7'
                      label: >-
                        Fabrication de produits de boulangerie-pâtisserie et de
                        pâtes alimentaires
                    naf_classe:
                      code: '10.71'
                      label: Boulangerie et boulangerie-pâtisserie
                    naf_sous_classe:
                      code: 10.71C
                      label: Boulangerie et boulangerie-pâtisserie
                    etat_administratif: Actif
                    caractere_employeur: true
                    tranche_effectifs: 3
                    annee_effectifs: '2021'
                    date_creation: '2015-01-01'
                    date_debut: '2015-03-01'
                    date_dernier_traitement: '2023-11-30T10:17:50'
                    etablissement_siege: true
                    statut_diffusion: 0
                    adresse_complete: 15 RUE DE RIVOLI 75001 PARIS
                    adresse_numero: 15
                    adresse_indice_repetition: null
                    adresse_nom_voie: RUE DE RIVOLI
                    adresse_code_postal: '75001'
                    parcelle:
                      code: 750560000AB0123
                      section: AB
                      numero: '0123'
                      superficie: 1250.5
                    municipalite:
                      code: '75056'
                      nom: Paris
                      codes_postaux:
                        - '75001'
                        - '75002'
                        - '75003'
                        - '75004'
                    centre:
                      type: Point
                      coordinates:
                        - 2.3522
                        - 48.8566
            application/geo+json:
              schema:
                title: GeoJSON FeatureCollection
                description: Format GeoJSON (format=geojson)
                properties:
                  type:
                    type: string
                    example: FeatureCollection
                  features:
                    type: array
                    items:
                      properties:
                        type:
                          type: string
                          example: Feature
                        geometry:
                          description: >-
                            Géométrie de l'occupant (Point - centre de la
                            parcelle)
                          properties:
                            type:
                              type: string
                              example: Point
                            coordinates:
                              type: array
                              items:
                                type: number
                              example:
                                - 2.3522
                                - 48.8566
                          type: object
                        properties:
                          properties:
                            siret:
                              description: Numéro SIRET de l'établissement (14 chiffres)
                              type: string
                              example: '12345678901234'
                            siren:
                              description: Numéro SIREN de l'unité légale (9 chiffres)
                              type: string
                              example: '123456789'
                            nic:
                              description: Numéro interne de classement (5 chiffres)
                              type: string
                              example: '01234'
                            denomination_complete:
                              description: >-
                                Dénomination complète de l'établissement - Champ
                                calculé
                              type: string
                              example: BOULANGERIE PATISSERIE PARIS
                            denomination_usuelle:
                              description: Dénomination usuelle (nom commercial)
                              type: string
                              example: null
                              nullable: true
                            enseigne_1:
                              description: Première enseigne
                              type: string
                              example: null
                              nullable: true
                            enseigne_2:
                              description: Deuxième enseigne
                              type: string
                              example: null
                              nullable: true
                            enseigne_3:
                              description: Troisième enseigne
                              type: string
                              example: null
                              nullable: true
                            activite_principale:
                              description: Code NAF/APE de l'activité principale
                              type: string
                              example: 10.71C
                            activite_principale_registre_metiers:
                              description: Code activité du registre des métiers
                              type: string
                              example: null
                              nullable: true
                            nomenclature_activite_principale:
                              description: Référentiel de l'APE (NAFRev2, etc.)
                              type: string
                              example: NAFRev2
                            categorie_activite:
                              description: Catégorie d'activité
                              type: string
                              example: Boulangerie
                            categorie_parent_activite:
                              description: Catégorie parent d'activité
                              type: string
                              example: Commerce
                            naf_section:
                              description: Section NAF (niveau 1)
                              properties:
                                code:
                                  type: string
                                  example: C
                                label:
                                  type: string
                                  example: Industrie manufacturière
                              type: object
                            naf_division:
                              description: Division NAF (niveau 2)
                              properties:
                                code:
                                  type: string
                                  example: '10'
                                label:
                                  type: string
                                  example: Industries alimentaires
                              type: object
                            naf_groupe:
                              description: Groupe NAF (niveau 3)
                              properties:
                                code:
                                  type: string
                                  example: '10.7'
                                label:
                                  type: string
                                  example: >-
                                    Fabrication de produits de
                                    boulangerie-pâtisserie et de pâtes
                                    alimentaires
                              type: object
                            naf_classe:
                              description: Classe NAF (niveau 4)
                              properties:
                                code:
                                  type: string
                                  example: '10.71'
                                label:
                                  type: string
                                  example: Boulangerie et boulangerie-pâtisserie
                              type: object
                            naf_sous_classe:
                              description: Sous-classe NAF (niveau 5)
                              properties:
                                code:
                                  type: string
                                  example: 10.71C
                                label:
                                  type: string
                                  example: Boulangerie et boulangerie-pâtisserie
                              type: object
                            etat_administratif:
                              description: 'État : Actif ou Fermé'
                              type: string
                              example: Actif
                            caractere_employeur:
                              description: Indique si l'établissement est employeur
                              type: boolean
                              example: true
                            tranche_effectifs:
                              description: >-
                                Tranche d'effectifs (0=0 salarié, 1=1 ou 2, 2=3
                                à 5, 3=6 à 9, 11=10 à 19, 12=20 à 49, etc.)
                              type: integer
                              example: 3
                              nullable: true
                            annee_effectifs:
                              description: Année de référence des effectifs
                              type: string
                              example: '2021'
                              nullable: true
                            date_creation:
                              description: Date de création (AAAA-MM-JJ)
                              type: string
                              format: date
                              example: '2015-01-01'
                            date_debut:
                              description: Date de début de période (AAAA-MM-JJ)
                              type: string
                              format: date
                              example: '2015-03-01'
                            date_dernier_traitement:
                              description: Date de dernière modification (ISO 8601)
                              type: string
                              format: date-time
                              example: '2023-11-30T10:17:50'
                            etablissement_siege:
                              description: Indique si c'est le siège
                              type: boolean
                              example: true
                            statut_diffusion:
                              description: >-
                                Statut de diffusion.


                                **Liste complète des statuts possibles :**


                                - `0` - Diffusion ouverte : Les données de
                                l'établissement sont publiques et diffusables

                                - `1` - Diffusion opposée : L'établissement
                                s'est opposé à la diffusion de ses données
                              type: integer
                              example: '0'
                            adresse_complete:
                              description: Adresse complète
                              type: string
                              example: 15 RUE DE RIVOLI 75001 PARIS
                            adresse_numero:
                              description: Numéro de voirie
                              type: integer
                              example: 15
                              nullable: true
                            adresse_indice_repetition:
                              description: Indice de répétition (bis, ter, etc.)
                              type: string
                              example: null
                              nullable: true
                            adresse_nom_voie:
                              description: Nom de la voie
                              type: string
                              example: RUE DE RIVOLI
                            adresse_code_postal:
                              description: Code postal
                              type: string
                              example: '75001'
                            parcelle:
                              description: Informations sur la parcelle cadastrale
                              properties:
                                code:
                                  description: Code cadastral complet (14 caractères)
                                  type: string
                                  example: 750560000AB0123
                                section:
                                  description: Section cadastrale
                                  type: string
                                  example: AB
                                numero:
                                  description: Numéro de parcelle
                                  type: string
                                  example: '0123'
                                superficie:
                                  description: Superficie de la parcelle en m²
                                  type: number
                                  format: float
                                  example: 1250.5
                              type: object
                            municipalite:
                              description: Informations sur la commune
                              properties:
                                code:
                                  description: Code INSEE de la commune
                                  type: string
                                  example: '75056'
                                nom:
                                  description: Nom de la commune
                                  type: string
                                  example: Paris
                                codes_postaux:
                                  description: >-
                                    Liste de tous les codes postaux de la
                                    commune
                                  type: array
                                  items:
                                    type: string
                                  example:
                                    - '75001'
                                    - '75002'
                                    - '75003'
                                    - '75004'
                              type: object
                          type: object
                      type: object
                type: object
                example:
                  type: FeatureCollection
                  features:
                    - type: Feature
                      geometry:
                        type: Point
                        coordinates:
                          - 2.3522
                          - 48.8566
                      properties:
                        siret: '12345678901234'
                        siren: '123456789'
                        nic: '01234'
                        denomination_complete: BOULANGERIE PATISSERIE PARIS
                        denomination_usuelle: null
                        enseigne_1: null
                        enseigne_2: null
                        enseigne_3: null
                        activite_principale: 10.71C
                        activite_principale_registre_metiers: null
                        nomenclature_activite_principale: NAFRev2
                        categorie_activite: Boulangerie
                        categorie_parent_activite: Commerce
                        naf_section:
                          code: C
                          label: Industrie manufacturière
                        naf_division:
                          code: '10'
                          label: Industries alimentaires
                        naf_groupe:
                          code: '10.7'
                          label: >-
                            Fabrication de produits de boulangerie-pâtisserie et
                            de pâtes alimentaires
                        naf_classe:
                          code: '10.71'
                          label: Boulangerie et boulangerie-pâtisserie
                        naf_sous_classe:
                          code: 10.71C
                          label: Boulangerie et boulangerie-pâtisserie
                        etat_administratif: Actif
                        caractere_employeur: true
                        tranche_effectifs: 3
                        annee_effectifs: '2021'
                        date_creation: '2015-01-01'
                        date_debut: '2015-03-01'
                        date_dernier_traitement: '2023-11-30T10:17:50'
                        etablissement_siege: true
                        statut_diffusion: 0
                        adresse_complete: 15 RUE DE RIVOLI 75001 PARIS
                        adresse_numero: 15
                        adresse_indice_repetition: null
                        adresse_nom_voie: RUE DE RIVOLI
                        adresse_code_postal: '75001'
                        parcelle:
                          code: 750560000AB0123
                          section: AB
                          numero: '0123'
                          superficie: 1250.5
                        municipalite:
                          code: '75056'
                          nom: Paris
                          codes_postaux:
                            - '75001'
                            - '75002'
                            - '75003'
                            - '75004'
        '400':
          description: Requête invalide - Paramètres manquants ou incorrects
        '401':
          description: Non authentifié
        '403':
          description: Accès refusé - Quota API dépassé ou permissions insuffisantes
        '404':
          description: Aucun occupant trouvé
      security:
        - bearer:
            - '*'
components:
  schemas:
    CTB_POSTSCHEMA_RechercheParcelleRequest:
      title: Requête de recherche avancée de parcelles
      description: >-
        Structure complète de la requête pour la recherche avancée et flexible
        de parcelles avec filtres configurables en mode strict ou indicatif
      properties:
        filtres:
          $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresRecherche'
        pagination:
          $ref: '#/components/schemas/CTB_POSTSCHEMA_PaginationRecherche'
        options:
          $ref: '#/components/schemas/CTB_POSTSCHEMA_OptionsRecherche'
      type: object
      example:
        filtres:
          code_municipalite:
            value: 75056,75001,75002
          annee_construction:
            min: 1990
            max: 2020
            indicatif: true
          surface_habitable:
            min: 50
            max: 150
            indicatif: true
          altitude:
            max: 500
            indicatif: false
          batiment_leger:
            value: 0
            indicatif: false
          dpe_energie:
            value: C
            indicatif: true
        pagination:
          limite: 20
          curseur: ''
        options:
          format: geojson
          geometrie: centre
          champs:
            - cadastre_id
            - superficie
            - score_pertinence
          champ_tri: score_pertinence
          ordre_tri: desc
    CTB_POSTSCHEMA_FiltresRecherche:
      title: Tous les filtres disponibles pour la recherche
      description: >-
        Liste complète et exhaustive de tous les filtres disponibles pour la
        recherche avancée de parcelles. Tous les filtres sont optionnels. Vous
        pouvez combiner des filtres de différentes catégories selon vos besoins.
      allOf:
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresGeographiques'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresCadastraux'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresBatiment'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresDPE'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresDVF'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresEstimation'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresPermis'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresZonesRisques'
        - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltresFonciers'
    CTB_POSTSCHEMA_FiltresBatiment:
      title: Filtres bâtiments
      description: >-
        Filtres liés aux caractéristiques des bâtiments construits sur les
        parcelles
      properties:
        bati_type:
          description: >-
            Type de bâti calculé. Accepte plusieurs valeurs sous forme d'array
            ou une chaîne séparée par des virgules (ex: '1,7,13').


            **Liste complète des types possibles :**


            **Global :**

            - `0` - Bâtiment : Maison/Appartement/Autres


            **Maisons :**

            - `1` - Maison

            - `2` - Maison 1 pièce/studio

            - `3` - Maison 2 pièces

            - `4` - Maison 3 pièces

            - `5` - Maison 4 pièces

            - `6` - Maison 5 pièces et plus


            **Appartements :**

            - `7` - Appartement

            - `8` - Appartement 1 pièce/studio

            - `9` - Appartement 2 pièces

            - `10` - Appartement 3 pièces

            - `11` - Appartement 4 pièces

            - `12` - Appartement 5 pièces et plus


            **Bâtiments et locaux :**

            - `13` - Immeuble : Bâtiment/Immeuble

            - `14` - Activité : Local d'activités

            - `15` - Dépendance


            **Terrains :**

            - `16` - Terrain à bâtir

            - `17` - Terrain
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        annee_construction:
          description: Période de construction du bâtiment (année).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        surface_habitable:
          description: Surface habitable de la parcelle issue des DVF et DPE (en m²).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        hauteur:
          description: Hauteur du bâtiment (en m).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        etages:
          description: >-
            Nombre d'étages du bâtiment principal. Accepte plusieurs valeurs
            sous forme d'array ou une chaîne séparée par des virgules (ex:
            '1,2,3').


            **Exemples de valeurs :**


            - `0` - Rez-de-chaussée uniquement : Bâtiment de plain-pied

            - `1` - 1 étage : Rez-de-chaussée + 1 étage (R+1)

            - `2` - 2 étages : Rez-de-chaussée + 2 étages (R+2)

            - `3` - 3 étages : Rez-de-chaussée + 3 étages (R+3)

            - `4` - 4 étages et plus : Rez-de-chaussée + 4 étages ou plus (R+4+)
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        isole:
          description: >-
            Bâtiment isolé : true = parcelle ne comportant aucun bâtiment dans
            les parcelles voisines, false = parcelle avec bâtiments voisins.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreBoolean'
        mitoyen:
          description: >-
            Nombre de faces mitoyennes (murs partagés avec des bâtiments
            voisins). Accepte plusieurs valeurs sous forme d'array ou une chaîne
            séparée par des virgules (ex: '0,1,2').


            **Liste complète des valeurs possibles :**


            - `0` - Aucune face mitoyenne : Bâtiment totalement isolé, sans mur
            partagé

            - `1` - Une face mitoyenne : Bâtiment partagé sur un côté

            - `2` - Deux faces mitoyennes : Bâtiment partagé sur deux côtés

            - `3` - Trois faces mitoyennes ou plus : Bâtiment partagé sur trois
            côtés ou plus
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        batiment_dur:
          description: >-
            Nombre de bâtiments durs (constructions en matériaux solides) sur la
            parcelle. Accepte plusieurs valeurs sous forme d'array ou une chaîne
            séparée par des virgules (ex: '1,2,3').


            **Liste complète des valeurs possibles :**


            - `0` - Aucun : Pas de bâtiment dur sur la parcelle

            - `1` - Un seul : Exactement 1 bâtiment dur (maison, immeuble, local
            commercial, etc.)

            - `2` - Deux : Exactement 2 bâtiments durs

            - `3` - Trois : Exactement 3 bâtiments durs

            - `4` - Quatre et plus : 4 bâtiments durs ou plus
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        batiment_leger:
          description: >-
            Nombre de bâtiments légers (constructions légères ou temporaires)
            sur la parcelle. Accepte plusieurs valeurs sous forme d'array ou une
            chaîne séparée par des virgules (ex: '1,2,3').


            **Liste complète des valeurs possibles :**


            - `0` - Aucun : Pas de bâtiment léger sur la parcelle

            - `1` - Un seul : Exactement 1 bâtiment léger (abri de jardin,
            préfabriqué, cabanon, serre, etc.)

            - `2` - Deux : Exactement 2 bâtiments légers

            - `3` - Trois : Exactement 3 bâtiments légers

            - `4` - Quatre et plus : 4 bâtiments légers ou plus
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        piscine:
          description: Construction de type piscine référencée au cadastre.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreBoolean'
        piscine_surface:
          description: Surface minimale et maximale de la piscine (en m²).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        forme_piscine:
          description: >-
            Forme de la piscine cadastrée. Accepte plusieurs valeurs sous forme
            d'array ou une chaîne séparée par des virgules (ex: '0,1,3').


            **Liste complète des formes possibles :**


            - `0` - Rectangle : Piscine de forme rectangulaire classique

            - `1` - Rectangle avec escalier : Piscine rectangulaire avec
            escalier intégré

            - `2` - L : Piscine en forme de L

            - `3` - Ronde/Arrondi : Piscine de forme ronde ou avec angles
            arrondis

            - `4` - Autres : Autres formes (haricot, ovale, libre, etc.)
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
      type: object
    CTB_POSTSCHEMA_FiltresCadastraux:
      title: Filtres cadastraux
      description: Filtres liés aux données cadastrales des parcelles
      properties:
        parcelle_multiple:
          description: >-
            Mode de recherche multi-parcelle (parcelles regroupées). Accepte
            plusieurs valeurs sous forme d'array ou une chaîne séparée par des
            virgules (ex: '1,2,3').


            **Liste complète des modes possibles :**


            - `0` - Toutes : Recherche toutes les parcelles (simples et
            multiples)

            - `1` - Parcelles simples : Uniquement les parcelles non regroupées
            (par défaut)

            - `2` - 2 parcelles : Uniquement les groupements de 2 parcelles

            - `3` - 3 parcelles : Uniquement les groupements de 3 parcelles

            - `4` - 4 parcelles et plus : Groupements de 4 parcelles ou plus
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        superficie:
          description: Surface de la parcelle en m².
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        jardin:
          description: Surface du jardin en m².
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        emprise_sol:
          description: Emprise au sol en m².
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        altitude:
          description: Altitude de la parcelle (en m).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        arpente:
          description: >-
            Lorsque le terrain a été mesuré par un Géomètre-Expert, la parcelle
            est dite 'arpentée'.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreBoolean'
      type: object
    CTB_POSTSCHEMA_FiltresDPE:
      title: Filtres DPE (Diagnostic Performance Énergétique)
      description: >-
        Filtres liés à la performance énergétique et environnementale des
        bâtiments
      properties:
        dpe_energie:
          description: >-
            Étiquette de performance énergétique (consommation). Accepte
            plusieurs valeurs sous forme d'array ou une chaîne séparée par des
            virgules (ex: 'A,B,C').


            **Liste complète des étiquettes possibles :**


            - `A` - Très performant : Consommation ≤ 70 kWh/m²/an (logements
            neufs ou très bien isolés)

            - `B` - Performant : Consommation entre 71 et 110 kWh/m²/an
            (logements bien isolés)

            - `C` - Assez performant : Consommation entre 111 et 180 kWh/m²/an
            (logements correctement isolés)

            - `D` - Moyennement performant : Consommation entre 181 et 250
            kWh/m²/an (isolation moyenne)

            - `E` - Peu performant : Consommation entre 251 et 330 kWh/m²/an
            (isolation faible)

            - `F` - Très peu performant : Consommation entre 331 et 420
            kWh/m²/an (isolation très faible)

            - `G` - Extrêmement peu performant : Consommation > 420 kWh/m²/an
            (passoire thermique)
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        dpe_ges:
          description: >-
            Étiquette d'émission de gaz à effet de serre (GES). Accepte
            plusieurs valeurs sous forme d'array ou une chaîne séparée par des
            virgules (ex: 'D,E,F').


            **Liste complète des étiquettes possibles :**


            - `A` - Très faible émission : Émission ≤ 6 kg CO2/m²/an (logements
            très écologiques)

            - `B` - Faible émission : Émission entre 7 et 11 kg CO2/m²/an
            (logements écologiques)

            - `C` - Émission modérée : Émission entre 12 et 30 kg CO2/m²/an
            (logements assez écologiques)

            - `D` - Émission moyenne : Émission entre 31 et 50 kg CO2/m²/an
            (impact environnemental moyen)

            - `E` - Émission importante : Émission entre 51 et 70 kg CO2/m²/an
            (impact environnemental élevé)

            - `F` - Émission très importante : Émission entre 71 et 100 kg
            CO2/m²/an (impact environnemental très élevé)

            - `G` - Émission extrêmement importante : Émission > 100 kg
            CO2/m²/an (logement très polluant)
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        dpe_date_reception:
          description: >-
            Période de réception du diagnostic de performance énergétique
            (format: YYYY-MM-DD).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        dpe_date_etablissement:
          description: >-
            Période d'établissement du diagnostic de performance énergétique
            (format: YYYY-MM-DD).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        dpe_date_visite_diagnostiqueur:
          description: >-
            Période de la visite du diagnostiqueur pour le DPE (format:
            YYYY-MM-DD).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        elec_tertiaire:
          description: Consommation électrique tertiaire (en kWh/an).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        elec_residentielle:
          description: Consommation électrique résidentielle (en kWh/an).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        gaz_tertiaire:
          description: Consommation gaz tertiaire (en kWh/an).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        gaz_residentielle:
          description: Consommation gaz résidentielle (en kWh/an).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
      type: object
    CTB_POSTSCHEMA_FiltresDVF:
      title: Filtres DVF (Demandes de Valeurs Foncières)
      description: Filtres liés aux transactions immobilières réelles (données DVF)
      properties:
        dvf_existe:
          description: >-
            Inclus dans les ventes immobilières depuis le 1er Janvier 2014.
            Valeurs : true ou false.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleStrict'
        dvf_prix:
          description: >-
            Prix de vente des biens immobiliers depuis le 1er Janvier 2014 (en
            euros).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        dvf_date:
          description: >-
            Période de vente des biens immobiliers depuis le 1er Janvier 2014
            (format YYYY-MM-DD).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        dvf_code_type_bien:
          description: >-
            Code du type de bien vendu depuis le 1er Janvier 2014. Accepte
            plusieurs valeurs sous forme d'array ou une chaîne séparée par des
            virgules (ex: '111,121').
             *
            **Liste complète des codes possibles :**
             *
            **Activité et indéterminé :**

            - `14` - ACTIVITE

            - `101` - BATI - INDETERMINE : Vefa sans descriptif

            - `102` - BATI - INDETERMINE : Vente avec volume(s)


            **Maisons :**

            - `110` - MAISON - INDETERMINEE

            - `111` - UNE MAISON

            - `112` - DES MAISONS


            **Appartements :**

            - `120` - APPARTEMENT INDETERMINE

            - `121` - UN APPARTEMENT

            - `122` - DEUX APPARTEMENTS


            **Dépendances :**

            - `131` - UNE DEPENDANCE

            - `132` - DES DEPENDANCES


            **Bâti mixte :**

            - `151` - BATI MIXTE - LOGEMENTS

            - `152` - BATI MIXTE - LOGEMENT/ACTIVITE


            **Terrains non bâtis :**

            - `20` - TERRAIN NON BATIS INDETERMINE

            - `21` - TERRAIN DE TYPE TAB (Terrain à bâtir)


            **Terrains artificialisés :**

            - `221` - TERRAIN D'AGREMENT

            - `222` - TERRAIN D'EXTRACTION

            - `223` - TERRAIN DE TYPE RESEAU

            - `229` - TERRAIN ARTIFICIALISE MIXTE


            **Terrains naturels :**

            - `232` - TERRAIN FORESTIER

            - `233` - TERRAIN LANDES ET EAUX

            - `239` - TERRAIN NATUREL MIXTE


            **Terrains agricoles :**

            - `2311` - TERRAIN VITICOLE

            - `2312` - TERRAIN VERGER

            - `2313` - TERRAIN DE TYPE TERRE ET PRE

            - `2319` - TERRAIN AGRICOLE MIXTE
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
      type: object
    CTB_POSTSCHEMA_FiltresEstimation:
      title: Filtres d'estimation de prix
      description: Filtres liés aux estimations de valeurs immobilières
      properties:
        estimation:
          description: Prix d'estimation en euros.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        estimation_ppm:
          description: Prix par m² d'estimation en euros.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
      type: object
    CTB_POSTSCHEMA_FiltresFonciers:
      title: Filtres fonciers et propriétaires
      description: >-
        Filtres liés aux données foncières, propriétaires et opportunités
        immobilières
      properties:
        construction:
          description: Parcelle contenant des constructions.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreBoolean'
        copropriete:
          description: >-
            Numéro d'immatriculation de la copropriété (identifiant unique de la
            copropriété). Accepte plusieurs valeurs sous forme d'array ou une
            chaîne séparée par des virgules (ex: ['AB7000001', 'AB7000002',
            'AB7000003']).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        personne_morale:
          description: >-
            Code SIREN de la personne morale propriétaire (9 chiffres). Accepte
            plusieurs valeurs sous forme d'array ou une chaîne séparée par des
            virgules (ex: ['123456789', '234567890', '345678901']).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        personne_morale_presente:
          description: Présence de personne morale sur la parcelle.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreBoolean'
        opportunite:
          description: Parcelle contenant des opportunités.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreBoolean'
        opportunite_date:
          description: 'Période de l''opportunité (format: YYYY-MM-DD).'
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreRange'
        opportunite_type:
          description: >-
            Type d'opportunités détectées sur la parcelle. Accepte plusieurs
            valeurs sous forme d'array ou une chaîne séparée par des virgules
            (ex: 'dpe,terrain').


            **Liste complète des types possibles :**


            - `dpe` - Opportunité DPE : Parcelles avec diagnostic de performance
            énergétique de moins de 3 mois.

            - `terrain` - Opportunité terrain : Parcelles avec potentiel foncier
            (terrain constructible, division possible, etc.)
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        numero_rue:
          description: >-
            Numéro de rue de l'adresse postale. Accepte plusieurs valeurs sous
            forme d'array ou une chaîne séparée par des virgules (ex: '2,3').
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
      type: object
    CTB_POSTSCHEMA_FiltresGeographiques:
      title: Filtres géographiques
      description: >-
        ⚠️ **IMPORTANT** : Au moins UN filtre géographique est REQUIS parmi :
        code_departement, code_municipalite, code_postal, code_iris, ou la paire
        de coordonnées GPS (lat ET lon ensemble). Cela permet de limiter la
        recherche et éviter de scanner toute la France.
         *
         * Filtres liés à la localisation et aux codes territoriaux
      properties:
        lat:
          description: >-
            Latitude (en degrés décimaux, WGS84) pour rechercher la parcelle
            contenant ce point.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleStrict'
        lon:
          description: >-
            Longitude (en degrés décimaux, WGS84) pour rechercher la parcelle
            contenant ce point.
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleStrict'
        code_departement:
          description: 'Code département sur 2 ou 3 caractères (ex: ''75'', ''2A'').'
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleStrict'
        code_municipalite:
          description: >-
            Code INSEE de la commune (ex: '75056'). Accepte plusieurs valeurs
            sous forme d'array ou une chaîne séparée par des virgules (ex:
            '75056,69123,13055').
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultipleStrict'
        code_postal:
          description: >-
            Code postal sur 5 caractères (ex: '75001'). Accepte plusieurs
            valeurs sous forme d'array ou une chaîne séparée par des virgules
            (ex: '75001,75002,75003').
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultipleStrict'
        code_iris:
          description: >-
            Code IRIS (Îlots Regroupés pour l'Information Statistique - Quartier
            - ex: '751010105'). Accepte plusieurs valeurs sous forme d'array ou
            une chaîne séparée par des virgules (ex:
            '751010105,751010204,751010301').
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultipleStrict'
        code_section:
          description: >-
            Code section cadastrale sur 2 caractères (ex: 'AB'). Accepte
            plusieurs valeurs sous forme d'array ou une chaîne séparée par des
            virgules (ex: 'AB,AC,AD').
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultipleStrict'
      type: object
    CTB_POSTSCHEMA_FiltresPermis:
      title: Filtres permis de construire
      description: Filtres liés aux permis de construire
      properties:
        permis_type:
          description: >-
            Types de permis depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs sous forme d'array ou une chaîne séparée par des virgules
            (ex: '1,2').
             *
            **Liste complète des types possibles :**


            - `0` - Non communiqué : Type de permis non précisé

            - `1` - Permis de construire de logement (PC) : Autorisation pour
            construire des logements neufs

            - `2` - Déclaration préalable de travaux de logement (DP) : Pour
            travaux de logement de faible ampleur

            - `3` - Permis de construire de local (PC) : Autorisation pour
            construire des locaux commerciaux, industriels ou professionnels

            - `4` - Déclaration préalable de travaux de local (DP) : Pour
            travaux de local de faible ampleur

            - `5` - Permis d'aménager (PA) : Pour aménager un terrain
            (lotissement, camping, etc.)

            - `6` - Permis de démolir : Autorisation de démolir une construction
            existante
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        permis_etat:
          description: >-
            États du permis depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs sous forme d'array ou une chaîne séparée par des virgules
            (ex: '2,5').
             *
            **Liste complète des états possibles :**


            - `0` - Non communiqué : État du permis non précisé

            - `2` - Autorisé : Permis délivré et autorisé

            - `4` - Annulé : Permis annulé ou refusé

            - `5` - Commencé : Travaux commencés (DOC - Déclaration d'Ouverture
            de Chantier)

            - `6` - Terminé : Travaux terminés (DAACT - Déclaration Attestant
            l'Achèvement et la Conformité des Travaux)
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        permis_nature:
          description: >-
            Natures du permis depuis le 1er Janvier 2013. Accepte plusieurs
            valeurs sous forme d'array ou une chaîne séparée par des virgules
            (ex: '1,3').
             *
            **Liste complète des natures possibles :**


            - `0` - Destruction de construction : Démolition totale ou partielle
            d'une construction existante

            - `1` - Nouvelle construction : Construction d'un bâtiment neuf sur
            terrain nu

            - `2` - Transformation sans extension ni diminution : Modification
            intérieure sans changement de surface

            - `3` - Transformation avec extension : Modification avec
            augmentation de la surface

            - `4` - Transformation avec diminution : Modification avec réduction
            de la surface

            - `5` - Extension sans transformation : Agrandissement sans
            modification de l'existant

            - `6` - Diminution sans transformation : Réduction de surface sans
            modification de l'existant

            - `7` - Non communiqué : Nature du permis non précisée
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        permis_cat_dem:
          description: >-
            Catégories du demandeur du permis depuis le 1er Janvier 2013.
            Accepte plusieurs valeurs sous forme d'array ou une chaîne séparée
            par des virgules (ex: '10,11,12').
             *
            **Liste complète des catégories possibles :**


            **Particuliers :**

            - `10` - Particuliers SAI (Sans Autre Indication) : Particuliers non
            catégorisés

            - `11` - Particuliers purs : Personnes physiques individuelles

            - `12` - SCI de particuliers : Sociétés Civiles Immobilières de
            particuliers


            **Bailleurs sociaux :**

            - `20` - Bailleurs sociaux SAI : Bailleurs sociaux non catégorisés

            - `21` - Organismes HLM : Office public de l'habitat, entreprises
            sociales pour l'habitat

            - `22` - EPL (Entreprises Publiques Locales) : SEM, SPL
            d'aménagement ou de construction

            - `23` - Autres organismes : Collecteurs d'Action Logement,
            associations, fondations


            **Promoteurs :**

            - `30` - Promoteurs : Promoteurs immobiliers non catégorisés

            - `31` - Promoteurs reconnus : Promoteurs immobiliers professionnels
            reconnus

            - `32` - SCI ou supports de programmes : Supports juridiques de
            programmes immobiliers

            - `33` - Autres professionnels : Constructeurs de maisons
            individuelles, lotisseurs


            **Administrations publiques :**

            - `40` - Administrations publiques : Administrations non
            catégorisées

            - `41` - État et ODAC : État et Organismes Divers d'Administration
            Centrale

            - `42` - Départements et régions : Collectivités territoriales de
            niveau supérieur

            - `43` - Communes et EPIC : Communes et Établissements Publics à
            caractère Industriel et Commercial


            **Autres :**

            - `50` - Autres sociétés : Sociétés commerciales, industrielles ou
            de services

            - `80` - Sans objet : Catégorie non applicable

            - `90` - Non déterminé : Catégorie du demandeur non précisée
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
      type: object
    CTB_POSTSCHEMA_FiltresZonesRisques:
      title: Filtres zones PLU et risques
      description: Filtres liés aux zones PLU et risques naturels
      properties:
        plu_zone:
          description: >-
            Zone PLU principale. Accepte plusieurs valeurs sous forme d'array ou
            une chaîne séparée par des virgules (ex: ['U', 'AU'] ou 'U,AU'). La
            recherche est insensible à la casse (u = U).
             *
            **Liste complète des zones possibles :**


            - `A` - Zone Agricole : Secteurs à protéger en raison du potentiel
            agronomique, biologique ou économique des terres agricoles

            - `Ah` - Zone Agricole avec habitat diffus : Sous-zone A permettant
            l'habitat diffus en milieu agricole

            - `AUc` - Zone À Urbaniser - Centre : Secteur destiné à
            l'urbanisation future, généralement situé en centre-ville

            - `AUs` - Zone À Urbaniser - Secteur : Secteur destiné à
            l'urbanisation future, généralement en périphérie

            - `N` - Zone Naturelle : Secteurs à protéger en raison de la qualité
            des sites, des milieux naturels ou des paysages

            - `Nd` - Zone Naturelle avec densification : Sous-zone N permettant
            une densification limitée

            - `Nh` - Zone Naturelle avec habitat diffus : Sous-zone N permettant
            l'habitat diffus en milieu naturel

            - `U` - Zone Urbaine : Secteurs déjà urbanisés où les équipements
            publics existants permettent d'admettre immédiatement des
            constructions
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        plu_zone_type:
          description: >-
            Type de zone PLU spécifique (ex: UBa, AUs, U1e, N, etc.). Accepte
            plusieurs valeurs sous forme d'array ou une chaîne séparée par des
            virgules (ex: ['UBa', 'AUs', 'U1e'] ou 'UBa,AUs,U1e'). La recherche
            est insensible à la casse (uba = UBa).
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        risque_argile:
          description: >-
            Aléa de retrait-gonflement des sols argileux. Accepte plusieurs
            valeurs sous forme d'array ou une chaîne séparée par des virgules
            (ex: [1, 2] ou '1,2').
             
            **Valeurs possibles :**


            - `1` - Faible : Aléa faible de retrait-gonflement des argiles

            - `2` - Moyen : Aléa moyen de retrait-gonflement des argiles

            - `3` - Fort : Aléa fort de retrait-gonflement des argiles
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
        risque_radon:
          description: >-
            Potentiel radon dans les roches et sous-sols. Accepte plusieurs
            valeurs sous forme d'array ou une chaîne séparée par des virgules
            (ex: [2, 3] ou '2,3').
             
            **Valeurs possibles :**


            - `1` - Faible : Potentiel radon faible dans les roches et sous-sols

            - `2` - Moyen : Potentiel radon moyen dans les roches et sous-sols

            - `3` - Fort : Potentiel radon fort dans les roches et sous-sols
          allOf:
            - $ref: '#/components/schemas/CTB_POSTSCHEMA_FiltreSimpleMultiple'
      type: object
    CTB_POSTSCHEMA_FiltreBoolean:
      title: Filtre avec valeur booléenne
      description: Structure pour les filtres avec une valeur booléenne (true/false)
      required:
        - value
        - indicatif
      properties:
        value:
          description: Valeur booléenne du filtre (true/false) ou (1/0)
          type: boolean
          example: true
        indicatif:
          description: >-
            Mode de recherche : false = strict (WHERE exact), true = indicatif
            (scoring/pertinence)
          type: boolean
          example: false
      type: object
    CTB_POSTSCHEMA_FiltreRange:
      title: Filtre avec plage (min/max)
      description: Structure pour les filtres numériques avec valeurs minimale et maximale
      required:
        - indicatif
      properties:
        min:
          description: Valeur minimale (optionnelle)
          type: number
          example: 1990
        max:
          description: Valeur maximale (optionnelle)
          type: number
          example: 2020
        indicatif:
          description: >-
            Mode de recherche : false = strict (WHERE exact), true = indicatif
            (scoring/pertinence)
          type: boolean
          example: true
      type: object
    CTB_POSTSCHEMA_FiltreSimple:
      title: Filtre avec valeur unique
      description: Structure pour les filtres avec une seule valeur (string ou number)
      required:
        - value
        - indicatif
      properties:
        value:
          description: Valeur du filtre
          example: '75056'
          oneOf:
            - type: string
            - type: number
        indicatif:
          description: >-
            Mode de recherche : false = strict (WHERE exact), true = indicatif
            (scoring/pertinence)
          type: boolean
          example: false
      type: object
    CTB_POSTSCHEMA_FiltreSimpleMultiple:
      title: Filtre avec valeur unique ou valeurs multiples
      description: >-
        Structure pour les filtres acceptant une ou plusieurs valeurs séparées
        par des virgules (ex: '75056' ou '75056,69123,13055')
      required:
        - value
        - indicatif
      properties:
        value:
          description: >-
            Valeur du filtre. Plusieurs valeurs peuvent être spécifiées en les
            séparant par des virgules
          type: string
          example: 75056,69123,13055
        indicatif:
          description: >-
            Mode de recherche : false = strict (WHERE exact), true = indicatif
            (scoring/pertinence)
          type: boolean
          example: false
      type: object
    CTB_POSTSCHEMA_FiltreSimpleMultipleStrict:
      title: Filtre avec valeurs multiples (mode strict uniquement)
      description: >-
        Structure pour les filtres acceptant une ou plusieurs valeurs séparées
        par des virgules en mode strict uniquement (pas de mode
        indicatif/scoring disponible)
      required:
        - value
      properties:
        value:
          description: >-
            Valeur du filtre (recherche exacte uniquement). Plusieurs valeurs
            peuvent être spécifiées en les séparant par des virgules
          type: string
          example: 75056,69123,13055
      type: object
    CTB_POSTSCHEMA_FiltreSimpleStrict:
      title: Filtre avec valeur unique (mode strict uniquement)
      description: >-
        Structure pour les filtres avec une seule valeur en mode strict
        uniquement (pas de mode indicatif/scoring disponible)
      required:
        - value
      properties:
        value:
          description: Valeur du filtre (recherche exacte uniquement)
          example: '75056'
          oneOf:
            - type: string
            - type: number
            - type: boolean
      type: object
    CTB_POSTSCHEMA_OptionsRecherche:
      title: Options d'affichage et de tri des résultats
      description: >-
        Configuration du format de sortie, de la géométrie et du tri des
        résultats
      properties:
        format:
          description: >-
            Format de sortie des résultats : 'json' (objets simples) ou
            'geojson' (format GeoJSON standard)
          type: string
          default: json
          enum:
            - json
            - geojson
        geometrie:
          description: >-
            Type de géométrie à inclure : 'centre' (point central), 'contour'
            (polygone complet) ou 'bbox' (boîte englobante)
          type: string
          default: centre
          enum:
            - centre
            - contour
            - bbox
        champs:
          description: >-
            Liste des champs à retourner dans la réponse. Valeurs possibles :
            cadastre_id, superficie, perimetre, arpente, section, municipalite,
            centre, contour, bbox, score_pertinence. Le champ 'score_pertinence'
            indique le score de pertinence calculé lors de l'utilisation de
            filtres en mode indicatif. Si non spécifié, les champs par défaut
            (cadastre_id, municipalite, superficie) sont retournés
          type: array
          items:
            type: string
            enum:
              - cadastre_id
              - superficie
              - perimetre
              - arpente
              - section
              - municipalite
              - centre
              - contour
              - bbox
              - score_pertinence
          example:
            - cadastre_id
            - superficie
            - score_pertinence
            - centre
            - municipalite
        champ_tri:
          description: >-
            Nom du champ utilisé pour le tri des résultats. Valeurs possibles :
            cadastre_id, superficie, code_municipalite, score_pertinence.
            Utiliser 'score_pertinence' pour trier par pertinence quand des
            filtres indicatifs sont utilisés
          type: string
          enum:
            - cadastre_id
            - superficie
            - code_municipalite
            - score_pertinence
          example: score_pertinence
        ordre_tri:
          description: >-
            Ordre de tri : 'asc' = croissant (A→Z, 0→9), 'desc' = décroissant
            (Z→A, 9→0)
          type: string
          default: desc
          enum:
            - asc
            - desc
      type: object
    CTB_POSTSCHEMA_PaginationRecherche:
      title: Options de pagination
      description: Configuration de la pagination des résultats de recherche
      properties:
        limite:
          description: Nombre maximum de résultats à retourner par page
          type: integer
          default: 10
          maximum: 50
          minimum: 1
          example: 20
        curseur:
          description: >-
            Curseur de pagination pour récupérer la page suivante (valeur
            obtenue depuis le header X-Pagination-Next-Cursor de la réponse
            précédente)
          type: string
          example: ''
      type: object
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Authentification par jeton Bearer JWT. Format: Bearer <votre_token>'
tags:
  - name: Géocodage
    description: Conversion d'adresses en coordonnées géographiques et géocodage inverse
  - name: Données foncières & immobilières
    description: >-
      DVF (transactions), DPE (diagnostics énergétiques), PLU (urbanisme),
      permis de construire, propriétaires, copropriétés et occupants
  - name: Parcelles
    description: Parcelles
  - name: Données territoriales
    description: Données territoriales
