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 & 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 :

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 celle de la création de votre compte : l’abonnement porte sur le flux courant, l’historique constitué avant votre arrivée étant proposé en option.

• 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": 200,
  "server_time": "2026-04-18T10:00:00.000Z"
}

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

$ # 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",
      "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_label": 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",
      "latitude": 47.2184,
      "longitude": -1.5536,
      "dpe": "D",
      "ges": "D",
      "dpe_value": 210,
      "ges_value": 42,
      "dpe_chart_url": "https://...",
      "ges_chart_url": null,
      "legal_info": "Copropriété de 24 lots...",
      "images": ["https://..."],
      "images_count": 8,
      "description": "Bel appartement lumineux...",
      "external_url": "https://site-a.example/...",
      "video_url": null,
      "virtual_tour_url": "https://...",
      "published_at": "2026-04-15T08:23:00.000Z",
      "updated_at": "2026-09-05T04:12:00.000Z",
      "seller_contact": null,
      "price_history": {
        "current": 312000,
        "previous": 325000,
        "changed_at": "2026-08-14T03:12:00.000Z",
        "changes": 2,
        "tracked_since": "2026-06-23T02:10:00.000Z",
        "depth": 2
      },
      "is_internal": false,
      "dedup_key": "a1b2c3d4e5f60718",
      "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 }
      ]
    }
  ]
}

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
    }
  ]
}

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.2184,
      "longitude": -1.5536,
      "price": 285000,
      "price_per_m2": 2375,
      "price_per_m2_color": "#16a34a",
      "surface": 120,
      "type": "Maison",
      "title": "Maison 5 pièces 120m²",
      "city": "Nantes",
      "postal_code": "44000",
      "rooms": 5,
      "image": "https://...",
      "is_internal": false
    }
  ]
}

Retourne le détail complet d’une annonce identifiée par sa source et sa référence. Consomme 1 annonce sur le quota journalier.

$ 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"
}