Recherche analytique PROPERTIES (Paris achat appartement)

Goal

Construire un dataset dédupliqué d’appartements à l’achat sur Paris (puis l’Île-de-France), paginer pour l’exhaustivité, et calculer des statistiques prix au m² par département — sans biais lié aux doublons inter-portails.

Scénario

Vous êtes une fintech ou une équipe analytics qui doit cartographier le marché parisien : stock disponible, médianes prix/m², distribution par dpt. Compter les annonces brutes (Adverts) gonfle le volume car chaque bien est publié sur 3-8 portails. Vous travaillez donc sur Properties (entités dédupliquées) avec pagination cursor et un workflow reproductible.

Étapes

1. Choisir Properties (et pas Adverts)

Une Property = 1 bien physique unique = N adverts agrégés. C’est l’objet à utiliser pour tout calcul agrégé : compter des biens (pas des publications), médianes prix, stocks, durées en ligne.Détail de l’asymétrie et des anti-patterns : /concepts/property-vs-advert.

2. Construire le payload — combo standard prod

Trois bonnes pratiques :

meta.isTotallyOffline: false → exclut les biens dont toutes les adverts sont offline (sinon votre stock contient des fantômes).
sortBy: "FIRST_SEEN_AT" + orderBy: "DESC" → vous parcourez du plus récent au plus ancien, idéal pour reprendre une exploration à chaud.
meta.firstSeenAt.min → borne temporelle pour ignorer le très ancien (typiquement 2025-01-01T00:00:00.000Z).
size: 100 → max autorisé sur l’endpoint full search (lite est plafonné à 25).

curl -X POST "https://api.fluximmo.io/v2/protected/properties/search" \
  -H "x-api-key: $FLUXIMMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 100,
    "sortBy": "FIRST_SEEN_AT",
    "orderBy": "DESC",
    "search": {
      "filterProperty": {
        "location": [{ "postalCode": "75001" }],
        "type": ["CLASS_FLAT", "CLASS_HOUSE", "CLASS_PROGRAM"],
        "offer": [{ "type": "OFFER_BUY" }],
        "price": { "initial": { "value": { "min": 100000, "max": 350000 } } },
        "habitation": {
          "surface":     { "total": { "min": 30, "max": 110 } },
          "bedroomCount":{ "min": 1, "max": 3 }
        },
        "meta": {
          "isTotallyOffline": false,
          "firstSeenAt": { "min": "2025-01-01T00:00:00.000Z" }
        }
      }
    }
  }'

3. Lire le `searchAfterHash` retourné

La réponse est wrappée sous data et contient items[] (jusqu’à 100 properties), count, et un champ searchAfterHash. C’est un cursor opaque : ne le décodez pas, contentez-vous de le replacer dans la requête suivante.

{
  "data": {
    "items": [ /* up to 100 Property */ ],
    "count": 1247,
    "searchAfterHash": "eyJzZWFyY2hfYWZ0ZXIiOlsxNzM..."
  }
}

4. Paginer pour exhaustivité (boucle cursor)

Boucle : tant que la dernière page ramène size items, replongez avec searchAfterHash. Stoppez quand len(items) < size (fin du dataset) ou quand votre cap user-defined est atteint.

# Pseudocode pagination
all_items = []
cursor = null
HARD_CAP = 5000

while all_items.length < HARD_CAP:
    payload = base_payload
    if cursor: payload.searchAfterHash = cursor

    resp = POST /v2/protected/properties/search (payload)
    items = resp.data.items
    all_items.append_all(items)

    if items.length < SIZE: break        # dernière page
    cursor = resp.data.searchAfterHash
    if !cursor: break

Deuxième page en curl direct :

curl -X POST "https://api.fluximmo.io/v2/protected/properties/search" \
  -H "x-api-key: $FLUXIMMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 100,
    "sortBy": "FIRST_SEEN_AT",
    "orderBy": "DESC",
    "searchAfterHash": "<cursor de la page 1>",
    "search": { "filterProperty": { "location": [{"postalCode":"75001"}], "type": ["CLASS_FLAT"], "offer": [{"type":"OFFER_BUY"}], "meta": {"isTotallyOffline": false} } }
  }'

5. Calculer le prix au m² par département

Une fois le dataset collecté, agrégez par les 2 premiers caractères du postalCode (= département).

# Pseudocode agrégation
by_dpt = {}
foreach p in all_items:
    cp        = p.location.postalCode
    price_psm = p.price.latest.valuePerArea
    if cp and price_psm:
        dpt = cp[0..2]
        by_dpt[dpt].append(price_psm)

foreach dpt, vals in by_dpt:
    sort(vals)
    n   = vals.length
    q1  = vals[floor(0.25 * (n - 1))]
    med = vals[floor(0.50 * (n - 1))]
    q3  = vals[floor(0.75 * (n - 1))]
    print(dpt, n, q1, med, q3)

6. Étendre à toute l'Île-de-France (multi-zones OR)

Pour passer de Paris-1er à Paris + petite couronne, remplacez location[] par 4 zones combinées en OR.

{
  "size": 100,
  "sortBy": "FIRST_SEEN_AT",
  "orderBy": "DESC",
  "search": {
    "filterProperty": {
      "location": [
        { "department": "75" },
        { "department": "92" },
        { "department": "93" },
        { "department": "94" }
      ],
      "type": ["CLASS_FLAT"],
      "offer": [{ "type": "OFFER_BUY" }],
      "meta": {
        "isTotallyOffline": false,
        "firstSeenAt": { "min": "2025-01-01T00:00:00.000Z" }
      }
    }
  }
}

Logique multi-zones complète et autres modes (bbox, geoDistance) : /concepts/recherche-geographique.

Architecture / flow

Pièges fréquents

Confondre Properties et Adverts → analytics biaisé : un même bien compté 3-8 fois (1 par portail) gonfle le stock et fausse les médianes. Toujours Properties pour les KPIs marché.
Oublier meta.isTotallyOffline: false → vous comptez des biens dont toutes les annonces sont offline (fantômes du catalogue).
Tenter une pagination par offset : ça n’existe pas. Le seul mode est cursor searchAfterHash. Ne décodez pas le cursor — c’est opaque.
Mixer postalCode et city dans la même entrée : city est ignoré par le moteur. Voir warning city deprecated.
Dépasser size max : 100 sur full search, 25 sur lite search. Au-delà, l’API reject ou tronque.
Ne pas dédoublonner sur flxId entre pages : un append concurrent peut renvoyer un même item deux fois si le tri change. Conservez un set des flxId vus.

Démarrer

Concepts principaux

Playbooks

Capabilities sur demande

Ressources

Goal

Scénario

Étapes

Architecture / flow

Pièges fréquents

Pour aller plus loin

​Goal

​Scénario

​Étapes

​Architecture / flow

​Pièges fréquents

​Pour aller plus loin

Goal

Scénario

Étapes

Architecture / flow

Pièges fréquents

Pour aller plus loin