---
title: "Classement de communes (screener)"
method: GET
path: "/communes/classement"
---

# Classement de communes (screener)

`GET /communes/classement`

## Request

- Base URL: `https://pillr.fr/api/v1`
- URL: `https://pillr.fr/api/v1/communes/classement`
- Auth: HTTP bearer

Communes classées par rendement brut théorique (loyer multiplié par douze, divisé par le prix au m², pour les appartements ou les maisons), par score Pillr ou par distance, avec la logique de l'outil de screening du Hub. Filtres : budget et surface type, prix au m² maximal, rendement minimal, population, sécurité, vacance, évolution à 3 ans, exclusion des QPV, type de bien, distance réelle autour d'une commune (entre centres habités), et les stratégies cashflow, patrimonial, pinel et deal de la page des opportunités. Chaque commune porte la provenance et le nombre de ventes de son prix. Liste paginée. Coût : 1 crédit par élément rendu.

## Query parameters

- `autour_de` string: Code INSEE de la commune de départ du rayon.
- `rayon_km` number: Rayon autour de la commune de départ, en km (50 par défaut, 150 au plus).
- `budget_eur` number: Budget d'achat, en euros : fixe le prix au m² maximal avec la surface type.
- `surface_type_m2` number: Surface type pour le budget, en m² (50 par défaut).
- `rendement_brut_min_pct` number
- `prix_m2_max` number
- `population_min` number: Population minimale (2 000 par défaut).
- `securite_min` number: Sous-score de sécurité minimal, sur 100.
- `vacance_max_pct` number
- `evol_3y_min_pct` number
- `exclure_qpv` union: true : écarte les communes qui comptent un quartier prioritaire.
  - boolean
  - 'true' | 'false' | 'oui' | 'non'
- `type` 'appartement' | 'maison': Type de bien : appartement (par défaut) ou maison.
- `strategie` 'rendement' | 'cashflow' | 'patrimonial' | 'pinel' | 'deal': rendement (par défaut, aucun filtre de plus), cashflow, patrimonial, pinel ou deal : les seuils de la page des opportunités.
- `tri` 'rendement' | 'score_pillr' | 'distance': Tri : rendement (par défaut), score_pillr ou distance (avec autour_de).
- `limite` integer: Nombre d'éléments par page (50 au plus).
- `curseur` string: Curseur opaque rendu par la page précédente (curseur_suivant), à repasser tel quel.

## Response `200`

Réponse servie et débitée (sauf réponse identique déjà servie dans les 24 h).

- object
  - `criteres` object, required
    - `type` 'appartement' | 'maison', required
    - `strategie` 'rendement' | 'cashflow' | 'patrimonial' | 'pinel' | 'deal', required
    - `tri` 'rendement' | 'score_pillr' | 'distance', required
    - `population_min` number, required
    - `prix_m2_max` number, nullable, required
    - `rendement_brut_min_pct` number, nullable, required
    - `securite_min` number, nullable, required
    - `vacance_max_pct` number, nullable, required
    - `evol_3y_min_pct` number, nullable, required
    - `exclure_qpv` boolean, required
    - `autour_de` string, nullable, required
    - `rayon_km` number, nullable, required
    - `perimetre` string, nullable, required: Le périmètre appliqué, en clair.
  - `candidates` integer, required: Communes qui passent les critères, toutes pages confondues.
  - `donnees` object[], required
    - `insee` string, required
    - `commune` string, nullable, required
    - `code_postal` string, nullable, required
    - `departement` string, nullable, required
    - `prix_m2` number, required
    - `provenance_prix` 'mesure' | 'estime', nullable, required: mesure : mesuré sur les ventes DVF de la commune ; estime : estimé par le barème sur trop peu de ventes pour une mesure, à lire avec le nombre de ventes ; null : non étiquetée.
    - `ventes` integer, nullable, required
    - `loyer_m2` number, required
    - `rendement_brut_pct` number, required
    - `evolution_3_ans_pct` number, nullable, required
    - `score_securite` number, nullable, required
    - `score_pillr` number, nullable, required
    - `vacance_pct` number, nullable, required
    - `population` integer, nullable, required
    - `signal_deal` string, nullable, required
    - `est_en_qpv` boolean, nullable, required
    - `zone_abc` string, nullable, required
    - `distance_km` number, nullable, required: À vol d'oiseau entre centres habités ; null sans commune de départ.
    - `qualite` object, required: Ce qui permet de juger la valeur : nombre, provenance, incertitude, drapeaux, date et source.
      - `n` integer, nullable, required: Nombre d'observations derrière la valeur ; null si sans objet.
      - `provenance` 'mesure' | 'estime', nullable, required: mesure : observé sur la donnée ; estime : modèle, barème ou imputation ; null : sans objet.
      - `incertitude` object, nullable, required: Incertitude de la valeur : fourchette et demi-largeur.
        - `demi_largeur_pct` number, nullable, required: Demi-largeur de la fourchette, en % de la valeur.
        - `bas` number, nullable, required
        - `haut` number, nullable, required
      - `drapeaux` string[], required: Ce qui doit faire lire la valeur avec prudence ; vide si rien.
      - `methode` string, nullable, required: Méthode de calcul ou de rattachement, en clair.
      - `donnees_du` string, nullable, required: Date de la donnée (AAAA-MM-JJ ou horodatage ISO 8601).
      - `source` string, required: Source publique ou moteur Pillr, en clair.
  - `donnees_du` string, nullable, required
  - `curseur_suivant` string, nullable, required: Curseur de la page suivante, à repasser dans curseur ; null sur la dernière page.
  - `credits` object, required: Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).
    - `debites` integer, required
    - `restants` integer, nullable, required

## Other responses

- `304`: Non modifiée depuis l'ETag fourni : rien n'est débité.
- `400`: Paramètres invalides ; Curseur invalide
- `401`: Clé d'API absente
- `402`: Crédits insuffisants ; Carte requise ; Plafond mensuel de dépense atteint
- `403`: Portée insuffisante
- `404`: Ressource absente : rien n'est débité
- `429`: Trop de requêtes par minute
- `500`: Erreur interne
- `503`: API indisponible ; Donnée momentanément indisponible

---

[API](https://skmtc.dev/pillr/apis/api-pillr.md) · [All operations](https://skmtc.dev/pillr/apis/api-pillr/llms.txt) · [OpenAPI document](https://skmtc.dev/pillr/apis/api-pillr/revisions/218b2866bd6c?raw)