Otodom API: ogłoszenia nieruchomości w JSON
Jeśli szukasz API do importu ofert dla biura nieruchomości albo dewelopera, to nie ta usługa: tu niczego się nie publikuje, a jedynie odczytuje stronę kupującego, czyli to, co Otodom pokazuje każdemu odwiedzającemu. Cena, cena za m², czynsz, metraż, piętro, dzielnica i ogłoszeniodawca wracają jako JSON, który obsłużysz z Pythona albo z dowolnego innego języka. Ten sam silnik czyta też imovirtual.com i storia.ro (parametr `site`), ale domyślnie działa na otodom.pl i w złotówkach.
Endpointy
| endpoint | Co zwraca | Wymagane |
|---|---|---|
| search | Oferty sprzedaży lub wynajmu: rodzaj nieruchomości, lokalizacja (id z `locations`), cena, cena za m², metraż, liczba pokoi, piętro, rok budowy, kto dodał ogłoszenie (osoba prywatna, biuro, deweloper), rynek pierwotny lub wtórny, słowo w opisie, udogodnienia i sortowanie serwisu. | wszystkie opcjonalne |
| listing | Pełna oferta po `listing_id` (token ID… z końca adresu) albo po URL: cena, czynsz administracyjny, kaucja, cena za m², piętro, rok budowy, materiał, forma własności, ogrzewanie, opis, zdjęcia, rzuty, współrzędne i ogłoszeniodawca. Dla inwestycji: cena „od” za m² i pierwszych 10 lokali. | wszystkie opcjonalne |
| locations | Wyszukiwarka lokalizacji: wpisujesz „Kraków” albo „Mokotów”, dostajesz identyfikatory serwisu z poziomem (województwo, powiat, miasto, dzielnica). Polskie znaki są opcjonalne. | query |
Każde wywołanie jest rozliczane w kredytach. Nieudane i zablokowane wywołania są darmowe.
Działający przykład
To są ceny ofertowe, a nie transakcyjne: tyle chce sprzedający, a nie tyle zapłacił kupujący. Czynsz (`maintenance_fee_monthly`) jest osobnym polem i bywa pusty, jeśli ogłoszeniodawca go nie podał. `decoy_rows_dropped: 1` oznacza, że z tej strony wyników usunęliśmy jeden fałszywy wiersz wstawiony przez serwis.
curl -X POST https://api.reefapi.com/otodom/v1/search \
-H "x-api-key: TWOJ_KLUCZ" \
-H "content-type: application/json" \
-d '{"site": "pl", "transaction": "sell", "estate": "flat", "location": "malopolskie/krakow/krakow/krakow", "rooms": "2"}'{
"ok": true,
"data": {
"results": [
{
"listing_id": "ID4x6ic",
"title": "2-pokojowe mieszkanie 49m2 + balkon Bezpośrednio",
"price": 620250,
"currency": "PLN",
"price_per_m2": 12500,
"maintenance_fee_monthly": null,
"area_m2": 49.62,
"rooms": 2,
"floor_number": 2,
"location": { "city": "Kraków", "district": "Podgórze", "neighbourhood": "Rybitwy", "street": "ul. Bukowa" },
"advertiser_type": "business",
"agency": { "name": "Wawel Service", "type": "developer" },
"development": { "title": "Enklawa Bukowa II" }
},
{
"listing_id": "ID4CYZz",
"title": "Stare budownictwo, cegła, 2 pokoje, balkon, las za oknem Borek Fałęcki",
"price": 635000,
"currency": "PLN",
"price_per_m2": 13774.4,
"maintenance_fee_monthly": 890,
"area_m2": 46.1,
"rooms": 2,
"location": { "city": "Kraków", "district": "Łagiewniki-Borek Fałęcki", "neighbourhood": "Borek Fałęcki" },
"advertiser_type": "private_person",
"tags": ["SEPARATE_KITCHEN", "BALCONY", "STORAGE_ROOM", "BASEMENT", "TOP_FLOOR"]
},
...
],
"total": 5805,
"last_page": 162,
"decoy_rows_dropped": 1
},
"meta": { "record_count": 36, "cache_hit": false, "mode": "live" }
}Własny scraper Otodom: na co uważać
Otodom to aplikacja Next.js i dane da się czytać z jej własnych odpowiedzi JSON, tyle że adres tych odpowiedzi zawiera identyfikator builda (buildId), który często się zmienia — w trakcie naszych pomiarów zmienił się w ciągu około 40 minut. Skrypt, który go raz zapamięta, wkrótce zaczyna dostawać 404.
Do tego w wynikach pojawia się wiersz-pułapka z niemożliwą datą dodania (29 lutego 1999), który potrafi skopiować tytuł i cenę sąsiedniej oferty. A wartość filtra, której serwis nie zna (np. zbyt duża liczba pokoi), jest po cichu pomijana: dostajesz HTTP 200 i cały rynek zamiast wyniku z filtrem.
Tutaj każdy filtr jest porównywany z tym, co serwis sam potwierdza jako zastosowane, fałszywy wiersz jest odrzucany i liczony w `decoy_rows_dropped`, a nieaktualny buildId odświeżamy sami. Jeśli jedną dzielnicę potrzebujesz tylko raz, własny skrypt będzie tańszy; przy codziennym śledzeniu cen płacisz za wyłapywanie tych cichych błędów.
Ograniczenia i uczciwe uwagi
- To nie jest oficjalne API Otodom i nie mamy z Otodom partnerstwa.
- Ceny są ofertowe. Cen transakcyjnych ani historii zmian ceny Otodom nie publikuje, więc nie ma ich też tutaj.
- Czynsz jest wypełniony tylko tam, gdzie podał go ogłoszeniodawca: w szerokim pomiarze (wszystkie rodzaje nieruchomości) w 886 z 2340 wierszy, a w przykładowym wyszukiwaniu mieszkań w Krakowie w 11 z 36.
- Liczba wierszy na stronie się waha (np. 23–37 przy domyślnym limicie 36), a wśród mieszkań trafiają się inwestycje deweloperskie (`kind: "investment"`) z ceną „od” za m² zamiast ceny całkowitej.
- Nie ma wyszukiwania w promieniu od punktu ani po kilku lokalizacjach naraz.