API ChercherTrouver — v1
Documentation technique pour consommer le flux d'annonces immobilières via API JSON. Le service est actuellement gratuit.
Prise en main
L'API est protégée par clé. Contactez-nous pour en obtenir une, puis
transmettez-la dans l'en-tête X-Api-Key ou
Authorization: Bearer <clé>.
curl "https://cherchertrouver.immo/api/v1/ping" \
-H "X-Api-Key: imk_xxxxxxxxxxxxxxxxxxxxxxxx"Limites par défaut
Chaque clé est créée avec ces limites par défaut. Si votre projet nécessite un volume plus important, contactez-nous — nous ajustons les plafonds au cas par cas.
| Requêtes par seconde | 1 req/s max |
|---|---|
| Requêtes par minute | 60 req/min max |
| Annonces retournées par jour | 200 annonces / 24 h |
Le quota s'applique sur le nombre d'annonces retournées, pas sur
le nombre de requêtes. Exemple : un appel /annonces?page_size=25
qui retourne 25 annonces consomme 25 du quota journalier.
Chaque réponse inclut les en-têtes X-RateLimit-Limit,
X-RateLimit-Remaining, X-RateLimit-Reset,
X-Quota-Items-Limit et X-Quota-Items-Used
pour vous permettre de vous throttler côté client.
Endpoints
/api/v1/ping
Test de vie. Retourne le nom de votre clé, ses limites et l'heure serveur.
/api/v1/annonces
Recherche paginée des annonces (toutes sources confondues : particuliers, professionnels, agrégation externe).
| Param | Type | Description |
|---|---|---|
q | string | Recherche plein texte (titre + description) |
type | string | Maison, Appartement, Terrain, Parking, … |
transaction | enum | vente | location |
ville | string | Nom de ville (LIKE %…%) |
cp | string | Code postal exact |
dept | string | Département (ex: 75) |
prix_min, prix_max | int | Fourchette de prix en € |
prix_m2_min, prix_m2_max | int | Fourchette prix au m² |
surface_min, surface_max | float | Surface en m² |
pieces_min, chambres_min | int | Nb de pièces/chambres min |
annee_min, annee_max | int | Année de construction |
dpe, ges | list | Classes A-G, séparées par virgule |
source | enum | all (défaut) | interne | scraped |
sort | enum | recent | price_asc | price_desc | surface_desc | pricem2_asc |
page | int | Page (1 à 200) |
page_size | int | Taille de page (1 à 48, défaut 25) |
curl "https://cherchertrouver.immo/api/v1/annonces?ville=Paris&type=Appartement&prix_max=500000&page=1" \
-H "X-Api-Key: imk_xxxxxxxxxxxxxxxxxxxxxxxx"/api/v1/annonces/:source/:reference
Détail complet d'une annonce identifiée par (source, référence). Inclut la liste des images, DPE/GES, géolocalisation, description et URL externe éventuelle.
/api/v1/annonces/map
Annonces géolocalisées dans une bbox. Pour alimenter une carte client. Retourne jusqu'à 5000 points avec lat/lng, prix, couleur calculée.
curl "https://cherchertrouver.immo/api/v1/annonces/map?bbox=48.8,2.3,48.9,2.4&type=Appartement" \
-H "X-Api-Key: imk_xxxxxxxxxxxxxxxxxxxxxxxx"/api/v1/stats
Indicateurs agrégés de marché : prix moyen/min/max au m², répartition par type, top villes, distribution DPE. Filtrable par type/ville/cp/dept.
Erreurs
Toutes les erreurs sont retournées en JSON avec la forme
{ error: "message", code: "ERROR_CODE" }.
| HTTP | Code | Sens |
|---|---|---|
| 400 | BAD_REQUEST | Paramètres invalides |
| 401 | API_KEY_MISSING | Aucune clé fournie |
| 401 | API_KEY_INVALID | Clé inexistante, bloquée ou révoquée |
| 402 | QUOTA_EXCEEDED | Quota journalier d'annonces atteint |
| 403 | IP_BANNED | IP bannie |
| 404 | NOT_FOUND | Ressource introuvable |
| 429 | RATE_LIMIT_PER_SEC | Trop de requêtes par seconde |
| 429 | RATE_LIMIT_PER_MIN | Trop de requêtes par minute |
| 500 | SERVER_ERROR | Erreur interne |
Obtenir une clé
Contactez-nous en décrivant votre projet. Nous vous répondons sous 48 h ouvrées avec votre clé et ses limites.
Demander une clé