API di valutazione

Un valore di riferimento riproducibile per qualsiasi immobile della città di Buenos Aires, con intervallo di confidenza, comparabili e una spiegazione in linguaggio semplice. URL di base: https://api.zavaluo.com/v1. Ogni risposta è JSON in UTF-8.

Autenticazione

Ogni richiesta porta la tua chiave nell’header Authorization. Conserviamo solo l’hash della chiave: se la perdi, ne emettiamo una nuova.

Authorization: Bearer zv_live_9f3c…

Richiedi una chiave su Accesso all’API. Il piano Explore include 100 richieste al mese; gli altri piani, la propria quota.

Prima richiesta

# 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})

Creare una valutazione

Restituisce il valore stimato di un immobile. Basta l’indirizzo; ogni attributo in più restringe l’intervallo.

Corpo

Risposta

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

Recuperare una valutazione

Restituisce una valutazione emessa in precedenza con la tua chiave, senza ricalcolare e senza consumare quota.

Indice degli annunci

Ogni annuncio attivo che monitoriamo (portali e proprietari diretti), paginato, con il suo URL canonico su Zavaluo e, per le vendite, l’USD/m² rispetto al valore di riferimento del barrio (delta_vs_reference, null finché il barrio è in calibrazione). I filtri sono gli stessi della ricerca del sito.

{ "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) descrive l’isolato a partire dagli open data del governo cittadino: distanza dalla subte (metropolitana), incidenti segnalati entro 500 m, scuole entro 800 m, verde e ospedali. Non è una valutazione; il dettaglio porta ogni componente e il dato che lo sostiene in context. È null quando l’annuncio non pubblica l’indirizzo esatto.

predicted_usd_m2, value_delta e deal_score vengono dal modello edonico in vigore (model_version nella risposta): il riferimento di prezzo richiesto per quell’annuncio dati superficie, locali, età, posto auto e contesto, quanto chiede sopra o sotto, e un punteggio 0–100 in cui 50 è “in linea con il modello”. Un value_delta oltre ±0,45 è quasi sempre un errore di superficie o di prezzo alla fonte, non un’occasione. quality_score (0–100) misura quanto è completo il record; con sort=delta l’indice ordina per value_delta dove esiste.

Un annuncio

Il dettaglio completo per ref (1863 o ZV-1863) o per uuid: descrizione, riassunto, superfici, piano, servizi, foto, storico dei prezzi, l’estrazione strutturata dal testo con la sua versione, e context (contesto: punteggi di trasporti, sicurezza, scuole, verde e sanità con le distanze e i conteggi dietro ciascuno). Non include mai i contatti dell’inserzionista.

Comparabili

Gli annunci attivi più simili intorno a un punto (500 m, allargando a 1 km e 2,5 km se sono meno di cinque), ciascuno con la sua similarity (distanza, superficie, locali, bagni, età, anzianità dell’annuncio) e il suo adjusted_usd_m2: il prezzo del comparabile adeguato all’immobile richiesto con i coefficienti del modello edonico in vigore (model_version). La mediana ponderata dei valori adeguati è il riferimento, e l’intervallo è il p25–p75. confidence A–D riassume numero, somiglianza e dispersione. Con asking_usd restituisce asking_vs_reference. La variante per ref costruisce il soggetto a partire dall’annuncio e lo esclude dai propri comparabili.

È un riferimento di prezzo richiesto, non una valutazione: reference.basis lo dice in ogni risposta. Gli adeguamenti vengono da un modello log-lineare stimato sugli annunci attivi di Buenos Aires (superficie, locali, bagni, età, posto auto, proprietario diretto, distanza dalla subte, sicurezza e verde del contesto, tipo e barrio); drivers riporta a parole gli adeguamenti che hanno pesato di più.

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

Indice dei barrios

Per barrio e per giorno: stock attivo, annunci nuovi e ritirati in 30 giorni, quota con ribasso di prezzo, giorni online, USD/m² in vendita e in affitto mensile, rendimento lordo, punteggio medio del contesto e le componenti del punteggio di mercato (momentum, liquidity, rental, entorno, affordability). market_score è null e calibrating è true finché non ci sono 30 giorni di storico per momentum e liquidità: preferiamo non pubblicare un punteggio che dica solo “economico”.

Punteggio di mercato CABA

Contesto mensile del mercato cittadino: un punteggio 0–100 con cinque componenti (attività transazionale 30%, credito ipotecario 25%, condizioni di finanziamento 15%, stabilità macro 15%, rischio sovrano e valutario 15%), il regime (very_weak … very_strong), le metriche grezze dietro ciascuna (atti e ipoteche del Colegio de Escribanos, dollaro A3500, TAMAR/BADLAR, tasso di policy, UVA e stock ipotecario del BCRA, IPC dell’INDEC, rischio paese), data_quality_score, is_provisional e calculation_version. Ogni componente è un percentile sulla propria storia dal 2016.

È contesto, non un input di valutazione: nessun riferimento né intervallo di comparabili viene adeguato con questo punteggio (basis lo ripete in ogni risposta). La serie storica serve per i grafici e per capire in che mercato stai vendendo. Viene ricalcolata ogni giorno e ogni volta che il Colegio pubblica un nuovo mese.

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

Statistiche di mercato

Aggregati per barrio, ricalcolati ogni notte: mediana e quartili dell’USD/m², annunci attivi, giorni online, ribasso di prezzo mediano e rapporto tra prezzo richiesto e prezzo di chiusura dove sono state segnalate chiusure. Senza neighborhood restituisce tutti i barrios della città; il risultato contiene fino a 100 righe, le più recenti per prime.

{ "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

I 48 barrios di Buenos Aires con slug, nome, comuna e centroide, e con include=geometry il poligono ufficiale del governo cittadino in GeoJSON (WGS84). È un’informazione pubblica: non serve una chiave e non consuma quota. Usala per le mappe e per ricavare lato client il barrio di una coordinata.

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

Confidenza e intervalli

low_usd e high_usd sono il 10° e il 90° quantile del modello. confidence (0–1) combina la densità di comparabili nel raggio, la dispersione dei loro prezzi e quante chiusure reali segnalate abbiamo nella zona. Dove la confidenza è bassa, l’intervallo si allarga verso la mediana del barrio; non inventiamo precisione. Finché lo storico dei prezzi è breve, calibrating è true.

Prezzo richiesto vs. prezzo di chiusura

A Buenos Aires il prezzo pubblicato e quello del rogito differiscono, e il divario varia per barrio e per fase del ciclo. estimate_usd e likely_closing_usd sono il prezzo di chiusura probabile. likely_asking_usd è il prezzo richiesto che oggi porta a quella chiusura, e asking_vs_closing_adj il divario applicato. Il divario è calibrato sulle chiusure segnalate dai proprietari e su aggregati pubblici.

Valute e tassi di cambio

Il mercato di Buenos Aires tratta in USD; ogni valore del modello è in USD. estimate_local e local_currency convertono al cambio MEP del giorno. Conserviamo le serie oficial, mep e blue per data, così la conversione è verificabile.

Errori

Limiti e versioni

La quota è mensile per chiave, e ogni richiesta consumata conta, comprese quelle che restituiscono 400. La versione dell’API è nell’URL (/v1); le modifiche incompatibili escono come /v2 con almeno 6 mesi di sovrapposizione. Il modello viene riaddestrato e la sua model_version cambia senza toccare il contratto; avvisiamo via email e nel registro delle modifiche prima di ogni versione principale.

Registro delle modifiche

2026-09 · /v1 in calibrazione per Buenos Aires. GET /market-stats e GET /barrios (con la geometria ufficiale) sono attivi; POST /valuations valida e risponde 503 finché il modello non è calibrato.