API de avaliação

Um valor de referência reprodutível para qualquer imóvel da Cidade de Buenos Aires, com faixa de confiança, comparáveis e uma explicação em linguagem clara. Base URL: https://api.zavaluo.com/v1. Todas as respostas são JSON em UTF-8.

Autenticação

Cada request leva a sua chave no header Authorization. Guardamos apenas o hash da chave: se você perder, emitimos uma nova.

Authorization: Bearer zv_live_9f3c…

Peça uma chave em Acesso à API. O plano Explorar inclui 100 requests por mês; os outros planos, a cota correspondente.

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

Criar uma avaliação

Devolve o valor estimado para um imóvel. Só o endereço já basta; cada atributo adicional estreita a faixa.

Body

Resposta

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

Recuperar uma avaliação

Devolve uma avaliação anterior emitida com a sua chave, sem recalcular nem consumir cota.

Índice de anúncios

Todos os anúncios ativos que monitoramos (portais e proprietários diretos), paginados, com a URL canônica na Zavaluo e, em venda, o USD/m² contra o valor de referência do bairro (delta_vs_reference, null enquanto o bairro calibra). Os filtros são os mesmos da busca do 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) descreve a quadra com dados abertos do governo da Cidade: distância ao metrô, ocorrências registradas em 500 m, escolas em 800 m, áreas verdes e hospitais. Não é uma avaliação; o detalhe traz cada componente e o dado de onde sai em context. É null quando o anúncio não publica o endereço exato.

predicted_usd_m2, value_delta e deal_score vêm do modelo hedônico vigente (model_version na resposta): a referência de anúncio para aquele imóvel dadas a metragem, os ambientes, a idade, a vaga e o entorno, quanto pede acima ou abaixo, e um 0–100 onde 50 é “no modelo”. Um value_delta além de ±0,45 quase sempre é erro de metragem ou de preço na fonte, não uma oportunidade. quality_score (0–100) mede quão completo é o registro; com sort=delta o índice ordena por value_delta quando existe.

Um anúncio

O detalhe completo por ref (1863 ou ZV-1863) ou por uuid: descrição, resumo, metragens, andar, comodidades, fotos, histórico de preços, a extração estruturada do texto com a sua versão e context (entorno: pontuações de transporte, segurança, escolas, verde e saúde com as distâncias e contagens por trás de cada uma). Nunca inclui dados de contato de quem publica.

Comparáveis

Os anúncios ativos mais parecidos ao redor de um ponto (500 m, ampliando para 1 km e 2,5 km se houver menos de cinco), cada um com o seu similarity (distância, metragem, ambientes, banheiros, idade, idade do anúncio) e o seu adjusted_usd_m2: o preço do comparável ajustado ao imóvel consultado com os coeficientes do modelo hedônico vigente (model_version). A mediana ponderada dos ajustados é a referência, e a faixa é o p25–p75. confidence A–D resume quantidade, similaridade e dispersão. Com asking_usd devolve asking_vs_reference. A variante por ref monta o sujeito com o anúncio e o exclui dos próprios comparáveis.

É uma referência de preços de anúncio, não uma avaliação: reference.basis diz isso em cada resposta. Os ajustes saem de um modelo log-linear estimado sobre os anúncios ativos de Buenos Aires (metragem, ambientes, banheiros, idade, vaga, proprietário direto, distância ao metrô, segurança e verde do entorno, tipo e bairro); drivers traz os ajustes que pesaram mais, em palavras.

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

Índice de bairro

Por bairro e por dia: estoque ativo, anúncios novos e retirados em 30 dias, proporção com baixa de preço, dias em mercado, USD/m² de venda e de aluguel mensal, rentabilidade bruta, entorno médio e os componentes da pontuação de mercado (momentum, liquidity, rental, entorno, affordability). market_score é null e calibrating true até haver 30 dias de histórico para momentum e liquidez: preferimos não publicar uma pontuação que só diga “barato”.

CABA Market Score

Contexto mensal do mercado da Cidade: uma pontuação 0–100 com cinco componentes (atividade de compra e venda 30 %, crédito imobiliário 25 %, condições de financiamento 15 %, estabilidade macro 15 %, risco soberano e cambial 15 %), o regime (very_weak … very_strong), as métricas cruas por trás de cada um (escrituras e hipotecas do Colegio de Escribanos, dólar A3500, TAMAR/BADLAR, taxa de política, UVA e estoque hipotecário do BCRA, IPC do INDEC, risco país), data_quality_score, is_provisional e calculation_version. Cada componente é um percentil sobre a própria história desde 2016.

É contexto, não um insumo de avaliação: nenhuma referência nem faixa de comparáveis é ajustada com esta pontuação (basis repete isso em cada resposta). A série histórica serve para traçar gráficos e para ler em que mercado se está vendendo. É recalculada diariamente e quando o Colegio publica um mês novo.

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

Estatísticas de mercado

Agregados por bairro, recalculados toda noite: mediana e quartis de USD/m², anúncios ativos, dias em mercado, baixa de preço mediana e a relação anúncio/fechamento quando há fechamentos reportados. Sem neighborhood devolve todos os bairros da cidade; o resultado traz até 100 linhas, as mais recentes primeiro.

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

Bairros

Os 48 bairros de Buenos Aires com slug, nome, comuna e centroide, e com include=geometry o polígono oficial do governo da Cidade em GeoJSON (WGS84). É informação pública: não exige chave nem consome cota. Use para mapas e para resolver o bairro de uma coordenada do lado do cliente.

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

Confiança e faixas

low_usd e high_usd são os quantis 10 e 90 do modelo. confidence (0–1) combina a densidade de comparáveis no raio, a dispersão dos preços deles e quantos fechamentos reais reportados temos na região. Com confiança baixa a faixa se alarga na direção da mediana do bairro; não inventamos precisão. Enquanto o histórico de preços for curto, calibrating é true.

Anúncio vs. fechamento

Em Buenos Aires o preço anunciado e o da escritura diferem, e a diferença varia por bairro e por momento do ciclo. estimate_usd e likely_closing_usd são o fechamento provável. likely_asking_usd é o preço de anúncio que hoje leva a esse fechamento, e asking_vs_closing_adj a diferença aplicada. A diferença é calibrada com fechamentos reportados por proprietários e com agregados públicos.

Moedas e câmbio

O mercado de Buenos Aires opera em USD; todos os valores do modelo são em USD. estimate_local e local_currency convertem pelo câmbio MEP do dia. Guardamos as séries oficial, mep e blue por data, para que a conversão seja auditável.

Erros

Limites e versões

A cota é mensal por chave e cada request consumido conta, inclusive os que devolvem 400. A versão da API vai na URL (/v1); mudanças incompatíveis saem como /v2 com ao menos 6 meses de convivência. O modelo é retreinado e a sua model_version muda sem afetar o contrato; avisamos por e-mail e no changelog antes de cada versão maior.

Changelog

2026-09 · /v1 em calibração para Buenos Aires. GET /market-stats e GET /barrios (com geometria oficial) ativos; POST /valuations valida e responde 503 até o modelo estar calibrado.