API d’estimation

Une valeur de référence reproductible pour tout bien de la ville de Buenos Aires, avec intervalle de confiance, comparables et une explication en langage clair. URL de base : https://api.zavaluo.com/v1. Chaque réponse est du JSON en UTF-8.

Authentification

Chaque requête porte votre clé dans l’en-tête Authorization. Nous ne conservons que le hash de la clé : si vous la perdez, nous en émettons une nouvelle.

Authorization: Bearer zv_live_9f3c…

Demandez une clé sur Accès à l’API. Le plan Explore inclut 100 requêtes par mois ; les autres plans, leur propre quota.

Première requête

# curl
curl -X POST https://api.zavaluo.com/v1/valuations \
  -H "Authorization: Bearer $ZAVALUO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"Gorriti 4800, Palermo, CABA","kind":"apartment","m2_total":68,"rooms":3,"floor":2}'

// JavaScript (fetch)
const r = await fetch("https://api.zavaluo.com/v1/valuations", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ZAVALUO_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ address: "Gorriti 4800, Palermo, CABA", kind: "apartment", m2_total: 68, rooms: 3, floor: 2 })
});
const v = await r.json();

# Python (requests)
r = requests.post("https://api.zavaluo.com/v1/valuations",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"address": "Gorriti 4800, Palermo, CABA", "kind": "apartment", "m2_total": 68, "rooms": 3, "floor": 2})

Créer une estimation

Renvoie la valeur estimée d’un bien. L’adresse seule suffit ; chaque attribut supplémentaire resserre l’intervalle.

Corps

Réponse

{
  "id": "7a1e…", "model_version": "ar-caba-sale-2026.09.1", "operation": "sale",
  "estimate_usd": 231000, "low_usd": 212000, "high_usd": 248000,
  "estimate_local": 312000000, "local_currency": "ARS",
  "likely_asking_usd": 244000, "likely_closing_usd": 231000, "asking_vs_closing_adj": -0.053,
  "confidence": 0.86, "comps_count": 23, "comps_radius_m": 500,
  "comps": [ { "listing_id": "…", "distance_m": 120, "price_usd": 239000, "usd_m2": 3414, "m2_total": 70,
             "rooms": 3, "days_on_market": 46, "price_cut_pct": -4.0, "source_url": "https://…" }, … ],
  "calibrating": true,
  "explanation": "Valuado 2% por debajo de la mediana de Palermo por estar en 2º piso al contrafrente…",
  "created_at": "2026-09-12T15:04:11-03:00"
}

Récupérer une estimation

Renvoie une estimation émise précédemment avec votre clé, sans recalcul et sans consommer de quota.

Index des annonces

Chaque annonce active que nous suivons (portails et propriétaires directs), paginée, avec son URL canonique sur Zavaluo et, pour les ventes, l’USD/m² par rapport à la valeur de référence du barrio (delta_vs_reference, null tant que le barrio est en calibrage). Les filtres sont ceux de la recherche du site.

{ "total": 224, "page": 1, "page_size": 50, "next": "https://api.zavaluo.com/v1/listings?…&page=2", "reference_as_of": "2026-09-18",
  "items": [ { "ref": 1863, "url": "https://www.zavaluo.com/propiedad/belgrano/ZV-1863-ph-3-ambientes-…",
             "title": "PH 3 ambientes con patio y terraza", "price_usd": 200000, "m2_total": 192, "usd_m2": 1042,
             "neighborhood": "Belgrano", "lat": -34.5612, "lng": -58.4587, "rooms": 3,
             "reference_usd_m2": 2815, "delta_vs_reference": -0.63, "entorno_score": 76, "days_on_market": 0, "cover_url": "https://…/01.jpg" }, … ] }

entorno_score (0–100) décrit le pâté de maisons à partir des données ouvertes de la ville : distance au subte (métro), incidents signalés dans un rayon de 500 m, écoles à moins de 800 m, espaces verts et hôpitaux. Ce n’est pas une estimation ; le détail porte chaque composante et le chiffre derrière dans context. Il est null quand l’annonce ne publie pas l’adresse exacte.

predicted_usd_m2, value_delta et deal_score viennent du modèle hédonique en vigueur (model_version dans la réponse) : la référence de prix demandé pour cette annonce compte tenu de sa surface, de ses pièces, de son âge, du stationnement et de l’environnement, l’écart au-dessus ou en dessous du prix demandé, et une note de 0 à 100 où 50 est « conforme au modèle ». Un value_delta au-delà de ±0,45 est presque toujours une erreur de surface ou de prix à la source, pas une opportunité. quality_score (0–100) mesure la complétude de la fiche ; avec sort=delta, l’index trie par value_delta quand il existe.

Une annonce

Le détail complet par ref (1863 ou ZV-1863) ou par uuid : description, résumé, surfaces, étage, équipements, photos, historique des prix, l’extraction structurée du texte avec sa version, et context (environnement : notes de transport, sécurité, écoles, espaces verts et santé avec les distances et comptages derrière chacune). Il n’inclut jamais les coordonnées de l’annonceur.

Comparables

Les annonces actives les plus similaires autour d’un point (500 m, élargi à 1 km puis 2,5 km s’il y en a moins de cinq), chacune avec sa similarity (distance, surface, pièces, salles de bains, âge, ancienneté de l’annonce) et son adjusted_usd_m2 : le prix du comparable ajusté au bien demandé avec les coefficients du modèle hédonique en vigueur (model_version). La médiane pondérée des chiffres ajustés est la référence, et l’intervalle est le p25–p75. confidence A–D résume nombre, similarité et dispersion. Avec asking_usd, elle renvoie asking_vs_reference. La variante par ref construit le sujet à partir de l’annonce et l’exclut de ses propres comparables.

C’est une référence de prix demandé, pas une estimation : reference.basis le rappelle dans chaque réponse. Les ajustements viennent d’un modèle log-linéaire ajusté sur les annonces actives de Buenos Aires (surface, pièces, salles de bains, âge, stationnement, propriétaire direct, distance au subte, sécurité et espaces verts de l’environnement, type et barrio) ; drivers porte, en mots, les ajustements qui ont le plus pesé.

{ "reference": { "usd_m2": 3180, "low_usd_m2": 2910, "high_usd_m2": 3460, "total_usd": 222600,
                 "confidence": "B", "n_comps": 9, "radius_used_m": 500, "model_usd_m2": 3097, "barrio_median_usd_m2": 3136,
                 "basis": "asking prices of active listings" },
  "comps": [ { "ref": 660, "distance_m": 140, "usd_m2": 2311, "adjusted_usd_m2": 2402, "similarity": 81, "adjustments": { "log_m2": 0.031, "has_parking": 0.145 } }, … ],
  "drivers": [ { "factor": "has_parking", "impact": 0.145, "label": "cochera" } ], "model_version": "hedonic-caba-2026-09-18" }

Index des barrios

Par barrio et par jour : stock actif, annonces nouvelles et retirées sur 30 jours, part avec baisse de prix, délai en ligne, USD/m² à la vente et en location mensuelle, rendement brut, note moyenne d’environnement et composantes de la note de marché (momentum, liquidity, rental, entorno, affordability). market_score est null et calibrating vaut true tant qu’il n’y a pas 30 jours d’historique pour le momentum et la liquidité : nous préférons ne pas publier une note qui dirait seulement « pas cher ».

Note de marché CABA

Contexte mensuel du marché de la ville : une note de 0 à 100 à cinq composantes (activité transactionnelle 30 %, crédit hypothécaire 25 %, conditions de financement 15 %, stabilité macro 15 %, risque souverain et de change 15 %), le régime (very_weak … very_strong), les métriques brutes derrière chacune (actes et hypothèques du Colegio de Escribanos, dollar A3500, TAMAR/BADLAR, taux directeur, UVA et encours hypothécaire de la BCRA, IPC de l’INDEC, risque pays), data_quality_score, is_provisional et calculation_version. Chaque composante est un percentile sur son propre historique depuis 2016.

C’est du contexte, pas une donnée d’estimation : aucune référence ni aucun intervalle de comparables n’est ajusté avec cette note (basis le répète dans chaque réponse). La série historique sert à tracer des graphiques et à lire dans quel marché vous vendez. Elle est recalculée chaque jour et chaque fois que le Colegio publie un nouveau mois.

{ "period": "2026-07", "caba_market_score": 58.4, "regime": "neutral", "score_change_3m": 3.1,
  "components": { "transaction": 61.2, "credit": 71.0, "financing": 44.5, "macro": 66.3, "risk": 40.9 },
  "metrics": { "total_deeds": 6051, "mortgage_share": 0.158, "deeds_yoy_pct": -9.0, "cpi_mom_pct": 2.1, "country_risk": 690, … },
  "data_quality_score": 100, "is_provisional": false, "calculation_version": "caba-market-score-v1" }

Statistiques de marché

Agrégats par barrio, recalculés chaque nuit : médiane et quartiles de l’USD/m², annonces actives, délai en ligne, baisse de prix médiane et ratio prix demandé/prix conclu là où des transactions ont été signalées. Sans neighborhood, renvoie tous les barrios de la ville ; le résultat compte jusqu’à 100 lignes, les plus récentes en premier.

{ "stats": [ { "country": "AR", "city": "CABA", "neighborhood": "Palermo", "kind": "apartment", "operation": "sale",
             "as_of": "2026-09-11", "n_active": 4812,
             "p25_usd_m2": 2980, "median_usd_m2": 3410, "p75_usd_m2": 3890,
             "median_days_on_market": 58, "median_price_cut_pct": -4.1, "asking_to_closed_ratio": null } ] }

Barrios

Les 48 barrios de Buenos Aires avec slug, nom, comuna et centroïde, et avec include=geometry le polygone officiel de la ville en GeoJSON (WGS84). C’est une information publique : aucune clé n’est nécessaire et aucun quota n’est consommé. Utilisez-la pour les cartes et pour déterminer côté client le barrio d’une coordonnée.

{ "barrios": [ { "slug": "palermo", "name": "Palermo", "comuna": 14, "centroid": { "lng": -58.4245, "lat": -34.5788 } }, … ] }

Confiance et intervalles

low_usd et high_usd sont les quantiles 10 et 90 du modèle. confidence (0–1) combine la densité de comparables dans le rayon, la dispersion de leurs prix et le nombre de transactions réelles signalées dans le secteur. Là où la confiance est faible, l’intervalle s’élargit vers la médiane du barrio ; nous n’inventons pas de précision. Tant que l’historique des prix est court, calibrating vaut true.

Prix demandé vs. prix conclu

À Buenos Aires, le prix publié et le prix de l’acte diffèrent, et l’écart varie selon le barrio et le moment du cycle. estimate_usd et likely_closing_usd sont le prix conclu probable. likely_asking_usd est le prix demandé qui mène aujourd’hui à ce prix conclu, et asking_vs_closing_adj l’écart appliqué. L’écart est calibré sur les transactions signalées par les propriétaires et sur des agrégats publics.

Devises et taux de change

Le marché de Buenos Aires se traite en USD ; toutes les valeurs du modèle sont en USD. estimate_local et local_currency convertissent au taux MEP du jour. Nous conservons les séries oficial, mep et blue par date, pour que la conversion soit auditable.

Erreurs

Limites et versions

Le quota est mensuel par clé, et chaque requête consommée compte, y compris celles qui renvoient 400. La version de l’API figure dans l’URL (/v1) ; les changements incompatibles sortent en /v2 avec au moins 6 mois de chevauchement. Le modèle est réentraîné et sa model_version change sans affecter le contrat ; nous prévenons par e-mail et dans le journal des modifications avant chaque version majeure.

Journal des modifications

2026-09 · /v1 en calibrage pour Buenos Aires. GET /market-stats et GET /barrios (avec la géométrie officielle) sont en service ; POST /valuations valide et répond 503 tant que le modèle n’est pas calibré.