Waarderings-API

Een reproduceerbare referentiewaarde voor elke woning in de stad Buenos Aires, met betrouwbaarheidsmarge, vergelijkbare woningen en een toelichting in gewone taal. Basis-URL: https://api.zavaluo.com/v1. Elk antwoord is JSON in UTF-8.

Authenticatie

Elk request bevat je sleutel in de header Authorization. We bewaren alleen de hash van de sleutel: ben je hem kwijt, dan geven we een nieuwe uit.

Authorization: Bearer zv_live_9f3c…

Vraag een sleutel aan via API-toegang. Het plan Explore bevat 100 requests per maand; de andere plannen hun eigen quotum.

Eerste request

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

Een waardering aanmaken

Geeft de geschatte waarde van een woning terug. Alleen het adres is genoeg; elk extra kenmerk versmalt de marge.

Body

Antwoord

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

Een waardering ophalen

Geeft een eerdere waardering terug die met jouw sleutel is uitgegeven, zonder herberekening en zonder quotum te verbruiken.

Advertentie-index

Elke actieve advertentie die we volgen (portals en directe eigenaren), gepagineerd, met de canonieke URL op Zavaluo en, bij verkoop, de USD/m² ten opzichte van de referentiewaarde van de barrio (delta_vs_reference, null zolang de barrio kalibreert). De filters zijn dezelfde als die van de zoekfunctie op de 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) beschrijft het blok op basis van de open data van het stadsbestuur: afstand tot de subte (metro), gemelde incidenten binnen 500 m, scholen binnen 800 m, groen en ziekenhuizen. Het is geen waardering; de detailweergave bevat elk onderdeel en het cijfer erachter in context. Het is null als de advertentie het exacte adres niet publiceert.

predicted_usd_m2, value_delta en deal_score komen uit het geldende hedonische model (model_version in het antwoord): de vraagprijsreferentie voor die advertentie gegeven oppervlakte, kamers, bouwjaar, parkeren en omgeving, hoeveel erboven of eronder gevraagd wordt, en een 0–100 waarbij 50 “op het model” is. Een value_delta buiten ±0,45 is bijna altijd een oppervlakte- of prijsfout bij de bron, geen kans. quality_score (0–100) meet hoe volledig het record is; met sort=delta sorteert de index op value_delta waar die bestaat.

Eén advertentie

Het volledige detail per ref (1863 of ZV-1863) of per uuid: beschrijving, samenvatting, oppervlaktes, verdieping, voorzieningen, foto’s, prijsgeschiedenis, de gestructureerde extractie uit de tekst met haar versie, en context (omgeving: scores voor vervoer, veiligheid, scholen, groen en zorg met de afstanden en aantallen erachter). Het bevat nooit de contactgegevens van de adverteerder.

Vergelijkbare woningen

De meest vergelijkbare actieve advertenties rond een punt (500 m, uitgebreid naar 1 km en 2,5 km als er minder dan vijf zijn), elk met haar similarity (afstand, oppervlakte, kamers, badkamers, bouwjaar, leeftijd van de advertentie) en haar adjusted_usd_m2: de prijs van de vergelijkbare woning, gecorrigeerd naar de gevraagde woning met de coëfficiënten van het geldende hedonische model (model_version). De gewogen mediaan van de gecorrigeerde cijfers is de referentie, en de marge is p25–p75. confidence A–D vat aantal, gelijkenis en spreiding samen. Met asking_usd geeft het asking_vs_reference terug. De variant per ref bouwt het onderwerp op uit de advertentie en sluit haar uit van haar eigen vergelijkbare woningen.

Het is een vraagprijsreferentie, geen waardering: reference.basis zegt dat in elk antwoord. De correcties komen uit een log-lineair model dat is gefit op de actieve advertenties in Buenos Aires (oppervlakte, kamers, badkamers, bouwjaar, parkeren, directe eigenaar, afstand tot de subte, veiligheid en groen in de omgeving, type en barrio); drivers bevat in woorden de correcties die het zwaarst wogen.

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

Barrio-index

Per barrio en per dag: actief aanbod, nieuwe en ingetrokken advertenties over 30 dagen, het aandeel met een prijsverlaging, looptijd, USD/m² voor verkoop en voor maandhuur, bruto rendement, gemiddelde omgevingsscore en de onderdelen van de marktscore (momentum, liquidity, rental, entorno, affordability). market_score is null en calibrating true tot er 30 dagen geschiedenis is voor momentum en liquiditeit: we publiceren liever geen score die alleen “goedkoop” zegt.

CABA-marktscore

Maandelijkse context voor de markt van de stad: een score van 0–100 met vijf onderdelen (transactieactiviteit 30%, hypotheekkrediet 25%, financieringsvoorwaarden 15%, macrostabiliteit 15%, staats- en valutarisico 15%), het regime (very_weak … very_strong), de ruwe cijfers achter elk (aktes en hypotheken van het Colegio de Escribanos, de A3500-dollar, TAMAR/BADLAR, de beleidsrente, UVA en de hypotheekportefeuille van de BCRA, de CPI van INDEC, landenrisico), data_quality_score, is_provisional en calculation_version. Elk onderdeel is een percentiel over de eigen geschiedenis sinds 2016.

Het is context, geen input voor waarderingen: geen enkele referentie of marge van vergelijkbare woningen wordt met deze score gecorrigeerd (basis herhaalt dat in elk antwoord). De historische reeks is er om te grafieken en om te lezen in welke markt je verkoopt. Hij wordt dagelijks herberekend en telkens wanneer het Colegio een nieuwe maand publiceert.

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

Marktstatistieken

Aggregaten per barrio, elke nacht herberekend: mediaan en kwartielen van USD/m², actieve advertenties, looptijd, de mediane prijsverlaging en de verhouding vraagprijs/transactieprijs waar transacties zijn gemeld. Zonder neighborhood geeft het elke barrio van de stad terug; het resultaat bevat tot 100 rijen, de meest recente eerst.

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

De 48 barrios van Buenos Aires met slug, naam, comuna en middelpunt, en met include=geometry de officiële polygoon van het stadsbestuur als GeoJSON (WGS84). Dit is openbare informatie: er is geen sleutel voor nodig en het verbruikt geen quotum. Gebruik het voor kaarten en om client-side de barrio van een coördinaat te bepalen.

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

Betrouwbaarheid en marges

low_usd en high_usd zijn het 10e en 90e kwantiel van het model. confidence (0–1) combineert de dichtheid van vergelijkbare woningen binnen de straal, de spreiding van hun prijzen en hoeveel echte gemelde transacties we in het gebied hebben. Waar de betrouwbaarheid laag is, schuift de marge op naar de mediaan van de barrio; we verzinnen geen precisie. Zolang de prijsgeschiedenis kort is, is calibrating true.

Vraagprijs vs. transactieprijs

In Buenos Aires verschillen de gepubliceerde prijs en de prijs in de akte, en het verschil varieert per barrio en per moment in de cyclus. estimate_usd en likely_closing_usd zijn de waarschijnlijke transactieprijs. likely_asking_usd is de vraagprijs die vandaag tot die transactie leidt, en asking_vs_closing_adj het toegepaste verschil. Het verschil wordt gekalibreerd op transacties die eigenaren melden en op openbare aggregaten.

Valuta en wisselkoersen

De markt in Buenos Aires handelt in USD; elke modelwaarde is in USD. estimate_local en local_currency rekenen om tegen de MEP-koers van de dag. We bewaren de reeksen oficial, mep en blue per datum, zodat de omrekening controleerbaar is.

Fouten

Limieten en versies

Het quotum is maandelijks per sleutel, en elk verbruikt request telt, ook die een 400 teruggeven. De API-versie staat in de URL (/v1); breaking changes verschijnen als /v2 met minstens 6 maanden overlap. Het model wordt opnieuw getraind en de model_version verandert zonder het contract te raken; we mailen en posten in het wijzigingslog vóór elke hoofdversie.

Wijzigingslog

2026-09 · /v1 kalibreert voor Buenos Aires. GET /market-stats en GET /barrios (met de officiële geometrie) zijn live; POST /valuations valideert en antwoordt 503 tot het model gekalibreerd is.