---
title: "Annonces dans une emprise de carte"
method: GET
path: "/annonces/carte"
---

# Annonces dans une emprise de carte

`GET /annonces/carte`

## Request

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

Les points des annonces actives et analysées dans une emprise de carte (sud, ouest, nord, est ; 3 degrés de côté au plus), filtrables par communes, départements, mots-clés, type, type de vendeur, DPE, travaux et règle « sous le marché » (rendement brut d'au moins 7 % et score d'au moins 70, comme la carte du site). Chaque point porte sa position et sa précision, son prix, sa surface, son score, son rendement et son identifiant. Les mieux notés d'abord, 1 000 points par page au plus. Coût : 1 crédit par tranche de 10 lignes rendues.

## Query parameters

- `bbox` string, required: Emprise de la carte : sud,ouest,nord,est en degrés décimaux (3 degrés de côté au plus).
- `insee` union
  - string: Code INSEE de la commune ou de l'arrondissement (5 caractères, 2A ou 2B pour la Corse).
  - string[]
- `departement` union
  - string: Code du département (01 à 95, 2A, 2B, 971 à 976).
  - string[]
- `cp` union
  - string: Code postal.
  - string[]
- `mots_cles` string
- `type` 'appartement' | 'maison' | 'immeuble': Type de bien : appartement, maison ou immeuble entier.
- `type_vendeur` 'pro' | 'particulier' | 'inconnu': Statut du vendeur déclaré par le portail : pro (agence, réseau, promoteur), particulier, ou inconnu.
- `dpe` union
  - 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G'
  - string[]
- `travaux_max` number
- `sous_le_marche` union
  - boolean
  - string
- `limite` integer: Nombre d'éléments par page (1000 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
  - `points` object[], required
    - `id` string, required
    - `lat` number, required
    - `lon` number, required
    - `precision_coordonnees` string, nullable, required
    - `prix` number, nullable, required
    - `surface` number, nullable, required
    - `prix_m2` number, nullable, required
    - `score` number, nullable, required
    - `rendement_brut` number, nullable, required
    - `dpe` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', nullable, required
    - `type` string, required
  - `total` integer, nullable, required: Points de l'emprise qui répondent, comptés sur la première page jusqu'à 10 000 ; null au-delà ou sur les pages suivantes.
  - `tronque` boolean, required: Vrai s'il reste des points après cette page (curseur_suivant).
  - `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)