API Estimatiz

Choisir entre API et MCP

L’API HTTP s’adresse aux développeurs de sites, d’applications et d’agents IA capables d’envoyer des requêtes HTTP. Elle renvoie les résultats au format JSON.

MCP (Model Context Protocol) permet à un assistant compatible d’utiliser les outils Estimatiz pendant une conversation. La personne qui configure l’assistant ajoute le serveur MCP ; l’assistant peut ensuite rechercher une adresse et demander une estimation.

Les deux accès donnent les mêmes montants et le lien du même type de rapport. MCP n’est pas nécessaire pour appeler l’API.

Accès et fonctionnement

L’API est conçue pour un accès sans clé, sans compte et sans quota applicatif. Elle ne demande aucun nom, e-mail ou téléphone. Sa disponibilité dépend du serveur et des services de données utilisés.

Tous les exemples ci-dessous appellent le service public https://www.estimatiz.fr. Les commandes cURL sont à copier dans un terminal macOS ou Linux ; elles ne nécessitent aucune installation d’Estimatiz.

Envoyer les demandes d’estimation en JSON avec Content-Type: application/json. La taille maximale d’une requête est de 16 Kio. Cette limite porte sur le contenu d’un appel, pas sur le nombre d’appels.

Un agent peut l’appeler directement en HTTP. Le connecteur MCP est optionnel. La documentation ne garantit pas que les assistants découvrent ou choisissent automatiquement Estimatiz.

Schéma OpenAPIConsulter la méthode EstimatizConsulter les sources

De l’adresse au rapport

1. Rechercher l’adresse et faire confirmer le bon résultat.
2. Envoyer cette adresse numérotée, le type de bien et la surface ; ajouter les pièces si elles sont connues.
3. Présenter le prix médian, la fourchette, les limites du résultat et le lien vers le rapport enregistré.

Le rapport et la réponse API utilisent la même sélection de ventes et les mêmes calculs. Le rapport donne accès aux informations complémentaires disponibles, dont les ventes comparables et la carte.

Le rapport est non indexable et accessible à toute personne possédant son lien. Informer l’utilisateur de cet enregistrement avant l’appel d’estimation. Ne pas transmettre de coordonnées de contact.

Rechercher une adresse

Paramètre requis : q, texte de 3 à 200 caractères contenant l’adresse recherchée. Aucun résultat correspond à un tableau addresses vide.

Ouvrir cet exemple de recherche dans le navigateur

curl --get 'https://www.estimatiz.fr/api/public/v1/addresses.php' \
  --data-urlencode 'q=146 boulevard Voltaire 75011 Paris'

La réponse contient ok et addresses. Chaque adresse fournit label, code_voie, voie, commune, cp, no_voie et btq. Conserver l’objet retourné après confirmation de l’utilisateur. Ne pas choisir arbitrairement le premier résultat ni inventer un identifiant.

Créer une estimation

Cette adresse attend une requête POST avec un corps JSON. L’ouvrir dans la barre d’adresse du navigateur envoie un GET et ne crée pas d’estimation.

Le corps JSON contient address (l’objet confirmé), property_type et surface. Les paramètres rooms, rooms_mode et location_fallback sont facultatifs.

property_type

Une catégorie : Appartement, Maison, Local ou Autres biens.

surface

Nombre de 5 à 500 m².

rooms et rooms_mode

Nombre entier de 1 à 30 pièces, si connu. Mode exact par défaut ou minimum avec un nombre de pièces fourni.

location_fallback

nearby_number par défaut : autorise un repère voisin si les règles de confirmation sont satisfaites. none désactive le recours à un numéro voisin.

Aucun prix, coordonnée géographique ni comparable calculé par le client n’est accepté comme base du calcul.

Exemple complet avec cURL

Cette commande estime un appartement de 60 m² au 146 boulevard Voltaire à Paris et enregistre un rapport partageable. Pour un autre bien, reprendre l’adresse confirmée par la recherche et modifier ses caractéristiques.

curl 'https://www.estimatiz.fr/api/public/v1/estimate.php' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "address": {
    "label": "146 BD VOLTAIRE 75011 Paris 11e Arrondissement",
    "code_voie": "9907",
    "voie": "BD VOLTAIRE",
    "commune": "Paris 11e Arrondissement",
    "cp": "75011",
    "no_voie": "146",
    "btq": ""
  },
  "property_type": "Appartement",
  "surface": 60
}'

Montants et rapport

estimation.median, low, high

Montant médian et fourchette basse et haute en euros. price_m2 indique le prix au m² médian.

report.url

Lien partageable du rapport enregistré. Afficher ce lien avec les montants ; ne pas le reconstruire.

comparables, location, warnings

Nombre et dates des ventes, état de localisation et avertissements. Une localisation approximative doit rester explicite.

sources, methodology_url, generated_at

Sources utilisées, méthode et date de génération du résultat.

Exemple complet en JavaScript

Ce code contient la demande et appelle directement l’API publique. Il peut être exécuté dans une application JavaScript disposant de fetch, ou dans un fichier avec Node.js 18 ou ultérieur. Depuis un site web, sa politique de sécurité doit autoriser les connexions à https://www.estimatiz.fr. Son exécution crée également un rapport.

async function estimerAvecEstimatiz() {
  const demande = {
  "address": {
    "label": "146 BD VOLTAIRE 75011 Paris 11e Arrondissement",
    "code_voie": "9907",
    "voie": "BD VOLTAIRE",
    "commune": "Paris 11e Arrondissement",
    "cp": "75011",
    "no_voie": "146",
    "btq": ""
  },
  "property_type": "Appartement",
  "surface": 60
};
  const reponse = await fetch('https://www.estimatiz.fr/api/public/v1/estimate.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(demande)
  });
  const resultat = await reponse.json();
  if (!reponse.ok || !resultat.ok) {
    throw new Error(resultat.error?.message || 'Estimation indisponible');
  }
  console.log(resultat.estimation);
  console.log(resultat.report.url);
  return resultat;
}
estimerAvecEstimatiz().catch(console.error);

L’estimation n’est pas un prix de vente garanti. En cas de données insuffisantes, expliquer la limite sans inventer de montant. Un résultat peut être réutilisé ; consulter sa date de génération.

Traiter les erreurs

{"ok": false, "error": {"code": "INVALID_PARAMETERS", "message": "Paramètres invalides."}}

REPORT_CREATION_FAILED signifie que l’enregistrement du rapport a échoué : ne pas annoncer un succès complet et ne pas inventer de lien. Le contrat OpenAPI décrit les réponses attendues.

Connecter un assistant avec MCP

Dans un client prenant en charge les serveurs MCP distants, ajouter un serveur avec le transport Streamable HTTP et sans authentification. L’adresse du serveur est https://www.estimatiz.fr/api/mcp.php.

Copiez cette URL complète dans le champ « URL du serveur » de votre client MCP :

https://www.estimatiz.fr/api/mcp.php

Le client MCP gère les appels POST et l’initialisation du protocole. Ouvrir cette URL dans la barre d’adresse du navigateur ne lance pas d’estimation.

1. Connecter le client au serveur et vérifier qu’il propose les outils search_addresses et estimate_property.
2. Demander la recherche d’une adresse, puis confirmer le résultat et les caractéristiques du bien.
3. Demander l’estimation et afficher les montants, les avertissements et le lien du rapport dans la réponse.

Le client gère l’initialisation MCP. Pour une intégration technique, envoyer Content-Type: application/json et Accept: application/json, text/event-stream. Les révisions prises en charge sont 2025-03-26, 2025-06-18 et 2025-11-25.

Le point d’accès https://www.estimatiz.fr/api/mcp.php expose les outils search_addresses et estimate_property. Ils utilisent le même service que l’API. L’estimation enregistre un rapport ; cet outil a donc un effet d’écriture.

Estimatiz est un service indépendant, sans affiliation avec une administration. Les attributions et les limites des données restent disponibles dans le rapport et dans les sources renvoyées.