Pagination

POST /properties expose deux modes via le champ discriminant paginationType (enum "PAGE" ou "CURSOR", défaut "PAGE").

`paginationType: "PAGE"` — offset classique

Simple et lisible, mais peut renvoyer des doublons ou omettre des items si la donnée évolue entre deux pages.

{
  "paginationType": "PAGE",
  "page": 1,
  "size": 20,
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

Incrémentez page jusqu'à meta.hasNextPage === false.

`paginationType: "CURSOR"` — curseur stable

Recommandé pour le scraping / export / listes longues. Stable même si des items sont insérés entre appels.

Première requête

Omettez cursor (ou envoyez null) :

{
  "paginationType": "CURSOR",
  "size": 50,
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

Réponse

Au format JSON:API (défaut), les biens sont dans data[] et la pagination dans meta :

{
  "data": [ /* 50 ressources Property */ ],
  "meta": {
    "totalItems": 4231,
    "hasNextPage": true,
    "cursor": "eyJzb3J0IjpbMTc3ODg0NDY0MzAwMCwiMDE5Z...",
    "pagination": {
      "type": "CURSOR",
      "size": 50,
      "nextRequestBody": { /* la requête suivante, prête à renvoyer */ }
    }
  },
  "links": { "self": "/properties" },
  "included": [ /* Listing, Publisher, PropertyPublisher, Source */ ]
}

meta.pagination.nextRequestBody contient le corps complet de la requête suivante (critères + curseur) : vous pouvez le renvoyer tel quel.

Page suivante

Renvoyez tel quel le meta.cursor reçu dans la réponse précédente :

{
  "paginationType": "CURSOR",
  "size": 50,
  "cursor": "eyJzb3J0IjpbMTc3ODg0NDY0MzAwMCwiMDE5Z...",
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

Bouclez jusqu'à meta.hasNextPage === false. Le cursor est opaque — ne tentez pas de l'analyser, contentez-vous de le réémettre.

Compter sans récupérer les biens

Pour connaître le nombre de biens qui correspondent à vos critères sans les recevoir — un compteur à côté d'un filtre, une estimation de volume avant un export — envoyez size: 0 :

{
  "size": 0,
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

La réponse ne contient aucun bien ; le nombre est dans meta.totalItems :

{
  "data": [],
  "meta": {
    "totalItems": 243
    /* … */
  }
}

Le nombre se lit au format JSON:API (défaut). Avec Accept: application/json, la réponse est un tableau nu, donc vide : elle ne porte pas le nombre.
En mode PAGE, meta.totalItems est plafonné à 10 000.

Limites

size : de 0 à 100 par requête (défaut 10). 0 renvoie uniquement le nombre de résultats.
meta.totalItems est toujours renvoyé, utile pour afficher un total même en mode CURSOR.
Avec Accept: application/json (format à plat), POST /properties renvoie un tableau nu sans totalItems, hasNextPage ni cursor : paginez au format JSON:API. Voir Format de réponse.
page est ignoré en mode CURSOR ; cursor est ignoré en mode PAGE.