---
title: "Recherche d'annonces analysées"
method: GET
path: "/annonces"
---

# Recherche d'annonces analysées

`GET /annonces`

## Request

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

Annonces de vente actives et analysées, par communes, codes postaux, départements ou autour d'un point, filtrées par type (appartement, maison, immeuble), prix, pièces, chambres, surface, prix au m², rendement brut ou net, score, DPE, passoires, état visuel, travaux, type de vendeur, SIREN ou enseigne de l'agence, mots-clés, date de parution, résidences gérées et règle « sous le marché ». Tri par rendement, score, état, date, prix, prix au m², distance ou opportunité (le radar du Hub : décote sur la commune, rendement, score, ancienneté). Chaque annonce porte son vendeur (professionnel nommé), sa diffusion multi-agences et ses drapeaux. Un crédit par annonce rendue. Coût : 1 crédit par élément rendu.

## Query parameters

- `insee` union: Code INSEE d'une commune, ou liste de 10 codes au plus (paramètre répété).
  - string: Code INSEE de la commune ou de l'arrondissement (5 caractères, 2A ou 2B pour la Corse).
  - string[]
- `cp` union: Code postal, ou liste de 10 codes au plus.
  - string: Code postal.
  - string[]
- `departement` union: Code de département, ou liste de 8 codes au plus.
  - string: Code du département (01 à 95, 2A, 2B, 971 à 976).
  - string[]
- `lat` number: Latitude du point de recherche (avec lon et rayon_km).
- `lon` number: Longitude du point de recherche (avec lat et rayon_km).
- `rayon_km` number: Rayon autour du point, en km (50 au plus).
- `mots_cles` string: Mots à trouver dans le titre ou la description (4 mots au plus, accents indifférents).
- `type` 'appartement' | 'maison' | 'immeuble': Type de bien : appartement, maison ou immeuble entier.
- `prix_min` number
- `prix_max` number
- `pieces_min` integer
- `pieces_max` integer
- `chambres_min` integer
- `surface_min` number
- `surface_max` number
- `prix_m2_max` number
- `rendement_min` number: Rendement brut minimal, en %.
- `rendement_net_min` number: Rendement net minimal, en %.
- `score_min` number
- `dpe` union: Étiquettes DPE acceptées (une ou plusieurs).
  - 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G'
  - string[]
- `dpe_max` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G': Étiquette DPE la moins bonne acceptée (D : de A à D).
- `passoires` union: Vrai : les seules passoires thermiques (F et G).
  - boolean
  - string
- `etat_visuel_max` number: État visuel maximal sur 100 (pour chercher des biens à rénover).
- `travaux_min` number: Travaux minimaux, sur le bas de la fourchette, en euros.
- `travaux_max` number: Travaux maximaux, sur le haut de la fourchette (le pire cas), en euros.
- `travaux_max_m2` number
- `type_vendeur` 'pro' | 'particulier' | 'inconnu': Statut du vendeur déclaré par le portail : pro (agence, réseau, promoteur), particulier, ou inconnu.
- `siren` string: SIREN de l'agence ou du professionnel.
- `enseigne` string: Nom ou enseigne de l'agence (début du nom).
- `exclure_residences_gerees` union: Vrai : écarte les logements de résidence gérée.
  - boolean
  - string
- `sous_le_marche` union: Vrai : la règle « sous le marché » de la carte du site (rendement brut d'au moins 7 % et score d'au moins 70).
  - boolean
  - string
- `publie_depuis` string: Annonces parues depuis cette date (AAAA-MM-JJ).
- `tri` 'rendement' | 'rendement_net' | 'score' | 'etat' | 'date' | 'prix' | 'prix_desc' | 'prix_m2' | 'opportunite' | 'distance': rendement (défaut), rendement_net, score, etat (meilleur état d'abord), date (plus récentes), prix, prix_desc, prix_m2, distance (avec lat, lon, rayon_km), opportunite (radar du Hub, sur les 250 annonces les mieux notées de la recherche).
- `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.
- `champs` union: Champs rendus, séparés par des virgules (« prix,surface,analyse.score ») ; tous si absent.
  - string
  - string[]

## Response `200`

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

- object
  - `donnees` object[], required
    - `id` string, required: Identifiant Pillr de l'annonce (à repasser à /annonces/{id}).
    - `id_portail` string, nullable: Identifiant chez le portail (lbc:<n>, bienici:<id>, seloger:<id>), servi avec la portée lien_origine.
    - `lien` string, nullable: Lien d'origine de l'annonce, servi avec la portée lien_origine.
    - `source` string: Portail d'origine : lbc, bienici ou seloger.
    - `type` string: Type de bien : appartement, maison, immeuble.
    - `insee` string, nullable
    - `code_postal` string, nullable
    - `commune` string, nullable
    - `lat` number, nullable
    - `lon` number, nullable
    - `precision_coordonnees` string, nullable: Précision de la position : adresse, approchee, centre_commune, ou inconnue tant que le lac ne l'a pas dite.
    - `prix` number, nullable
    - `surface` number, nullable
    - `pieces` number, nullable
    - `prix_m2` number, nullable: Prix divisé par la surface (jamais la valeur du portail).
    - `dpe` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', nullable
    - `score` number, nullable: Score Pillr sur 100.
    - `rendement_brut` number, nullable: Rendement brut en %, recalculé : loyer estimé sur 12 mois divisé par le prix.
    - `rendement_net` number, nullable: Rendement net en %, recalculé sur le budget total (prix, frais de notaire, travaux).
    - `loyer_estime` number, nullable: Loyer mensuel estimé, en euros ; null quand le moteur s'est replié sur un forfait.
    - `etat_visuel` number, nullable: État visuel lu sur les photos, sur 100 (100 : neuf) ; null sans photos exploitables.
    - `travaux` object
      - `statut` 'chiffre' | 'aucun' | 'partiel' | 'non_evalue' | 'non_analyse', required: chiffre : travaux chiffrés poste par poste sur les photos ; aucun : aucun travaux vu ; partiel : chiffrés, mais la cuisine ou la salle de bain n'apparaît pas sur les photos ; non_evalue : photos absentes, inexploitables ou de catalogue ; non_analyse : annonce pas encore analysée.
      - `min` number, nullable, required: Bas de la fourchette des travaux, en euros.
      - `max` number, nullable, required: Haut de la fourchette des travaux, en euros.
      - `max_m2` number, nullable, required: Haut de la fourchette rapporté à la surface, en euros par m².
    - `profil` string, nullable: Profil de l'annonce selon le moteur d'analyse.
    - `type_vendeur` 'pro' | 'particulier' | 'inconnu': Statut du vendeur déclaré par le portail : pro (agence, réseau, promoteur), particulier, ou inconnu.
    - `annonceur` object: Le vendeur : un professionnel est nommé, un particulier jamais.
      - `type_vendeur` 'pro' | 'particulier' | 'inconnu', required: Statut du vendeur déclaré par le portail : pro (agence, réseau, promoteur), particulier, ou inconnu.
      - `nom` string, nullable, required: Nom de l'agence ou du professionnel tel que le portail l'affiche ; null pour un particulier.
      - `enseigne` string, nullable, required: Enseigne ou réseau du professionnel ; null pour un particulier.
      - `siren` string, nullable, required: SIREN du professionnel quand le portail le publie ; null pour un particulier.
    - `agences` integer, nullable: Agences qui proposent le même bien (diffusion multi-agences) ; null si une seule annonce connue.
    - `residence_geree` boolean: Vrai si le titre ou la description décrit un logement de résidence gérée (bail commercial).
    - `premiere_parution` string, nullable
    - `distance_km` number, nullable: Distance au point de recherche, en km ; null sans point.
    - `drapeaux` string[]: Ce qui doit faire lire l'annonce avec prudence ; vide si rien.
    - `opportunite` object, nullable: Lecture d'opportunité du radar du Hub, avec tri=opportunite seulement ; null sinon.
      - `note` number, required: Note composite du radar : décote bornée, rendement borné, score, ancienneté, taille du marché.
      - `signaux` string[], required
      - `ecart_marche_pct` number, nullable, required: Écart du prix au m² au prix médian de la commune pour ce type de bien, en %.
      - `prix_m2_marche` number, nullable, required: Prix médian au m² de la commune pour ce type de bien.
      - `fiable` boolean, required: Vrai si l'annonce passe les garde-fous du radar (marché assez peuplé, écart et prix plausibles).
  - `total` integer, nullable, required: Annonces qui répondent, comptées sur la première page jusqu'à 10 000 ; null au-delà ou sur les pages suivantes.
  - `notes` string[], required
  - `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.
  - `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)