Guides
Rechercher des annonces
GET /v1/listings cherche les biens en vente dans un secteur, les filtre et les trie. Chaque résultat est un bien dédoublonné, avec toutes ses plateformes.
Choisir un secteur
Indiquez un et un seul secteur. Sans secteur, ou avec deux, la réponse est 400 validation_error.
| Paramètres | Secteur |
|---|---|
commune | Une ou plusieurs communes, par code INSEE, séparés par des virgules (50 au plus) : commune=83137,83069. Paris (75056), Lyon (69123) et Marseille (13055) : le code de la ville réunit ses arrondissements ; un arrondissement se demande aussi par son propre code (13208). |
departement | Code de département : 13, 2A, 974. |
region | Code INSEE de région : 93 pour Provence-Alpes-Côte d’Azur. |
lat, lon, radius_m | Cercle autour d’un point, de 100 à 50 000 mètres de rayon. Les trois paramètres vont ensemble. |
bbox | Cadre minLon,minLat,maxLon,maxLat (WGS84), minimums strictement inférieurs aux maximums. |
Un cercle ou un cadre ne retient que les biens dont la position est connue ; un bien sans position se trouve par sa commune, son département ou sa région.
Filtrer
| Paramètres | Effet |
|---|---|
property_type | appartement ou maison. |
min_price, max_price | Prix demandé, en euros. |
min_surface, max_surface | Surface habitable, en m². |
min_surface_terrain, max_surface_terrain | Surface du terrain, en m². |
min_rooms, max_rooms | Nombre de pièces. |
viager | exclude écarte les ventes en viager, only ne garde qu’elles. Absent : incluses. |
nue_propriete | Même chose pour les ventes en nue-propriété : exclude ou only. |
sources | Plateformes, séparées par des virgules (30 au plus) : biens en ligne sur au moins l’une d’elles. Identifiants en minuscules, tels qu’ils apparaissent dans sources[].id ; autre désigne une plateforme inconnue. |
labels | Libellés d’audit (TBA,BA…) : ne garde que les biens valorisés qui portent l’un d’eux. Droit valuations:read. |
on_sale_after | Biens mis en vente à partir de cet instant, en date-heure ISO 8601 complète : 2026-10-01T00:00:00Z. |
Les filtres se cumulent. Un filtre sur une caractéristique écarte les biens qui ne la déclarent pas : un bien dont la surface est inconnue ne passe pas min_surface. Un min_price supérieur à max_price répond 400 validation_error.
Trier
| sort | Ordre |
|---|---|
recent | Par défaut. Mises en vente les plus récentes d’abord (date déclarée par les plateformes, à défaut notre premier relevé). |
oldest | Mises en vente les plus anciennes d’abord. |
price_asc | Prix croissant. |
price_desc | Prix décroissant. |
delta | Plus fortes décotes d’abord (prix demandé le plus en dessous du prix de marché). Ne garde que les biens valorisés. Droit valuations:read. |
Les pages font 50 biens par défaut, 100 au plus (limit). La première page donne le total, plafonné à 10 000. Voir Pagination.
La fiche d’un bien
GET /v1/listings/{id} reprend les champs de la recherche et ajoute la description complète, les liens vers chaque plateforme (urls), la présence du bien sur chacune avec son prix et son état (portals), l’adresse déclarée et l’adresse retrouvée (address : exacte, ou probable avec jusqu’à 5 candidates), les relevés de prix, les faits déclarés (étage, référence…), les risques naturels et technologiques, la délinquance de la commune et l’environnement du quartier. Avec le droit valuations:read, audit y ajoute les facteurs de décote.
La fiche d’un bien retiré du marché reste lisible : delisted_at donne alors la date du retrait. Un identifiant inconnu, ou un bien pas encore diffusé pour votre plan, répond 404 not_found. Voir la référence.
L’historique d’un bien
GET /v1/listings/{id}/history donne la chronologie des modifications, de la plus ancienne à la plus récente (events), et la courbe de prix de chaque plateforme (price_series). Chaque événement a une nature (kind) :
price(prix modifié,old_price→new_price),price_removed(prix retiré de l’annonce) ;url_replaced(annonce republiée sous un nouveau lien),url_removed(une annonce du bien retirée),new_portal(bien apparu sur une nouvelle plateforme),merged(annonces réunies comme un même bien) ;title,description,photo(contenu modifié),bump(annonce remontée en tête de liste sans autre changement) ;delisted(annonce retirée d’une plateforme),relisted(remise en ligne).
source indique la plateforme concernée quand elle est connue. Voir la référence.