Documentation API v1

Authentification

Toutes les requêtes doivent inclure votre clé API. Deux méthodes acceptées :

X-Api-Key: imk_votre_cle

Authorization: Bearer imk_votre_cle

Limites et quotas

Chaque réponse acceptée inclut ces en-têtes pour surveiller votre consommation. Une réponse 429 porte Retry-After et X-Annonces-From, mais pas les compteurs de quota :

• /annonces : chaque annonce de la page ; les autres publications du même bien, dans sources, sont comprises.
• /annonces/feed : chaque publication, puisque le flux livre à part chaque site d’un même bien.
• /annonces/doublons : une annonce par groupe, sa principale.
• /annonces/map : chaque point.
• /annonces/:source/:reference : l’annonce.
• /annonces/retirees et les calculs des outils : aucune annonce.

Périmètre du catalogue

Deux règles distinguent ce que renvoie l’API de ce qu’affiche la page publique. Elles jouent en sens inverse : la première réduit le périmètre, la seconde l’élargit.

1. Date de début d’accès

Une clé ne restitue que les annonces entrées dans notre catalogue à partir d’une date donnée, renvoyée dans l’en-tête X-Annonces-From de chaque réponse. Par défaut, cette date est fixée 30 jours avant la création de votre compte : vous essayez l’API dès l’inscription, sur un mois d’annonces. L’abonnement porte ensuite sur le flux courant.

Ce mois est l’historique maximal offert, essai compris. Un historique plus ancien est une option payante, à prévoir à la commande (CGV, article 4).

• Elle dépend du compte, pas de la clé : en révoquer une et en créer une autre ne déplace pas cette date.
• Elle porte sur la date d’entrée dans notre base, et non sur la date de publication sur le site d’origine ni sur updated_at. Le paramètre updated_since ne permet donc pas de remonter au-delà.
• Elle s’applique à toutes les offres, gratuite comme payantes.

2. Aucun filtre de fraîcheur

La page publique n’affiche que les annonces revues dans les deux dernières semaines. L’API lève cette contrainte : elle vous sert aussi les annonces que nous n’avons pas revues depuis, sur la période à laquelle vous avez accès. C’est délibéré : une veille incrémentale a besoin de revoir une annonce même quand elle cesse d’être rafraîchie.

En revanche, une annonce explicitement passée à vendue, sous compromis ou archivée sort du flux, sur l’API comme sur le site. Une annonce qui disparaît de vos résultats est donc soit vendue, soit hors de votre période d’accès : ne déduisez pas de sa présence qu’un bien est toujours disponible, ni de son absence qu’il a été vendu.

Pour vous rapprocher de ce qu’affiche le site, filtrez avec updated_since : il porte sur la date de notre dernier passage de collecte, exposée dans le champ updated_at. Une annonce que nous n’avons pas revue depuis deux semaines a de fortes chances de ne plus être en ligne.

Format des erreurs

Toutes les erreurs retournent un JSON avec error (message lisible) et code (identifiant machine) :

{
  "error": "Limite de requêtes dépassée (60 req/min max)",
  "code": "RATE_LIMIT_PER_MIN",
  "retry_after_seconds": 42
}

Health check, vérifie que votre clé est valide et retourne les limites configurées pour votre offre. Utile pour tester l’authentification sans consommer de quota.

{
  "ok": true,
  "api_key_name": "Clé personnelle",
  "tier": "free",
  "rate_limit_per_sec": 1,
  "rate_limit_per_min": 60,
  "items_per_day": 50,
  "annonces_from": "2026-03-19T00:00:00.000Z",
  "quota_mois": {
    "palier": "Découverte",
    "limit": 50,
    "used": 12,
    "remaining": 38,
    "reset": null
  },
  "server_time": "2026-04-18T10:00:00.000Z"
}

quota_mois est le volume de votre offre, celui qui refuse les appels quand il est atteint : mêmes valeurs que les en-têtes X-Quota-Mois-*. reset vaut null sur l’offre gratuite, dont la période glisse sur trente jours. quota_mois vaut null si votre compte n’a pas de quota mensuel. annonces_from est la date à partir de laquelle votre clé reçoit les annonces, la même que l’en-tête X-Annonces-From (Périmètre du catalogue).

Recherche d’annonces, rendue par pages. Tous les filtres sont optionnels. Les partenaires API accèdent au catalogue complet, sans filtre de récence.

Recherche interrompue. Une recherche très large (aucun lieu, filtre rare sur toute la France) peut dépasser le délai accordé à une requête. La réponse porte alors "degraded": true et un "message" : la page vide ne veut pas dire qu’aucune annonce ne correspond. Relancez, ou précisez un lieu (ville, cp, dept).

$ # Première page
$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/annonces?updated_since=2026-06-09&sort=recent&page_size=50"
# → réponse contient "next_cursor": "eyJ1IjoiMjAyNi0wNi0...="

$ # Page suivante : passer next_cursor reçu
$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/annonces?cursor=eyJ1IjoiMjAyNi0wNi0...="

$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/annonces?ville=Nantes&type=Appartement&prix_max=350000&page_size=5"

{
  "page": 1,
  "page_size": 5,
  "has_more": true,
  "next_cursor": "eyJ1IjoiMjAyNi0wNi0wOVQwMjozMjowMC4wMDBaIiwiciI6ImFiYzEyMyIsInMiOiJzZWxvZ2VyIn0",
  "items": [
    {
      "source": "site_a",
      "reference": "abc123",
      "link": "https://cherchertrouver.immo/annonces/appartement-nantes-44000/...",
      "title": "Appartement 3 pièces 68m² Nantes Centre",
      "type": "Appartement",
      "transaction_type": "vente",
      "price": 312000,
      "price_per_m2": 4588,
      "price_per_m2_color": "#f59e0b",
      "price_to_verify": null,
      "price_label": null,
      "nature": null,
      "viager": null,
      "surface": 68,
      "land_surface": null,
      "living_room_surface": 28,
      "rooms": 3,
      "bedrooms": 2,
      "bathrooms": 1,
      "shower_rooms": 1,
      "toilets": 1,
      "kitchen": "équipée",
      "year_built": 1975,
      "elevator": true,
      "parking": false,
      "parking_interior": null,
      "parking_exterior": null,
      "cellar": true,
      "garden": false,
      "seller_type": "Pro",
      "seller_name": "Agence Centre Immo",
      "real_estate_network": "Réseau Exemple",
      "exclusive": true,
      "city": "Nantes",
      "postal_code": "44000",
      "department": "44",
      "region": "Pays de la Loire",
      "street": "Rue Crébillon",
      "latitude": 47.213,
      "longitude": -1.561,
      "position_precision": "adresse",
      "position_source": "annonce",
      "position_coherente": true,
      "insee_code": "44109",
      "dpe": "D",
      "ges": "D",
      "dpe_value": 210,
      "ges_value": 42,
      "dpe_chart_url": null,
      "ges_chart_url": null,
      "energy_to_verify": null,
      "legal_info": "Copropriété : 24 lot(s) Charges prévisionnelles : 1 320 € / an...",
      "copropriete": {
        "lots": 24,
        "annual_charges": 1320,
        "monthly_charges": 110,
        "charges_written_per": "year",
        "procedure": "none",
        "read_from": { "lots": "legal_info", "charges": "legal_info", "procedure": "legal_info" }
      },
      "images": ["https://site-a.example/photos/1.jpg", "https://site-a.example/photos/2.jpg", "..."],
      "images_count": 8,
      "description": "Bel appartement lumineux...",
      "description_truncated": false,
      "external_url": "https://site-a.example/...",
      "video_url": null,
      "virtual_tour_url": "https://...",
      "published_at": "2026-04-15T10:23:00+02:00",
      "updated_at": "2026-09-05T06:12:00+02:00",
      "seller_contact": null,
      "price_history": {
        "current": 312000,
        "previous": 325000,
        "changed_at": "2026-08-14T05:12:00+02:00",
        "changes": 2,
        "tracked_since": "2026-06-23T04:10:00+02:00",
        "depth": 2
      },
      "is_internal": false,
      "dedup_key": "a1b2c3d4e5f60718",
      "dedup_version": 3,
      "sources": [
        { "source": "site_a", "reference": "123456", "url": "https://site-a.example/...", "price": 415000, "is_main": true },
        { "source": "site_b", "reference": "789012", "url": "https://site-b.example/...", "price": 418000, "is_main": false }
      ],
      "sites_count": 2
    }
  ]
}

Flux complet du catalogue. Conçu pour un seul besoin : récupérer toutes les annonces qui entrent en base, puis rester à jour en continu, sans jamais en manquer ni gérer de pages. Une seule boucle : on rappelle avec le next_cursor reçu, indéfiniment.

$ # Premier appel (sans cursor)
$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/annonces/feed?page_size=100"
# → réponse : "next_cursor": "eyJ1IjoiMjAyNi0wNy0wMS...="

$ # Appels suivants : réinjecter next_cursor. Page vide = à jour → re-poller plus tard.
$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/annonces/feed?cursor=eyJ1IjoiMjAyNi0wNy0wMS...="

{
  "count": 100,
  "has_more": true,
  "next_cursor": "eyJ1IjoiMjAyNi0wNy0wMVQxMDowMDowMFoiLCJyIjoiYWJjMTIzIiwicyI6ImxlYm9uY29pbiJ9",
  "items": [
    {
      "source": "site_b",
      "reference": "abc123",
      "title": "Studio 30m² Paris 15e",
      "price": 385000,
      "surface": 30,
      "city": "Paris",
      "postal_code": "75015",
      // ... mêmes champs que /annonces
    }
  ]
}

Les groupes de doublons qui ont changé depuis une date. Quand un site publie un bien que nous connaissons déjà, sa publication rejoint le groupe (même dedup_key). Mais les publications déjà reçues ne vous sont pas renvoyées : leur updated_at est leur date de collecte, et le regroupement ne la change pas. Ce point d’accès vous donne, pour chaque groupe modifié, la liste actuelle de ses publications.

$ curl -H "X-Api-Key: ..." "https://cherchertrouver.immo/api/v1/annonces/doublons?changed_since=2026-10-01"
{
  "items": [
    {
      "dedup_key": "a1b2c3d4e5f60718",
      "dedup_version": 3,
      "changed_at": "2026-10-01T15:40:12+02:00",
      "sources": [
        { "source": "site_a", "reference": "123", "url": "https://…", "price": 290000, "surface": 156, "land_surface": 80, "is_main": true },
        { "source": "site_b", "reference": "456", "url": "https://…", "price": 290000, "surface": 156, "land_surface": 171, "is_main": false }
      ]
    }
  ],
  "count": 1,
  "has_more": false,
  "history_since": "2026-10-07T18:05:12+02:00",
  "complete": true,
  "dedup_version_current": 3,
  "next_cursor": "MjAyNi0xMC0wMVQx…"
}

• sources vide : le groupe n’existe plus (ses publications ont été séparées) ; retirez la clé de vos fiches. Sa dedup_key reste présente (c’est elle qu’il faut retirer) et sa dedup_version vaut null : il n’y a plus rien à vérifier. Sur /annonces, une annonce sans groupe porte au contraire dedup_key: null et sources: null.
• history_since : la plus ancienne modification gardée. Le journal existe depuis octobre 2026 et garde 30 jours. complete: false (avec un message) : votre date de départ remonte plus loin, et les modifications antérieures n’y figurent pas ; pour un état complet, relisez dedup_key et sources sur /annonces.
• dedup_version_current : la version de clé en vigueur (3 depuis le 06/10/2026). La dedup_version d’un groupe vaut ce nombre quand le calcul actuel retombe sur sa clé. Elle se vérifie à la lecture : son changement seul n’est pas une modification du groupe. Un groupe recalculé sous une autre clé apparaît deux fois : l’ancienne clé (vide ou réduite) et la nouvelle.
• Une clé peut revenir plusieurs fois au fil des jours : la dernière réponse fait foi.
• Quota : comme sur /annonces, une annonce par groupe, sa principale (is_main), si votre clé ne l’a jamais reçue ; les autres publications du groupe sont comprises, comme sources sur une liste. Une principale déjà reçue ne coûte rien, et un groupe qui n’existe plus non plus. Depuis le 13/10/2026 ; avant, chaque publication jamais reçue comptait.
• Le journal est écrit au fil de chaque passage du regroupement, plusieurs fois par heure, groupe par groupe.

Retourne les points géographiques d’une zone définie par son rectangle englobant. Format léger, taillé pour alimenter une carte Leaflet ou Mapbox. Accepte les mêmes filtres que /annonces.

$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/annonces/map?bbox=47.15,-1.65,47.30,-1.45&type=Maison"

{
  "bbox": { "south": 47.15, "west": -1.65, "north": 47.30, "east": -1.45 },
  "total": 142,
  "capped": false,
  "items": [
    {
      "source": "site_b",
      "reference": "xyz789",
      "latitude": 47.218,
      "longitude": -1.554,
      "position_precision": "adresse",
      "price": 285000,
      "price_per_m2": 2375,
      "price_per_m2_color": "#16a34a",
      "price_to_verify": null,
      "surface": 120,
      "type": "Maison",
      "title": "Maison 5 pièces 120m²",
      "city": "Nantes",
      "postal_code": "44000",
      "rooms": 5,
      "image": null,
      "link": "https://cherchertrouver.immo/annonces/maison-nantes-44000/…",
      "is_internal": false
    }
  ]
}

Retourne le détail complet d’une annonce identifiée par sa source et sa référence. Compte 1 annonce dans vos quotas (le jour et la période) si votre clé ne l’a jamais reçue ; une fiche déjà reçue, par cette route ou par une liste, ne coûte rien, et une fiche introuvable (404) non plus.

$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/annonces/site_a/abc123"

{
  "annonce": {
    "source": "site_a",
    "reference": "abc123",
    // ... tous les champs (même structure que /annonces)
  }
}

Lookup officiel d’une commune française vers sa zone du prêt à taux zéro (PTZ) (A bis / A / B1 / B2 / C) selon l’arrêté du 5 septembre 2025 du Ministère du Logement. Zonage utilisé par tous les dispositifs aidés : Prêt à Taux Zéro, Pinel, Logement Locatif Intermédiaire, Bail Réel Solidaire, PSLA. Coût : 1 token par lookup réussi (200). Les erreurs (400/404) ne consomment pas.

$ curl -H "X-Api-Key: imk_xxx" \
  "https://cherchertrouver.immo/api/v1/ptz/zone?cp=75011"

{
  "zone": "Abis",
  "codePostal": "75011",
  "source": "Arrêté du 5 septembre 2025, Ministère du Logement"
}

{
  "error": "Code postal inconnu"
}

Le même catalogue et les mêmes outils, présentés à un assistant (Claude, ChatGPT, Cursor, VS Code…) par le protocole MCP. Ouvert à tous les comptes : présentation.

POST https://cherchertrouver.immo/api/v1/mcp
Authorization: Bearer VOTRE_CLE_API
Content-Type: application/json
Accept: application/json, text/event-stream

• Tout ce que l’API sert en lecture, avec les mêmes droits : annonces (recherche, fiche, carte, flux, retraits), zone PTZ, état de l’accès, les outils de calcul (compris selon l’offre, comme /tools) et la veille des SCI (sur option). La liste tools/list ne montre que ce que la clé peut utiliser.
• Transport HTTP du protocole, sans session : chaque requête porte un seul message JSON-RPC (les lots sont refusés) et reçoit une réponse JSON.
• Même clé et même en-tête que le reste de l’API (Authorization: Bearer ou X-Api-Key). Un compte sans accès reçoit 404.
• Ou une connexion au compte (OAuth 2.1, pour ChatGPT et l’application Claude, qui n’envoient pas de clé) : sans authentification, la réponse est un 401 dont l’en-tête WWW-Authenticate désigne /.well-known/oauth-protected-resource/api/v1/mcp. Enregistrement dynamique du client, code d’autorisation avec PKCE (S256), jeton d’accès d’une heure, renouvellement avec rotation. Le jeton ne vaut que pour cette adresse et applique la clé du compte (mêmes quotas, mêmes droits). La personne coupe la connexion dans Mon compte › API et webhooks.
• Les annonces renvoyées comptent dans le quota de votre offre, comme par /annonces ; les calculs n’en consomment pas.
• Débit : 10 requêtes par seconde et 60 par minute, 600 par jour et par clé (ou ceux de votre offre s’ils sont plus élevés) ; appels d’outils par jour et par compte selon l’offre (30 avec l’offre gratuite, 300 avec Secteur (12 € par mois), 1 000 avec Ville (30 € par mois), 2 000 avec Département (70,80 € par mois), 5 000 à partir de Région) ; 10 annonces au plus par recherche.
• Un GET sur cette adresse répond 405, comme le prévoit le protocole pour un serveur qui n’ouvre pas de flux : ce n’est pas une erreur, et il n’est pas compté.