---
title: "Annonce par lien ou identifiant"
method: GET
path: "/annonces/par-url"
---

# Annonce par lien ou identifiant

`GET /annonces/par-url`

## Request

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

Fiche complète d'une annonce de vente analysée, retrouvée par son lien Leboncoin, BienIci ou SeLoger, ou par son identifiant : faits du bien et détails du portail (honoraires, taxe foncière, copropriété, équipements), vendeur professionnel nommé avec son enseigne, son SIREN et son mandat, photos et description, analyse complète (score et sous-scores, verdict, forces et faiblesses, leviers et cibles de négociation, loyer, rendements recalculés, budget, travaux par poste lus sur les photos, stratégie locative, régime fiscal), valeurs brutes du modèle à côté des valeurs recalculées, coût de sortie de passoire, échéance de location, historique des prix et diffusion en nombres. Données brutes du portail avec inclure=brut, pour un professionnel. Rien n'est débité si l'annonce est absente ou pas encore analysée. Coût : 3 crédits par appel réussi.

## Query parameters

- `url` string, uri: Lien de l'annonce sur le portail d'origine.

## Response `200`

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

- object
  - `id` string, required: Identifiant Pillr de l'annonce.
  - `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
  - `statut` 'actif' | 'retire' | 'masque': actif : en ligne ; retire : retirée du portail ; masque : ni l'un ni l'autre (contrôle en cours).
  - `actif` boolean
  - `type` string
  - `neuf_ancien` string, nullable
  - `commune` string, nullable
  - `code_postal` string, nullable
  - `insee` string, nullable
  - `departement` string, nullable
  - `region` string, nullable
  - `position` object, nullable: Position telle que le portail la donne, avec sa précision.
    - `lat` number, required
    - `lon` number, required
    - `precision` string, required: adresse, approchee, centre_commune ou inconnue.
  - `prix` number, nullable
  - `prix_m2` number, nullable: Prix divisé par la surface (jamais la valeur du portail).
  - `prix_m2_portail` number, nullable: Prix au m² affiché par le portail, servi à côté.
  - `surface` number, nullable
  - `pieces` number, nullable
  - `chambres` number, nullable
  - `etage` number, nullable
  - `nb_etages` number, nullable
  - `salles_de_bain` number, nullable
  - `salles_d_eau` number, nullable
  - `terrain_m2` number, nullable
  - `jardin_privatif_m2` number, nullable
  - `terrain_portail_m2` number, nullable
  - `terrain_suspect` boolean, nullable: Vrai si le terrain d'une maison est plus petit que sa surface habitable.
  - `annee_construction` number, nullable
  - `dpe` object
    - `etiquette` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', nullable, required
    - `conso_kwh_m2_an` number, nullable, required
    - `ges` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', nullable, required
    - `ges_kg_m2_an` number, nullable, required
    - `ges_statut` 'non_soumis' | 'vierge', nullable, required
    - `interdiction_location` string, nullable, required: Premier jour où la location d'un logement de cette classe est interdite (AAAA-MM-JJ), selon le calendrier de la loi Climat et résilience en métropole (G 2025, F 2028, E 2034). null : classe sans échéance, DPE absent, ou adresse hors de la métropole (le calendrier des outre-mer n'est pas servi).
    - `mois_restants` integer, nullable, required: Mois pleins avant l'échéance ; 0 quand l'interdiction est déjà en vigueur ; null sans échéance.
  - `equipements` object
    - `ascenseur` boolean, nullable, required
    - `balcon` boolean, nullable, required
    - `cave` boolean, nullable, required
    - `parking` boolean, nullable, required
    - `meuble` boolean, nullable, required
    - `terrasse` boolean, nullable, required
    - `jardin` boolean, nullable, required
    - `piscine` boolean, nullable, required
    - `garage` boolean, nullable, required
    - `cuisine_equipee` boolean, nullable, required
    - `visite_virtuelle` boolean, nullable, required
    - `orientation` string, nullable, required
    - `chauffage` string, nullable, required
    - `chauffage_mode` string, nullable, required
    - `liste` string[], required: Équipements listés par le portail.
  - `details_portail` object
    - `prix_hors_honoraires` number, nullable, required
    - `honoraires` number, nullable, required
    - `honoraires_a_charge` string, nullable, required
    - `taxe_fonciere` number, nullable, required
    - `charges_copro_annuelles` number, nullable, required
    - `charges_suspectes` boolean, nullable, required: Vrai si les charges annuelles d'un appartement en copropriété semblent mensuelles.
    - `budget_energie_min` number, nullable, required
    - `budget_energie_max` number, nullable, required
    - `lots_copro` number, nullable, required
    - `procedure_copro` boolean, nullable, required
    - `en_copro` boolean, nullable, required
  - `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 servi en entier (nom, enseigne, SIREN, mandat, coordonnées professionnelles), 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
    - `enseigne` string, nullable, required
    - `siren` string, nullable, required
    - `mandat` string, nullable, required: Type de mandat publié (simple, exclusif) ; null si inconnu.
    - `telephone` string, nullable, required: Téléphone professionnel publié par le portail ; jamais celui d'un particulier.
    - `email` string, nullable, required: Adresse électronique professionnelle publiée par le portail ; jamais celle d'un particulier.
  - `titre` string, nullable
  - `description` string, nullable: Description du portail, en texte ; les coordonnées d'un vendeur qui n'est pas un professionnel en sont retirées.
  - `photos` string[]: Liens des photos chez le portail.
  - `premiere_parution` object
    - `date` string, nullable, required
    - `estimee` boolean, required: Vrai quand la date est une estimation (portail qui ne la publie pas).
  - `vu_le` string, nullable
  - `retire_le` string, nullable
  - `entree_le` string, nullable
  - `maj_le` string, nullable
  - `bien_uid` string, nullable: Bien dédoublonné qui porte l'annonce (opération bien).
  - `analyse` object
    - `score` number, nullable, required: Score Pillr sur 100.
    - `sous_scores` object, required
      - `localisation` number, nullable, required
      - `transport` number, nullable, required
      - `rentabilite` number, nullable, required
      - `potentiel` number, nullable, required
      - `etat` number, nullable, required
      - `marche` number, nullable, required
      - `fiscalite` number, nullable, required
      - `risques` number, nullable, required
      - `qualite_annonce` number, nullable, required
    - `profil` string, nullable, required
    - `verdict` string, nullable, required
    - `forces` string[], required
    - `faiblesses` string[], required
    - `recommandation` string, nullable, required
    - `leviers` string[], required: Leviers de négociation.
    - `negociation` object, required
      - `cible_min` number, nullable, required: Cible basse, bornée entre 60 % et 100 % du prix.
      - `cible_max` number, nullable, required
      - `cible_min_moteur` number, nullable, required: Cible basse écrite par le modèle, avant bornage.
      - `cible_max_moteur` number, nullable, required
    - `loyer` object, required
      - `estime` number, nullable, required: Loyer mensuel estimé, en euros ; null quand le moteur s'est replié sur un forfait ou a écarté son estimation.
      - `source` string, nullable, required: carte_des_loyers, repli, ecarte ou non_precise.
      - `estime_moteur` number, nullable, required: Loyer écrit par le moteur, servi tel quel.
    - `rendement_brut` number, nullable, required: Rendement brut en %, recalculé depuis le loyer estimé et le prix.
    - `rendement_brut_moteur` number, nullable, required
    - `rendement_net` number, nullable, required: Rendement net en %, recalculé sur le budget total.
    - `rendement_net_moteur` number, nullable, required
    - `frais_notaire` number, nullable, required: Frais de notaire au taux de l'ancien, en euros.
    - `frais_notaire_moteur` number, nullable, required
    - `budget_total` number, nullable, required: Prix, frais de notaire et milieu de la fourchette des travaux, en euros ; null si les travaux ne sont pas évalués.
    - `budget_total_moteur` number, nullable, required: Budget écrit par le modèle : son sens varie selon les analyses, à lire avec prudence.
    - `etat_visuel` number, nullable, required: État visuel lu sur les photos, sur 100 ; null avec des photos de catalogue.
    - `photos` object, required
      - `exploitables` integer, nullable, required
      - `total` integer, nullable, required
      - `qualite_annonce` integer, nullable, required
    - `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 du barème déterministe, en euros.
      - `max` number, nullable, required: Haut de la fourchette du barème déterministe, en euros.
      - `max_m2` number, nullable, required
      - `postes` object[], required: Travaux par poste, lus sur les photos.
        - `poste` string, nullable, required
        - `libelle` string, nullable, required
        - `min` number, nullable, required
        - `max` number, nullable, required
        - `priorite` string, nullable, required
      - `defauts` object, nullable, required: Défauts relevés sur les photos, par gravité.
        - `mineur` integer, nullable, required
        - `moyen` integer, nullable, required
        - `majeur` integer, nullable, required
      - `pieces_vues` string[], required: Pièces vues sur les photos.
      - `pieces_manquantes` string[], required: Pièces clés absentes des photos (cuisine, salle de bain).
      - `etat_general_moteur` string, nullable, required
      - `urgence_moteur` string, nullable, required
      - `min_moteur` number, nullable, required: Budget bas écrit par le modèle de langage, servi à côté du barème.
      - `max_moteur` number, nullable, required: Budget haut écrit par le modèle de langage, servi à côté du barème.
      - `alertes` string[], required
    - `strategie_locative` string, nullable, required
    - `strategie_locative_raison` string, nullable, required
    - `regime_fiscal` string, nullable, required
    - `regime_fiscal_fiable` boolean, required: Faux quand le régime vaut LMNP_REEL : le modèle le propose sur presque toutes les analyses.
    - `regime_fiscal_raison` string, nullable, required
    - `economie_fiscale_an` number, nullable, required
    - `taxe_fonciere_moteur` number, nullable, required
    - `charges_annuelles_moteur` number, nullable, required
    - `drapeaux` object, required
      - `enchere` boolean, nullable, required
      - `photos_catalogue` boolean, nullable, required
      - `vendu` boolean, nullable, required
      - `loue` boolean, nullable, required
      - `raisons` string, nullable, required
    - `confiance` object, required
      - `niveau_moteur` string, nullable, required: Confiance déclarée par le modèle lui-même (high sur la plupart des analyses).
      - `facteurs` string[], required
      - `limites` string[], required
    - `completude` 'haute' | 'moyenne' | 'basse', nullable, required
    - `completude_criteres` object, required
      - `dpe` boolean, nullable, required
      - `loyer_communal` boolean, nullable, required
      - `prix_dvf` boolean, nullable, required
      - `photos_exploitables` boolean, nullable, required
      - `cuisine_salle_de_bain_vues` boolean, nullable, required
    - `sources` string[], required
    - `moteur` object, required
      - `modele` string, nullable, required
      - `version` number, nullable, required
      - `analyse_le` string, nullable, 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.
  - `sortie_passoire` object, nullable: Coût de sortie d'une passoire (classe E, F ou G) vers D, C ou B, mesuré sur les audits énergétiques réglementaires de l'ADEME pour des logements comparables. null hors des classes E à G, pour un type de logement sans comparable, ou hors de la métropole.
    - `classe_depart` 'E' | 'F' | 'G', required
    - `cibles` object[], required
      - `vers` 'D' | 'C' | 'B', required: Classe visée.
      - `n_audits` integer, required: Nombre d'audits comparables de la cellule retenue.
      - `euros` object, required: Coût des travaux chiffré par les audits comparables, sur leurs propres surfaces, en euros arrondis à la centaine.
        - `mediane` number, required
        - `p25` number, required
        - `p75` number, required
      - `eur_m2` object, nullable, required: Le même coût rapporté à la surface habitable, en euros par m² ; null s'il y a trop peu d'audits avec surface.
        - `mediane` number, required
        - `p25` number, required
        - `p75` number, required
      - `surface_mediane_m2` number, nullable, required: Surface habitable médiane des logements audités.
      - `pour_la_surface` object, nullable, required: Le coût au m² des audits appliqué à la surface du bien, quand elle est connue : le chiffre à citer.
        - `surface_m2` number, required
        - `mediane` number, required
        - `p25` number, required
        - `p75` number, required
      - `part_au_dela` number, nullable, required: Part des audits (0 à 1) dont l'étape chiffrée atteint déjà la classe suivante : le chiffrage dépasse alors la cible.
      - `perimetre` string, required: Les audits comparables, en clair (type de logement, zone climatique, période de construction).
      - `niveau` 'complet' | 'sans_periode' | 'sans_zone' | 'national', required: Finesse de la cellule retenue, de la plus fine (type, zone climatique et période) à la plus large (type seul, France métropolitaine).
    - `lecture` string, required: Ce que mesure le chiffre : une estimation d'auditeur, pas un devis.
    - `source` string, required
  - `prix_historique` object[]: Variations de prix détectées, dédoublonnées au jour ; le détail est dans vie_annonce.
    - `le` string, required
    - `de` number, nullable, required
    - `a` number, required
    - `doublon_probable` boolean, required
  - `diffusion` object, nullable: Le même bien chez d'autres annonceurs, en nombres ; les agences nommées sont dans vie_annonce.
    - `annonces` integer, required
    - `agences` integer, required
    - `particuliers` integer, required
    - `portails` integer, required
    - `prix_min` number, nullable, required
    - `prix_max` number, nullable, required
    - `premiere_parution` string, nullable, required
  - `brut` object, nullable: Données brutes du portail, avec inclure=brut, pour un vendeur professionnel seulement ; null sinon.
  - `drapeaux` string[]: Ce qui doit faire lire l'annonce avec prudence ; vide si rien.
  - `qualite` object: 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)