Référence · Annonces
Rechercher des annonces dans un secteur
GET/v1/listingsDroit listings:read
Un et un seul secteur : commune (codes INSEE séparés par des virgules, 50 au plus), departement, region, lat+lon+radius_m, ou bbox. Le total n’est donné que sur la première page, plafonné à 10 000 (total_capped).
Paramètres
| Paramètre | Type | Description |
|---|---|---|
| communefacultatif | liste (a,b,c) | Codes INSEE de communes, séparés par des virgules (50 au plus). Paris, Lyon et Marseille : le code de la ville réunit ses arrondissements. |
| departementfacultatif | chaîne | Code de département (13, 2A, 974). |
| regionfacultatif | chaîne | Code INSEE de région (93 : Provence-Alpes-Côte d’Azur). |
| latfacultatif | nombre, -90 à 90 | Latitude du centre d’un rayon (avec lon et radius_m). |
| lonfacultatif | nombre, -180 à 180 | Longitude du centre d’un rayon (avec lat et radius_m). |
| radius_mfacultatif | entier, 100 à 50000 | Rayon en mètres, de 100 à 50 000. |
| bboxfacultatif | chaîne | Cadre « minLon,minLat,maxLon,maxLat » (WGS84). |
| property_typefacultatif | maison | appartement | Type de bien. |
| min_pricefacultatif | entier | Prix minimal, en euros. |
| max_pricefacultatif | entier | Prix maximal, en euros. |
| min_surfacefacultatif | nombre | Surface habitable minimale, en m². |
| max_surfacefacultatif | nombre | Surface habitable maximale, en m². |
| min_surface_terrainfacultatif | nombre | Surface de terrain minimale, en m². |
| max_surface_terrainfacultatif | nombre | Surface de terrain maximale, en m². |
| min_roomsfacultatif | entier | Nombre de pièces minimal. |
| max_roomsfacultatif | entier | Nombre de pièces maximal. |
| viagerfacultatif | exclude | only | Ventes en viager : écartées (exclude) ou seules retenues (only). Absent : incluses. |
| nue_proprietefacultatif | exclude | only | Ventes en nue-propriété : écartées ou seules retenues. Absent : incluses. |
| sourcesfacultatif | liste (a,b,c) | Plateformes, séparées par des virgules : au moins une annonce en ligne sur l’une d’elles (autre : plateforme inconnue). |
| labelsfacultatif | liste (a,b,c) | Libellés d’audit (TBA,BA…), droit valuations:read : ne garde que les biens valorisés. |
| on_sale_afterfacultatif | date-heure (ISO 8601) | Mises en vente à partir de cette date (ISO 8601). |
| sortfacultatif | recent | oldest | price_asc | price_desc | delta | recent (défaut) et oldest : date de mise en vente ; price_asc / price_desc : prix ; delta : meilleurs écarts au prix de marché d’abord (droit valuations:read). |
| limitfacultatif | entier, 1 à 100 | Taille de page, de 1 à 100 (50 par défaut). |
| cursorfacultatif | chaîne | next_cursor de la page précédente, tel quel (avec le même sort). |
Réponse 200
| Champ | Type | Description |
|---|---|---|
| data | tableau de objet | Annonces de la page. |
| ↳ id | uuid | Identifiant du bien (stable : un même bien vu sur plusieurs plateformes garde le même). |
| ↳ title | chaîne | Titre de l’annonce affichée. |
| ↳ property_typepeut être null | maison | appartement | Type de bien. |
| ↳ price | entier | Prix demandé, en euros. |
| ↳ price_per_sqmpeut être null | entier | Prix demandé au m², en euros. |
| ↳ surfacepeut être null | nombre | Surface habitable, en m². |
| ↳ surface_terrainpeut être null | nombre | Surface du terrain, en m². |
| ↳ roomspeut être null | entier | Nombre de pièces. |
| ↳ bedroomspeut être null | entier | Nombre de chambres. |
| ↳ construction_yearpeut être null | entier | Année de construction déclarée. |
| ↳ dpe_letterpeut être null | A | B | C | D | E | F | G | Classe énergie (DPE). |
| ↳ ges_letterpeut être null | A | B | C | D | E | F | G | Classe climat (GES). |
| ↳ works_neededpeut être null | none | light | moderate | heavy | Travaux à prévoir : aucun, légers, modérés, lourds. |
| ↳ outdoor_spacepeut être null | none | balcon | loggia | terrasse | jardin | Extérieur : aucun, balcon, loggia, terrasse ou jardin. |
| ↳ seller_typepeut être null | particulier | pro | Vendeur : particulier ou professionnel. |
| ↳ commune | objet | Commune du bien. |
| ↳ code | chaîne | Code INSEE. |
| ↳ name | chaîne | Nom de la commune. |
| ↳ positionpeut être null | objet | Position du bien ; null si inconnue. |
| ↳ lon | nombre | Longitude (WGS84). |
| ↳ lat | nombre | Latitude (WGS84). |
| ↳ precision | point | secteur | commune | point : adresse exacte ; secteur : zone floutée par la plateforme ; commune : centre de la commune. |
| ↳ radius_mpeut être null | entier | Rayon de la zone floutée, en mètres (secteur seulement). |
| ↳ photos | tableau de adresse (URL) | Adresses des photos, la principale d’abord. |
| ↳ sources | tableau de objet | Plateformes où le bien est en ligne. |
| ↳ id | chaîne | Identifiant normalisé de la plateforme (seloger, leboncoin… ; autre si inconnue). |
| ↳ name | chaîne | Nom lisible de la plateforme. |
| ↳ price_droppeut être null | objet | Dernière baisse de prix ; null si aucune. |
| ↳ pct | nombre | Baisse, en % (négatif). |
| ↳ from_price | entier | Prix avant la baisse. |
| ↳ to_price | entier | Prix après la baisse. |
| ↳ drops_count | entier | Nombre de baisses depuis la mise en vente. |
| ↳ days_ago | entier | Jours écoulés depuis la dernière baisse. |
| ↳ on_sale_since | date-heure (ISO 8601) | Mise en vente déclarée par les plateformes (à défaut, notre premier relevé). |
| ↳ first_seen_at | date-heure (ISO 8601) | Notre premier relevé du bien. |
| ↳ changes_count | entier | Nombre de modifications connues (prix, liens, titre, retraits…). |
| ↳ auditfacultatif | objet | Résumé de l’audit de prix, présent seulement avec le droit valuations:read. |
| ↳ statuspeut être null | OK | INSUFFICIENT_DATA | COVERAGE_UNAVAILABLE | OK : estimation disponible. INSUFFICIENT_DATA (aucune vente comparable) ou COVERAGE_UNAVAILABLE (pas de données DVF dans la commune) : ni estimation, ni libellé. null : pas encore valorisée. |
| ↳ estimated_pricepeut être null | entier | Prix de marché estimé, en euros, base prix affichés (comparable au prix demandé). |
| ↳ delta_pctpeut être null | nombre | Écart du prix demandé au prix de marché, en % (−12,5 = 12,5 % sous le marché). |
| ↳ labelpeut être null | TBA | BA | N | MA | TMA | TBA (très bonne affaire), BA (bonne affaire), N (dans le marché), MA (mauvaise affaire), TMA (très mauvaise affaire). |
| ↳ confidencepeut être null | nombre, 0 à 1 | Confiance de l’estimation, de 0 à 1 (nombre et proximité des ventes comparables). |
| ↳ location_precision | point | secteur | commune | Précision de la localisation qui a fondé l’estimation : adresse exacte, zone floutée par la plateforme, ou centre de la commune. |
| ↳ decote_unexplained | booléen | Bonne affaire apparente sans facteur de décote identifié : à vérifier. |
| next_cursorpeut être null | chaîne | À renvoyer dans cursor pour la page suivante ; null : dernière page. |
| totalfacultatif | entier | Nombre total de résultats, sur la première page seulement (sans curseur), plafonné à 10 000. |
| total_cappedfacultatif | booléen | Vrai si le total a atteint le plafond : il y a AU MOINS total résultats. |
Erreurs
400 · Requête invalide401 · Clé absente ou invalide403 · Droit manquant ou accès coupé429 · Limite atteinte503 · Requête trop longue
Toutes les erreurs ont la forme { "error": { "code", "message", "request_id" } } : voir Erreurs.