{"genere_le":"2026-09-26T22:05:16.065Z","api":{"nom":"API cherchertrouver.immo","version":"1.0.0","base_url":"https://cherchertrouver.immo/api/v1","description":"API d'accès aux annonces immobilières agrégées de nombreux sites. Données du bien, prix, prix au m², DPE/GES, localisation approximative.\n\nConfidentialité : par défaut, l'API ne redistribue AUCUNE donnée de contact. Le champ `seller_name` est `null` pour les vendeurs particuliers, et la `description` est expurgée des téléphones et emails. Les coordonnées GPS sont arrondies à ~111 m. Pour joindre le vendeur, suivre `external_url` vers la fiche d'origine.\n\nOption `seller_contact` : sur autorisation explicite et nominative, un compte peut recevoir les coordonnées PROFESSIONNELLES de l'agence ou du mandataire rattaché à l'annonce. Cette option n'est jamais active par défaut, ne concerne jamais un vendeur particulier, et ne renseigne le champ que lorsqu'elle est ouverte ; sinon il vaut null.","documentation":"https://cherchertrouver.immo/api/docs","openapi":"https://cherchertrouver.immo/openapi.json"},"authentification":{"entetes":["X-Api-Key: VOTRE_CLE","Authorization: Bearer VOTRE_CLE"],"obtention":"https://cherchertrouver.immo/account#devSection","avertissement":"Ne jamais exposer la clé côté navigateur ou application mobile."},"quotas":{"principe":"Deux quotas, qui ne se remplacent pas. Le JOURNALIER protège le service ; le MENSUEL délimite l’offre souscrite et se compte sur la période de facturation (sur une fenêtre glissante de 30 jours pour l’offre gratuite, qui n’a pas d’abonnement). Les deux comptent les annonces UNIQUES découvertes, pas les requêtes : une même annonce revue plusieurs fois ne compte qu’une fois.","au_dela":"Au-delà du quota mensuel, les annonces NEUVES reçoivent un 402 de code ITEMS_QUOTA. Le corps porte quota, consomme, la date de reprise (repart_le sur un abonnement, se_libere_le sur la fenêtre glissante) et palier_suivant. Seul /ping continue de répondre : le refus est posé avant la recherche, donc même une annonce déjà connue renvoie 402. Ne pas réessayer en boucle, lire la date de reprise.","entetes_de_suivi":["X-RateLimit-Limit","X-RateLimit-Remaining","X-RateLimit-Reset","X-Quota-Items-Limit","X-Quota-Items-Used","X-Quota-Requests-Limit","X-Quota-Requests-Used","X-Quota-Mois-Limit","X-Quota-Mois-Used","X-Quota-Mois-Remaining","X-Quota-Mois-Reset"]},"codes_erreur":[{"code":400,"sens":"Paramètre absent ou hors bornes. La réponse nomme le champ fautif."},{"code":401,"sens":"Clé absente, invalide ou révoquée."},{"code":402,"sens":"Quota dépassé. Code QUOTA_EXCEEDED pour le plafond JOURNALIER, ITEMS_QUOTA pour le quota MENSUEL de l’offre (le corps porte alors la date de reprise et le palier suivant), PAID_PLAN_REQUIRED pour le filtre par site, réservé aux offres à partir de 118,80 EUR TTC par mois."},{"code":404,"sens":"Ressource inexistante."},{"code":422,"sens":"Paramètres valides, mais rien à calculer avec ces valeurs."},{"code":429,"sens":"Trop de requêtes : ralentir et respecter X-RateLimit-Reset."}],"endpoints":[{"methode":"GET","chemin":"/api/v1/health","resume":"État du service, sans clé API","description":"Sonde de supervision. Ne demande aucune authentification, et c’est voulu : un moniteur externe doit pouvoir constater une panne sans détenir de secret. Renvoie 503 quand la base applicative ne répond pas.","parametres":[]},{"methode":"GET","chemin":"/api/v1/sources","resume":"Sites disponibles","description":"Identifiants EXACTS des sites présents en base, à utiliser dans le paramètre `sources`. Réservé aux offres à partir de 118,80 € TTC par mois : en dessous, 402 PAID_PLAN_REQUIRED. Seuls les noms sont publiés, sans volume ni fraîcheur.","parametres":[]},{"methode":"GET","chemin":"/api/v1/ping","resume":"Vérifie la clé et retourne les quotas","description":null,"parametres":[]},{"methode":"GET","chemin":"/api/v1/annonces","resume":"Recherche paginée d'annonces","description":"Recherche multi-critères. Pour parcourir en profondeur, préférer `cursor` (pagination O(1)) à `page`. Le quota `items_per_day` ne décompte que les couples (source, reference) NOUVEAUX pour la clé.","parametres":[{"nom":"q","requis":false,"type":"string","description":"Recherche plein texte (titre + description)."},{"nom":"type","requis":false,"type":"string","description":"Type de bien (Appartement, Maison, Terrain...)."},{"nom":"transaction","requis":false,"type":"string","description":null,"valeurs":["vente","location"]},{"nom":"ville","requis":false,"type":"string","description":"Une ou plusieurs villes (séparées par des virgules, max 8)."},{"nom":"cp","requis":false,"type":"string","description":"Code postal."},{"nom":"dept","requis":false,"type":"string","description":"Département."},{"nom":"region","requis":false,"type":"string","description":null},{"nom":"prix_min","requis":false,"type":"integer","description":null,"min":0},{"nom":"prix_max","requis":false,"type":"integer","description":null,"min":0},{"nom":"prix_m2_min","requis":false,"type":"integer","description":null,"min":0},{"nom":"prix_m2_max","requis":false,"type":"integer","description":null,"min":0},{"nom":"surface_min","requis":false,"type":"number","description":null,"min":0},{"nom":"surface_max","requis":false,"type":"number","description":null,"min":0},{"nom":"pieces_min","requis":false,"type":"integer","description":null,"min":0},{"nom":"chambres_min","requis":false,"type":"integer","description":null,"min":0},{"nom":"annee_min","requis":false,"type":"integer","description":"Année de construction minimale. Renseignée sur environ 35 % des annonces : ce filtre écarte donc aussi les biens dont l'année est inconnue. Utilisable pour trouver du récent à coup sûr (inclusion), pas pour affirmer qu'un secteur n'en contient pas.","min":1700,"max":2100},{"nom":"annee_max","requis":false,"type":"integer","description":"Année de construction maximale. Même réserve de couverture que annee_min.","min":1700,"max":2100},{"nom":"dpe","requis":false,"type":"array","description":"Classes DPE acceptées (répétable ou CSV)."},{"nom":"ges","requis":false,"type":"array","description":"Classes GES acceptées (répétable ou CSV)."},{"nom":"source","requis":false,"type":"string","description":"OBSOLÈTE et sans effet : ce paramètre n’a jamais filtré quoi que ce soit. Il reste accepté pour ne casser aucun appel existant. Pour restreindre à certains sites, utiliser `sources`.","valeurs":["all","interne","scraped"]},{"nom":"sources","requis":false,"type":"string","description":"Sites voulus, séparés par des virgules : `site_a,site_b`. Les identifiants exacts sont donnés par /sources. Réservé aux offres à partir de 118,80 € TTC par mois (402 sinon). Un nom inconnu au milieu de noms valides n’est pas bloquant : il est signalé dans l’en-tête X-Unknown-Sources."},{"nom":"exclude_sources","requis":false,"type":"string","description":"Sites à ÉCARTER, séparés par des virgules : `site_a`. Le miroir de `sources`, plus pratique quand on veut presque tout : une liste blanche se périme dès qu’un site est ajouté, une liste noire non. Mêmes règles : identifiants exacts donnés par /sources, réservé aux offres à partir de 118,80 € TTC par mois (402 sinon), inconnus signalés dans X-Unknown-Sources. Combinable avec `sources` (la différence est appliquée) ; si cette différence est vide, la requête est refusée en 400 plutôt que de rendre zéro annonce sans explication. Si AUCUN nom à exclure n’existe, 400 également : l’exclusion n’aurait aucun effet et le client recevrait précisément ce qu’il voulait écarter."},{"nom":"sort","requis":false,"type":"string","description":null,"valeurs":["recent","price_asc","price_desc","surface_desc","pricem2_asc"],"defaut":"recent"},{"nom":"updated_since","requis":false,"type":"string","description":"Annonces (re-)scrapées depuis cette date (ISO 8601). Pour la veille incrémentale, combiner avec sort=recent."},{"nom":"created_since","requis":false,"type":"string","description":"Annonces publiées sur le site source depuis cette date (ISO 8601)."},{"nom":"page","requis":false,"type":"integer","description":"Numéro de page (1..1000). Préférer cursor au-delà de 50.","min":1,"max":1000},{"nom":"page_size","requis":false,"type":"integer","description":"Taille de page (max 100).","min":1,"max":100,"defaut":25},{"nom":"cursor","requis":false,"type":"string","description":"Curseur opaque de pagination (fourni par next_cursor)."}]},{"methode":"GET","chemin":"/api/v1/annonces/feed","resume":"Flux complet (changefeed) sans plafond de profondeur","description":"Aspire tout le catalogue sans jamais rater d'annonce. Boucler avec `cursor` : appeler sans cursor, traiter `items`, rappeler avec `?cursor=<next_cursor>`. Quand `has_more=false`, rappeler avec le MÊME cursor pour récupérer les nouvelles annonces.","parametres":[{"nom":"type","requis":false,"type":"string","description":"Type de bien (Appartement, Maison, Terrain...)."},{"nom":"ville","requis":false,"type":"string","description":"Une ou plusieurs villes (séparées par des virgules, max 8)."},{"nom":"dept","requis":false,"type":"string","description":"Département."},{"nom":"page_size","requis":false,"type":"integer","description":"Taille de page (max 100).","min":1,"max":100,"defaut":25},{"nom":"cursor","requis":false,"type":"string","description":"Curseur opaque de pagination (fourni par next_cursor)."},{"nom":"sources","requis":false,"type":"string","description":"Sites voulus, séparés par des virgules : `site_a,site_b`. Les identifiants exacts sont donnés par /sources. Réservé aux offres à partir de 118,80 € TTC par mois (402 sinon). Un nom inconnu au milieu de noms valides n’est pas bloquant : il est signalé dans l’en-tête X-Unknown-Sources."},{"nom":"exclude_sources","requis":false,"type":"string","description":"Sites à ÉCARTER, séparés par des virgules : `site_a`. Le miroir de `sources`, plus pratique quand on veut presque tout : une liste blanche se périme dès qu’un site est ajouté, une liste noire non. Mêmes règles : identifiants exacts donnés par /sources, réservé aux offres à partir de 118,80 € TTC par mois (402 sinon), inconnus signalés dans X-Unknown-Sources. Combinable avec `sources` (la différence est appliquée) ; si cette différence est vide, la requête est refusée en 400 plutôt que de rendre zéro annonce sans explication. Si AUCUN nom à exclure n’existe, 400 également : l’exclusion n’aurait aucun effet et le client recevrait précisément ce qu’il voulait écarter."}]},{"methode":"GET","chemin":"/api/v1/annonces/retirees","resume":"Annonces retirées du marché par leur site d'origine","description":"Énumération complète et reprenable des biens dont le site d'origine déclare le retrait (vendu, sous compromis, retiré, loué, sous offre, mise en pause). Boucler avec `cursor`, comme /annonces/feed.\n\nDEUX LIMITES À CONNAÎTRE. `retired_at` n'est connu que sur une PARTIE des lignes et vaut `null` ailleurs : ce flux n'est donc PAS un delta par date, et il n'accepte aucun filtre temporel. Et seuls certains sites nous déclarent le retrait : l'absence d'une annonce de ce flux ne signifie pas qu'elle est encore au marché.\n\nLa réponse ne porte ni prix, ni description, ni photos : elle sert à réconcilier un stock déjà collecté. Elle ne consomme pas de quota d'annonces.","parametres":[{"nom":"page_size","requis":false,"type":"integer","description":"Taille de page (max 100).","min":1,"max":100,"defaut":25},{"nom":"cursor","requis":false,"type":"string","description":"Curseur opaque de pagination (fourni par next_cursor)."},{"nom":"sources","requis":false,"type":"string","description":"Sites voulus, séparés par des virgules : `site_a,site_b`. Les identifiants exacts sont donnés par /sources. Réservé aux offres à partir de 118,80 € TTC par mois (402 sinon). Un nom inconnu au milieu de noms valides n’est pas bloquant : il est signalé dans l’en-tête X-Unknown-Sources."},{"nom":"exclude_sources","requis":false,"type":"string","description":"Sites à ÉCARTER, séparés par des virgules : `site_a`. Le miroir de `sources`, plus pratique quand on veut presque tout : une liste blanche se périme dès qu’un site est ajouté, une liste noire non. Mêmes règles : identifiants exacts donnés par /sources, réservé aux offres à partir de 118,80 € TTC par mois (402 sinon), inconnus signalés dans X-Unknown-Sources. Combinable avec `sources` (la différence est appliquée) ; si cette différence est vide, la requête est refusée en 400 plutôt que de rendre zéro annonce sans explication. Si AUCUN nom à exclure n’existe, 400 également : l’exclusion n’aurait aucun effet et le client recevrait précisément ce qu’il voulait écarter."}]},{"methode":"GET","chemin":"/api/v1/annonces/map","resume":"Annonces dans une emprise géographique (bbox)","description":null,"parametres":[{"nom":"bbox","requis":true,"type":"string","description":"Emprise au format south,west,north,east (latitudes/longitudes)."},{"nom":"type","requis":false,"type":"string","description":"Type de bien (Appartement, Maison, Terrain...)."},{"nom":"transaction","requis":false,"type":"string","description":null,"valeurs":["vente","location"]},{"nom":"sources","requis":false,"type":"string","description":"Sites voulus, séparés par des virgules : `site_a,site_b`. Les identifiants exacts sont donnés par /sources. Réservé aux offres à partir de 118,80 € TTC par mois (402 sinon). Un nom inconnu au milieu de noms valides n’est pas bloquant : il est signalé dans l’en-tête X-Unknown-Sources."},{"nom":"exclude_sources","requis":false,"type":"string","description":"Sites à ÉCARTER, séparés par des virgules : `site_a`. Le miroir de `sources`, plus pratique quand on veut presque tout : une liste blanche se périme dès qu’un site est ajouté, une liste noire non. Mêmes règles : identifiants exacts donnés par /sources, réservé aux offres à partir de 118,80 € TTC par mois (402 sinon), inconnus signalés dans X-Unknown-Sources. Combinable avec `sources` (la différence est appliquée) ; si cette différence est vide, la requête est refusée en 400 plutôt que de rendre zéro annonce sans explication. Si AUCUN nom à exclure n’existe, 400 également : l’exclusion n’aurait aucun effet et le client recevrait précisément ce qu’il voulait écarter."}]},{"methode":"GET","chemin":"/api/v1/annonces/{source}/{reference}","resume":"Détail d'une annonce","description":null,"parametres":[{"nom":"source","requis":true,"type":"string","description":null},{"nom":"reference","requis":true,"type":"string","description":null}]},{"methode":"GET","chemin":"/api/v1/ptz/zone","resume":"Zone PTZ (Abis/A/B1/B2/C) d'une commune","description":"Zonage officiel (arrêté du 5 septembre 2025). Lecture seule.","parametres":[{"nom":"cp","requis":true,"type":"string","description":"Code postal (5 chiffres)."}]}]}