Démarrer
Pagination
Les listes se lisent page par page, avec un curseur : un repère opaque que vous renvoyez tel quel pour obtenir la suite.
Lire la page suivante
Chaque page donne next_cursor. Renvoyez-le tel quel dans le paramètre cursor, avec les mêmes filtres et le même tri, pour obtenir la page suivante. Ne le décodez pas et ne le fabriquez pas : son format peut changer.
| Point d’entrée | Taille de page (limit) | Fin de la liste |
|---|---|---|
/v1/listings | 1 à 100, 50 par défaut | next_cursor vaut null. |
/v1/market/sales | 1 à 200, 100 par défaut | next_cursor vaut null. |
/v1/changes | 1 à 500, 100 par défaut | has_more vaut false ; next_cursor est toujours fourni, pour reprendre plus tard. |
Le flux des changements a ses propres règles (reprise, expiration) : voir Synchroniser un secteur.
Des curseurs stables
Le curseur retient la position du dernier élément lu, pas un numéro de page. Les biens ajoutés ou retirés entre deux pages ne décalent donc pas la lecture : aucun bien ne saute ni ne se répète à cause d’eux, et une page lointaine se lit aussi vite que la première. Lisez les pages à votre rythme ; un curseur d’annonces ou de ventes n’expire pas.
Seule exception : un bien dont la valeur de tri change pendant votre parcours (son prix, avec un tri par prix) peut changer de place. Pour une copie exacte d’un secteur, complétez l’import par le flux des changements.
Un curseur va avec son tri
Un curseur obtenu avec un tri ne vaut que pour ce tri : changer sort en cours de route répond 400 invalid_cursor. De même, un curseur ne sert qu’au point d’entrée qui l’a donné. Le curseur ne retient pas les filtres : renvoyez-les à l’identique à chaque page, sinon la suite ne correspond plus au début, sans erreur pour vous prévenir.
Le total
GET /v1/listings donne total et total_capped sur la première page seulement (requête sans curseur). Le total est plafonné à 10 000 : au-delà, total vaut 10 000 et total_capped vaut true, ce qui signifie « au moins 10 000 ». Pour un compte exact, découpez le secteur (par département, par commune) ou ajoutez des filtres.
/v1/market/sales et /v1/changes ne donnent pas de total.
Chaque page est une requête, décomptée de vos limites : 10 000 annonces lues par pages de 100 font 100 requêtes. Voir Limites et quotas.