---
title: "Recherche d'annonces en langage naturel"
method: GET
path: "/annonces/recherche-naturelle"
---

# Recherche d'annonces en langage naturel

`GET /annonces/recherche-naturelle`

## Request

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

Une phrase libre (« T3 avec balcon sous 250 000 euros à Nantes ») traduite en filtres de rechercher_annonces, d'abord par le parseur de règles du site, sinon par un modèle de langage, puis exécutée comme rechercher_annonces : 12 annonces au plus, comprises dans le prix. La réponse dit les filtres retenus, ce qui a été ignoré et l'interprétation de la phrase. Les crédits sont rendus si la traduction échoue. Coût : 15 crédits par appel réussi.

## Query parameters

- `q` string, required: La recherche, en une phrase.
- `limite` integer: Annonces rendues (12 au plus).

## Response `200`

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

- object
  - `interpretation` string, required: Ce que la phrase a été comprise vouloir dire.
  - `parseur` 'local' | 'modele', required: local : lue par le parseur de règles du site ; modele : traduite par un modèle de langage.
  - `filtres_retenus` object, required: Les filtres de rechercher_annonces tirés de la phrase, exécutés tels quels.
  - `ignores` string[], required: Ce que la phrase demandait et que la recherche ne sait pas appliquer.
  - `donnees` object[], required
    - `id` string, required: Identifiant Pillr de l'annonce (à repasser à /annonces/{id}).
    - `id_portail` string, nullable, required: Identifiant chez le portail (lbc:<n>, bienici:<id>, seloger:<id>), servi avec la portée lien_origine.
    - `lien` string, nullable, required: Lien d'origine de l'annonce, servi avec la portée lien_origine.
    - `source` string, required: Portail d'origine : lbc, bienici ou seloger.
    - `type` string, required: Type de bien : appartement, maison, immeuble.
    - `insee` string, nullable, required
    - `code_postal` string, nullable, required
    - `commune` string, nullable, required
    - `lat` number, nullable, required
    - `lon` number, nullable, required
    - `precision_coordonnees` string, nullable, required: Précision de la position : adresse, approchee, centre_commune, ou inconnue tant que le lac ne l'a pas dite.
    - `prix` number, nullable, required
    - `surface` number, nullable, required
    - `pieces` number, nullable, required
    - `prix_m2` number, nullable, required: Prix divisé par la surface (jamais la valeur du portail).
    - `dpe` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', nullable, required
    - `score` number, nullable, required: Score Pillr sur 100.
    - `rendement_brut` number, nullable, required: Rendement brut en %, recalculé : loyer estimé sur 12 mois divisé par le prix.
    - `rendement_net` number, nullable, required: Rendement net en %, recalculé sur le budget total (prix, frais de notaire, travaux).
    - `loyer_estime` number, nullable, required: Loyer mensuel estimé, en euros ; null quand le moteur s'est replié sur un forfait.
    - `etat_visuel` number, nullable, required: État visuel lu sur les photos, sur 100 (100 : neuf) ; null sans photos exploitables.
    - `travaux` object, required
      - `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, required: Profil de l'annonce selon le moteur d'analyse.
    - `type_vendeur` 'pro' | 'particulier' | 'inconnu', required: Statut du vendeur déclaré par le portail : pro (agence, réseau, promoteur), particulier, ou inconnu.
    - `annonceur` object, required: 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, required: Agences qui proposent le même bien (diffusion multi-agences) ; null si une seule annonce connue.
    - `residence_geree` boolean, required: Vrai si le titre ou la description décrit un logement de résidence gérée (bail commercial).
    - `premiere_parution` string, nullable, required
    - `distance_km` number, nullable, required: Distance au point de recherche, en km ; null sans point.
    - `drapeaux` string[], required: Ce qui doit faire lire l'annonce avec prudence ; vide si rien.
  - `total` integer, nullable, required
  - `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.
  - `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
- `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)