Automatyczna wycena nieruchomości (AVM)
AVM (Automated Valuation Model) to szybki benchmark ceny nieruchomości porównujący parametry Twojej oferty (cena ofertowa, metraż) ze średnimi rynkowymi cenami transakcyjnymi z Rejestru Cen Nieruchomości (RCN). Zamiast oceniać jakość lokalizacji (to robi /evaluate i LIM), AVM odpowiada na jedno pytanie:
Czy moja cena ofertowa jest adekwatna do realnych, notarialnych cen transakcyjnych w tej okolicy?
Endpoint jest dostępny pod adresem POST /api/v1/evaluate/avm i wymaga klucza API (Bearer).
Kiedy używać AVM?
| Scenariusz | Czego dostarcza AVM |
|---|---|
| Wycena mieszkania do sprzedaży | Czy oferta jest zawyżona, w normie, czy poniżej rynku (dla danego metrażu)? |
| Weryfikacja ceny zakupu | Jaka jest szacunkowa wartość rynkowa (fair_value) nieruchomości? |
| Analiza gruntu budowlanego | Cena za m² gruntu vs. średnia transakcyjna dla komórki H3 L9 (próg 25%). |
| Due diligence inwestycyjne | Szybki, obiektywny punkt odniesienia przed negocjacją ceny. |
Wskazówka: AVM to celowy, lekki endpoint do szybkiej wyceny. Jeśli potrzebujesz pełnego raportu lokalizacji razem z wyceną i dodatkowymi warstwami (MPZP, GUNB, demografia, ryzyka), użyj LIM — jego odpowiedź zawiera blok
market_valuation_avmz tymi samymi cenami transakcyjnymi RCN.
Parametry żądania
Żądanie przyjmuje dane nieruchomości oraz lokalizację na trzy sposoby:
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
latitude / longitude | float | tak* | Współrzędne w EPSG:4326 (latitude -90..90, longitude -180..180). |
address | string | tak* | Adres tekstowy w Polsce do geokodowania, np. ul. Legnicka 12, Wrocław. |
parcel_id | string | tak* | Pełny identyfikator działki TERYT, np. 026401_1.0022.AR_11.54/2. |
property_type | string | tak | Typ nieruchomości: apartment (mieszkanie), house (dom) lub land (grunt). |
area_m2 | float | tak | Powierzchnia użytkowa w m² (większa od 0). |
listing_price | float | tak | Cena ofertowa brutto w PLN (większa od 0). |
* Wymagane jest dokładnie jedno z: (współrzędne) albo address albo parcel_id.
Przykłady wywołań
curl -X 'POST' \
'https://api.lokalscore.pl/api/v1/evaluate/avm' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ls_TWOJ_KLUCZ_API' \
-H 'Content-Type: application/json' \
-d '{
"latitude": 51.1093,
"longitude": 17.0289,
"property_type": "apartment",
"area_m2": 55,
"listing_price": 550000
}'Struktura odpowiedzi
| Pole | Typ | Opis |
|---|---|---|
market_data_available | bool | Czy w komórce H3 L9 dostępne są dane transakcyjne RCN dla danego typu nieruchomości. |
h3_index_l9 | string | Indeks komórki H3 (rozdzielczość 9), dla której pobrano transakcje. |
property_type | string | Typ wycenianej nieruchomości (apartment, house, land). |
listing_price | float | Przekazana cena ofertowa (PLN). |
area_m2 | float | Powierzchnia nieruchomości (m²). |
listing_price_per_m2 | float | Cena ofertowa w przeliczeniu na m² (listing_price / area_m2). |
market_price_per_m2 | float? | Średnia rynkowa cena transakcyjna za m² z RCN w komórce H3. null przy NO_DATA. |
fair_value | float? | Szacunkowa wartość rynkowa nieruchomości (market_price_per_m2 * area_m2). null przy NO_DATA. |
price_difference_per_m2 | float? | Różnica ceny za m² między ofertą a rynkiem (PLN/m²). null przy NO_DATA. |
price_difference_ratio | float? | Procentowe odchylenie ceny ofertowej od rynkowej (np. 0.12 = +12%). null przy NO_DATA. |
status | string | Klasyfikacja wyceny: FAIR, OVERPRICED, UNDERPRICED lub NO_DATA. |
sample_size_12m | int | Liczba transakcji bazowych RCN dla danego typu w komórce H3 w ostatnich 12–36 mies. |
resolution_metadata | object? | Metadane geokodowania adresu / działki powiązane z zapytaniem. |
Przykład odpowiedzi
{
"market_data_available": true,
"h3_index_l9": "8f2637c5303c000",
"property_type": "apartment",
"listing_price": 550000,
"area_m2": 55,
"listing_price_per_m2": 10000.0,
"market_price_per_m2": 9210.5,
"fair_value": 506577.5,
"price_difference_per_m2": 789.5,
"price_difference_ratio": 0.0857,
"status": "FAIR",
"sample_size_12m": 14,
"resolution_metadata": {}
}Interpretacja statusu
Status wyceny zależy od odchylenia ceny ofertowej od rynkowej (price_difference_ratio). Próg odchylenia jest dynamiczny i zależny od typu nieruchomości:
| Typ | Próg odchylenia | Status |
|---|---|---|
apartment, house | ±10% | FAIR (w normie) gdy odchylenie ≤ 10%; OVERPRICED gdy > +10%; UNDERPRICED gdy < -10%. |
land | ±25% | Grunty mają szerszy próg ze względu na większą zmienność cen transakcyjnych. |
FAIR— cena ofertowa jest w normie względem rynku transakcyjnego (odchylenie w obrębie progu).OVERPRICED— oferta jest przeszacowana względem rynku. Sygnał do weryfikacji lub negocjacji ceny.UNDERPRICED— oferta jest niedoszacowana (okazja). Przy zakupie może oznaczać potencjał, ale warto zweryfikować stan techniczny i metraż.NO_DATA— brak transakcji RCN dla danego typu nieruchomości w komórce H3 L9 (market_data_available: false). Nie można wyznaczyć wartości rynkowej.
Ważne: Benchmark opiera się na cenach transakcyjnych (notarialnych), a nie ofertowych. Transakcje są agregowane dla komórki H3 L9 (~0,17 km²) w przedziale 12–36 miesięcy. Im większy
sample_size_12m, tym bardziej wiarygodna średnia. Przy bardzo małej próbie odchylenie może być mniej reprezentatywne.
Obsługa błędów
- 401/403 — brak lub nieprawidłowy klucz API (Bearer).
- 422 — błędne parametry (np. brak lokalizacji,
property_typespozaapartment/house/land,area_m2lublisting_price≤ 0). - 429 — przekroczony limit zapytań (rate limit lub limit miesięczny).
- 504 — przekroczony limit czasu. AVM jest szybki (zwykle < 5 s), ale geokodowanie adresu może wydłużyć odpowiedź.
Następne kroki
- Location Intelligence Model (LIM) — pełny raport B2B, który zawiera blok
market_valuation_avmoraz analizę MPZP, GUNB, demografii i ryzyk. - Dokumentacja API — interaktywna konsola Swagger UI ze schematami
AVMRequestiAVMResponse. - Integracja GIS — praca z indeksami H3 (agregacja transakcji AVM używa rozdzielczości 9).
- Uwierzytelnianie — klucze Bearer, limity i obsługa błędów.
- SDK Python — metoda
evaluate_avm(). - SDK Node.js — metoda
evaluateAVM().