# API cherchertrouver.immo > 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. - Version : 1.0.0 - Racine : https://cherchertrouver.immo/api/v1 - Documentation : https://cherchertrouver.immo/api/docs - Spécification OpenAPI : https://cherchertrouver.immo/openapi.json ## Authentification Toute requête porte une clé, via l’un de ces en-têtes : - `X-Api-Key: VOTRE_CLE` - `Authorization: Bearer VOTRE_CLE` Ne jamais exposer la clé côté navigateur ou application mobile. ## Quotas 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-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. En-têtes 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 de réponse - **400** : Paramètre absent ou hors bornes. La réponse nomme le champ fautif. - **401** : Clé absente, invalide ou révoquée. - **402** : 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. - **404** : Ressource inexistante. - **422** : Paramètres valides, mais rien à calculer avec ces valeurs. - **429** : Trop de requêtes : ralentir et respecter X-RateLimit-Reset. ## Points d’accès ### GET /api/v1/health État du service, sans clé API ### GET /api/v1/sources Sites disponibles ### GET /api/v1/ping Vérifie la clé et retourne les quotas ### GET /api/v1/annonces Recherche paginée d'annonces - `q`, optionnel, string : Recherche plein texte (titre + description). - `type`, optionnel, string : Type de bien (Appartement, Maison, Terrain...). - `transaction`, optionnel, string, valeurs : vente | location - `ville`, optionnel, string : Une ou plusieurs villes (séparées par des virgules, max 8). - `cp`, optionnel, string : Code postal. - `dept`, optionnel, string : Département. - `region`, optionnel, string - `prix_min`, optionnel, integer, bornes : 0 à … - `prix_max`, optionnel, integer, bornes : 0 à … - `prix_m2_min`, optionnel, integer, bornes : 0 à … - `prix_m2_max`, optionnel, integer, bornes : 0 à … - `surface_min`, optionnel, number, bornes : 0 à … - `surface_max`, optionnel, number, bornes : 0 à … - `pieces_min`, optionnel, integer, bornes : 0 à … - `chambres_min`, optionnel, integer, bornes : 0 à … - `annee_min`, optionnel, integer, bornes : 1700 à 2100 : 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. - `annee_max`, optionnel, integer, bornes : 1700 à 2100 : Année de construction maximale. Même réserve de couverture que annee_min. - `dpe`, optionnel, array : Classes DPE acceptées (répétable ou CSV). - `ges`, optionnel, array : Classes GES acceptées (répétable ou CSV). - `source`, optionnel, string, valeurs : all | interne | scraped : 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`. - `sources`, optionnel, string : 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. - `exclude_sources`, optionnel, string : 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. - `sort`, optionnel, string, valeurs : recent | price_asc | price_desc | surface_desc | pricem2_asc, défaut : recent - `updated_since`, optionnel, string : Annonces (re-)scrapées depuis cette date (ISO 8601). Pour la veille incrémentale, combiner avec sort=recent. - `created_since`, optionnel, string : Annonces publiées sur le site source depuis cette date (ISO 8601). - `page`, optionnel, integer, bornes : 1 à 1000 : Numéro de page (1..1000). Préférer cursor au-delà de 50. - `page_size`, optionnel, integer, défaut : 25, bornes : 1 à 100 : Taille de page (max 100). - `cursor`, optionnel, string : Curseur opaque de pagination (fourni par next_cursor). ### GET /api/v1/annonces/feed Flux complet (changefeed) sans plafond de profondeur - `type`, optionnel, string : Type de bien (Appartement, Maison, Terrain...). - `ville`, optionnel, string : Une ou plusieurs villes (séparées par des virgules, max 8). - `dept`, optionnel, string : Département. - `page_size`, optionnel, integer, défaut : 25, bornes : 1 à 100 : Taille de page (max 100). - `cursor`, optionnel, string : Curseur opaque de pagination (fourni par next_cursor). - `sources`, optionnel, string : 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. - `exclude_sources`, optionnel, string : 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. ### GET /api/v1/annonces/retirees Annonces retirées du marché par leur site d'origine - `page_size`, optionnel, integer, défaut : 25, bornes : 1 à 100 : Taille de page (max 100). - `cursor`, optionnel, string : Curseur opaque de pagination (fourni par next_cursor). - `sources`, optionnel, string : 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. - `exclude_sources`, optionnel, string : 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. ### GET /api/v1/annonces/map Annonces dans une emprise géographique (bbox) - `bbox`, **requis**, string : Emprise au format south,west,north,east (latitudes/longitudes). - `type`, optionnel, string : Type de bien (Appartement, Maison, Terrain...). - `transaction`, optionnel, string, valeurs : vente | location - `sources`, optionnel, string : 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. - `exclude_sources`, optionnel, string : 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. ### GET /api/v1/annonces/{source}/{reference} Détail d'une annonce - `source`, **requis**, string - `reference`, **requis**, string ### GET /api/v1/ptz/zone Zone PTZ (Abis/A/B1/B2/C) d'une commune - `cp`, **requis**, string : Code postal (5 chiffres). --- Généré le 2026-09-26T22:05:16.168Z.