Przejdź do treści
CenyMieszkań.pl

Dla deweloperów

API i integracje MCP

Programowy dostęp do cen transakcyjnych (RCN) i ofertowych nieruchomości w Polsce — przez REST API v1 oraz konektor MCP, który podłącza nasze dane bezpośrednio do Claude i ChatGPT.

Dokumentacja interaktywna (Swagger)Szybki start MCP

Przegląd REST v1

Wszystkie punkty końcowe działają pod ścieżką bazową /api/v1. Pełną, zawsze aktualną specyfikację (parametry, schematy, odpowiedzi) znajdziesz w interaktywnej dokumentacji generowanej wprost z API:

Swagger UI → /docsReDoc → /redocSchemat → /openapi.json
Transakcje
/api/v1/transactions/search

Transakcje notarialne (RCN) z filtrami przestrzennymi i atrybutowymi.

Agregacje H3
/api/v1/aggregations/h3

Siatka heksagonalna H3 z medianami cen — źródło heatmapy na mapie.

Miasta
/api/v1/cities/summary

Lista miast i podstawowe wskaźniki rynku.

Trendy
/api/v1/trends/city/{slug}

Szeregi czasowe cen dla miasta, komórki H3 lub adresu.

Spread
/api/v1/spread/national

Różnica między ceną ofertową a transakcyjną (asking-to-transaction).

Statystyki
/api/v1/statistics/{slug}

Zagregowane statystyki rynku dla wybranego miasta.

Porównywalne
/api/v1/comparables

Zbiór porównywalnych transakcji dla wskazanej nieruchomości.

Wyceny (AVM)
/api/v1/valuations/estimate

Automatyczna wycena nieruchomości (model AVM oparty o XGBoost).

Budynki
/api/v1/buildings

Dane cenowe na poziomie budynku.

Adresy
/api/v1/addresses/{id_or_slug}

Wyszukiwanie i dane na poziomie adresu.

Osiedla
/api/v1/estates

Osiedla (materializowane) wraz z ich statystykami.

Oferty
/api/v1/offers

Ceny ofertowe z rynku pierwotnego.

Geokodowanie
/api/v1/geocode/search

Zamiana adresu na współrzędne.

Uwierzytelnianie

Dostępne są dwa mechanizmy: token JWT (dla aplikacji z kontem użytkownika) oraz klucz API (dla integracji serwer-serwer, z rozliczaniem zapytań).

Klucz API

Klucz przekazujesz w nagłówku X-API-Key lub jako Authorization: Bearer cmk_…. Klucze mają prefiks cmk_ i są widoczne w całości tylko raz — przy utworzeniu.

Przykład: klucz API
curl -H "X-API-Key: cmk_twoj_klucz" \
  "http://127.0.0.1:8000/api/v1/transactions/search?city=warszawa&limit=10"

Token JWT

Zarejestruj konto (POST /api/v1/auth/register), zaloguj się, a otrzymany token dołączaj w nagłówku Authorization: Bearer. Token jest ważny 1 godzinę.

Przykład: logowanie JWT
# 1. Zaloguj się i pobierz token JWT
curl -X POST "http://127.0.0.1:8000/api/v1/auth/jwt/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=email@example.com&password=***"

# 2. Użyj tokenu w nagłówku Authorization
curl -H "Authorization: Bearer <token>" \
  "http://127.0.0.1:8000/api/v1/cities/summary"

Dwa punkty wyceny — który wybrać

API udostępnia dwa niezależne silniki wyceny. Domyślnym wyborem — i tym, którego używa nasz własny formularz /wycena — jest GET /api/v1/valuation.

Punkt końcowyMetodaMediana błędu
GET /api/v1/valuationŚrednia ważona podobieństwem z transakcji porównywalnych7,6%
POST /api/v1/valuations/estimateModel AVM (XGBoost) z przedziałem ufności26,3%

Mediana bezwzględnego błędu względem ceny, po jakiej nieruchomość faktycznie się sprzedała, na 399 transakcjach wyłączonych z obliczeń (mieszkania 30–100 m², od czerwca 2025, osiem miast). W granicach 10% od ceny transakcyjnej mieści się 61% wycen porównawczych i 11% wycen modelowych. Model AVM zwraca za to jawny przedział ufności — porównawcza wycena go nie ma.

Limity zapytań

  • 60 zapytań/min — globalny limit na adres IP.
  • 10 zapytań/min — dla punktu wyceny AVM (/api/v1/valuations/estimate), z uwagi na koszt obliczeń.
  • 1000 zapytań/miesiąc — domyślny limit przypisany do klucza API.

Cennik i wyższe limity dla zastosowań komercyjnych — wkrótce. W sprawie podniesienia limitów napisz na kontakt@cenymieszkan.pl.

Konektor MCP dla Claude i ChatGPT

MCP (Model Context Protocol) to standard, który pozwala asystentom AI korzystać z zewnętrznych źródeł danych. Nasz serwer MCP udostępnia dane o cenach nieruchomości jako zestaw narzędzi, z których model może korzystać podczas rozmowy. Serwer działa pod adresem http://127.0.0.1:8000/mcp.

Claude Desktop

Dodaj poniższy wpis do pliku konfiguracyjnego claude_desktop_config.json i zrestartuj aplikację:

claude_desktop_config.json
{
  "mcpServers": {
    "cenymieszkan": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}

ChatGPT

W ustawieniach konektorów (Connectors) dodaj niestandardowy konektor MCP wskazujący na http://127.0.0.1:8000/mcp. W środowisku produkcyjnym może być wymagany klucz API (nagłówek X-API-Key).

Dostępne narzędzia

search_transactions

Wyszukiwanie transakcji notarialnych z filtrami przestrzennymi i atrybutowymi.

get_area_stats

Statystyki cenowe dla obszaru (miasto, dzielnica, komórka H3).

find_comparables

Porównywalne transakcje dla wskazanej nieruchomości.

compare_offer_vs_transaction

Porównanie ceny ofertowej z transakcyjną (spread).

get_valuation

Automatyczna wycena nieruchomości (AVM).

Przykładowe pytania

  • „Jakie są mediany cen mieszkań w Krakowie w ostatnim kwartale?”
  • „Znajdź 5 porównywalnych transakcji do mieszkania 55 m² przy ul. Długiej w Gdańsku.”
  • „O ile ceny ofertowe w Warszawie różnią się od transakcyjnych?”
  • „Wyceń mieszkanie 48 m², 2 pokoje, Wrocław, dzielnica Krzyki.”