Guides

Synchroniser un secteur

Pour tenir une copie à jour d’un secteur, importez-le une fois, puis appliquez le flux des changements. Le parcours ci-dessous ne perd aucun événement.

Droits nécessaires : listings:read pour l’import et changes:read pour le flux (plus valuations:read pour suivre l’audit).

Le parcours

Notez la tête du flux. GET /v1/changes sans curseur répond sans événement, avec un next_cursor qui marque « maintenant ». Gardez-le.
Importez le secteur. GET /v1/listings, toutes les pages (voir Pagination). Enregistrez chaque bien sous son id.
Suivez le flux. GET /v1/changes?cursor=… avec le curseur noté à l’étape 1, puis, à chaque appel, le dernier next_cursor reçu.

Notez la tête avant l’import : les changements survenus pendant l’import vous seront rejoués. Écrivez par « upsert » (insérer ou remplacer) : appliquer deux fois le même événement est alors sans effet.

Les événements

type	Sens
`created`	Un bien entre dans le flux : nouveau bien en vente.
`price_changed`	Le prix a changé : `old_price` → `new_price`. `changed_fields` contient `price`, et d’autres champs s’ils ont changé en même temps.
`updated`	Autre modification : les champs touchés sont dans `changed_fields`.
`removed`	Le bien a quitté le flux : vendu, retiré, ou fusionné avec un doublon. `listing` vaut `null`.

Chaque événement porte listing_id, occurred_at et listing : l’état courant du bien au moment de votre lecture (pas celui de l’instant de l’événement), ou null s’il a quitté le flux depuis. La règle la plus simple : listing présent, enregistrez-le ; listing à null, supprimez le bien.

Champs possibles de changed_fields : price, title, property_type, surface, surface_terrain, rooms, bedrooms, commune, position, photos, sources, dpe, audit, on_sale_since. audit signale un statut ou un libellé changé, ou une estimation déplacée de plus de 1 % ; sans le droit valuations:read, ces modifications ne vous sont pas envoyées. Un recalcul qui ne change rien de visible ne produit aucun événement.

Filtrer le flux

departement : un ou plusieurs départements, séparés par des virgules (20 au plus).
types : types d’événements, séparés par des virgules (created,price_changed…). Pour tenir une copie, gardez-les tous : sans removed, vous garderiez des biens disparus.
limit : de 1 à 500 événements par page, 100 par défaut.

Le flux ne se filtre pas par commune. Pour un secteur plus petit qu’un département, filtrez de votre côté sur listing.commune.code ; un removed, sans listing, se traite en supprimant l’id s’il est chez vous.

Lire jusqu’au bout, puis attendre

has_more: true : d’autres événements attendent déjà, relancez tout de suite avec next_cursor. has_more: false : vous êtes à jour, attendez avant l’appel suivant ; un appel par minute fait 1 440 requêtes par jour. Fiez-vous à has_more, pas au nombre d’événements : une page peut en compter moins que limit, voire aucun.

next_cursor est toujours fourni, même sans événement. Enregistrez-le à chaque page, dans la même transaction que vos écritures : après une interruption, vous reprenez exactement où vous en étiez.

Reprendre après une longue interruption

Les événements sont gardés 30 jours. Un curseur plus ancien répond 410 cursor_expired : réimportez le secteur en reprenant le parcours à l’étape 1.

Sans curseur, since (date-heure ISO 8601) fait repartir le flux d’une date des 30 derniers jours ; plus loin, la réponse est 400 since_too_old. Avec un curseur, since est ignoré. Le curseur reste le moyen sûr de reprendre : since peut vous rejouer des événements déjà appliqués.

Délai de diffusion

Si votre plan a un délai de diffusion, le flux est décalé d’autant : un nouveau bien y entre (created) au moment où il devient visible pour vous, comme dans la recherche.

Le détail de chaque champ est dans la référence.