API оценки

Воспроизводимая эталонная стоимость любого объекта в городе Буэнос-Айрес с доверительным диапазоном, сопоставимыми объектами и пояснением простым языком. Базовый URL: https://api.zavaluo.com/v1. Все ответы — JSON в кодировке UTF-8.

Аутентификация

Каждый запрос передаёт ваш ключ в заголовке Authorization. Мы храним только хеш ключа: если вы его потеряете, мы выпустим новый.

Authorization: Bearer zv_live_9f3c…

Запросите ключ на странице Доступ к API. Тариф Explorar включает 100 запросов в месяц; остальные тарифы — свою квоту.

Первый запрос

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

Создать оценку

Возвращает расчётную стоимость объекта. Достаточно одного адреса; каждый дополнительный атрибут сужает диапазон.

Тело запроса

Ответ

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

Получить оценку

Возвращает ранее выданную с вашим ключом оценку без пересчёта и без расхода квоты.

Индекс объявлений

Все активные объявления, которые мы отслеживаем (порталы и собственники напрямую), с пагинацией, каноническим URL на Zavaluo и, для продажи, USD/м² относительно эталонной стоимости barrio (delta_vs_reference, null, пока barrio калибруется). Фильтры те же, что в поиске на сайте.

{ "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) описывает квартал по открытым данным правительства города (GCBA): расстояние до subte (метро), зарегистрированные происшествия в радиусе 500 м, школы в радиусе 800 м, зелёные зоны и больницы. Это не оценка стоимости; в детальной записи каждая составляющая и исходные данные для неё приводятся в context. Значение null, если в объявлении не указан точный адрес.

predicted_usd_m2, value_delta и deal_score получены из действующей гедонической модели (model_version в ответе): эталонная цена предложения для этого объявления с учётом площади, комнат, возраста здания, парковки и окружения, насколько запрашиваемая цена выше или ниже её, и шкала 0–100, где 50 означает «на уровне модели». value_delta за пределами ±0,45 почти всегда означает ошибку площади или цены в источнике, а не выгодное предложение. quality_score (0–100) показывает полноту записи; при sort=delta индекс сортируется по value_delta, если оно есть.

Одно объявление

Полная информация по ref (1863 или ZV-1863) или по uuid: описание, краткое резюме, площади, этаж, удобства, фотографии, история цен, структурированные данные, извлечённые из текста, с их версией, и context (окружение: баллы за транспорт, безопасность, школы, зелёные зоны и здравоохранение с расстояниями и количествами, на которых они основаны). Контактные данные автора объявления никогда не включаются.

Сопоставимые объекты

Самые похожие активные объявления вокруг точки (500 м; радиус расширяется до 1 км и 2,5 км, если их меньше пяти), у каждого — similarity (расстояние, площадь, комнаты, санузлы, возраст здания, возраст объявления) и adjusted_usd_m2: цена сопоставимого объекта, скорректированная под запрошенный объект с помощью коэффициентов действующей гедонической модели (model_version). Взвешенная медиана скорректированных значений — это эталон, а диапазон — p25–p75. confidence A–D обобщает количество, сходство и разброс. При передаче asking_usd возвращается asking_vs_reference. Вариант по ref строит субъект оценки из объявления и исключает его из собственных сопоставимых объектов.

Это эталон цен предложения, а не оценка стоимости: reference.basis сообщает об этом в каждом ответе. Корректировки получены из лог-линейной модели, оценённой на активных объявлениях Буэнос-Айреса (площадь, комнаты, санузлы, возраст здания, парковка, продажа от собственника, расстояние до subte, безопасность и зелёные зоны окружения, тип и barrio); drivers словами описывает корректировки, которые повлияли сильнее всего.

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

По barrio и дню: активный объём предложения, новые и снятые объявления за 30 дней, доля объявлений со сниженной ценой, срок экспозиции, USD/м² при продаже и при месячной аренде, валовая доходность, средняя оценка окружения и составляющие рыночного балла (momentum, liquidity, rental, entorno, affordability). market_score равно null, а calibrating — true, пока не накопится 30 дней истории для динамики и ликвидности: мы предпочитаем не публиковать балл, который говорит только «дёшево».

CABA Market Score

Ежемесячный контекст рынка города: балл 0–100 из пяти составляющих (активность сделок купли-продажи 30 %, ипотечное кредитование 25 %, условия финансирования 15 %, макростабильность 15 %, суверенный и валютный риск 15 %), режим (very_weak … very_strong), исходные метрики за каждой составляющей (escrituras — нотариально оформленные сделки — и ипотеки по данным Colegio de Escribanos, доллар A3500, TAMAR/BADLAR, ключевая ставка, UVA и ипотечный портфель по данным BCRA, ИПЦ INDEC, страновой риск), data_quality_score, is_provisional и calculation_version. Каждая составляющая — это перцентиль относительно собственной истории с 2016 года.

Это контекст, а не входные данные для оценки: ни эталон, ни диапазон сопоставимых объектов этим баллом не корректируются (basis повторяет это в каждом ответе). Исторический ряд нужен для графиков и для понимания того, на каком рынке идёт продажа. Пересчитывается ежедневно и всякий раз, когда Colegio публикует данные за новый месяц.

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

Рыночная статистика

Агрегаты по barrios, пересчитываемые каждую ночь: медиана и квартили USD/м², активные объявления, срок экспозиции, медианное снижение цены и соотношение цены предложения и цены сделки, если есть данные о сделках. Без neighborhood возвращаются все barrios города; результат содержит до 100 строк, сначала самые свежие.

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

48 barrios CABA со slug, названием, comuna (административным округом) и центроидом, а с include=geometry — официальный полигон GCBA в формате GeoJSON (WGS84). Это публичная информация: ключ не нужен, квота не расходуется. Используйте её для карт и для определения barrio по координате на стороне клиента.

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

Достоверность и диапазоны

low_usd и high_usd — это 10-й и 90-й квантили модели. confidence (0–1) объединяет плотность сопоставимых объектов в радиусе, разброс их цен и количество реальных сделок, о которых нам сообщили в этом районе. При низкой достоверности диапазон расширяется в сторону медианы barrio; мы не выдумываем точность. Пока история цен короткая, calibrating равно true.

Цена предложения и цена сделки

В CABA цена в объявлении и цена в escritura (нотариальном акте купли-продажи) различаются, и разрыв зависит от barrio и фазы цикла. estimate_usd и likely_closing_usd — это вероятная цена сделки. likely_asking_usd — цена предложения, которая сегодня приводит к такой сделке, а asking_vs_closing_adj — применённый разрыв. Разрыв калибруется по сделкам, о которых сообщают собственники, и по публичным агрегатам.

Валюты и обменные курсы

Рынок CABA работает в USD; все значения модели указаны в USD. estimate_local и local_currency пересчитывают по курсу MEP (биржевой доллар) на текущий день. Мы храним ряды oficial, mep и blue по датам, так что пересчёт можно проверить.

Ошибки

Лимиты и версии

Квота — месячная для каждого ключа, и учитывается каждый обработанный запрос, включая те, что вернули 400. Версия API указана в URL (/v1); несовместимые изменения выходят как /v2 с периодом параллельной работы не менее 6 месяцев. Модель переобучается, и её model_version меняется без влияния на контракт; перед каждой мажорной версией мы сообщаем по email и в списке изменений.

Список изменений

2026-09 · /v1 на калибровке для CABA. GET /market-stats и GET /barrios (с официальной геометрией) работают; POST /valuations проверяет запрос и отвечает 503, пока модель не откалибрована.