Mamy dla was coś, co w świecie portali ogłoszeniowych właściwie się nie zdarza: całkowicie otwarte, darmowe API do dodawania ofert działek. Bez zakładania konta, bez czekania na akceptację, bez klucza dostępu, którego trzeba pilnować jak hasła do konta bankowego. Jedno zapytanie HTTP i ogłoszenie jest w serwisie.
Dlaczego w ogóle to zrobiliśmy
Wracamy tu do naszej podstawowej misji, czyli budowania przejrzystego i darmowego rynku nieruchomości w Polsce. Otwarty rynek to nie tylko brak prowizji dla kupującego czy sprzedającego, to też brak sztucznych barier technicznych. Mnóstwo osób prowadzi własne serwisy z ogłoszeniami, systemy CRM dla biur nieruchomości albo prywatne narzędzia do zarządzania portfelem działek. Do tej pory, żeby taka oferta trafiła również do tuziemia.pl, ktoś musiał ręcznie wchodzić na stronę, wypełniać formularz, wklejać dane. Uznaliśmy, że to zwyczajnie bez sensu w czasach, gdy każdy szanujący się system potrafi rozmawiać z innym systemem przez API.
Więc otworzyliśmy nasze API dla każdego. Dosłownie każdego, kto ma numer ewidencyjny działki, cenę i chwilę czasu na jedno zapytanie POST.
Jak to działa w praktyce
Cały mechanizm sprowadza się do jednego adresu:
POST https://tuziemia.pl/api/ofertaWymagane są tylko trzy rzeczy: lista numerów ewidencyjnych działek, cena w złotych oraz co najmniej jeden sposób kontaktu ze sprzedającym, telefon albo email. Wszystko inne, w tym nazwa sprzedającego czy opis oferty, jest opcjonalne, choć oczywiście im więcej szczegółów podacie, tym pełniejsze i bardziej atrakcyjne będzie ogłoszenie dla potencjalnego kupującego.
Resztą zajmuje się już sam serwis. Na podstawie numeru ewidencyjnego tuziemia.pl automatycznie wylicza powierzchnię działki, przypisuje region i sprawdza plany zagospodarowania przestrzennego. Wy podajecie surowe dane, a system sam składa z nich kompletne ogłoszenie.
Prosty przykład w cURL, żeby zobaczyć to na żywym organizmie:
bash
curl -X POST https://tuziemia.pl/api/oferta \
-H "Content-Type: application/json" \
-d '{
"parcelIds": ["142503_5.0004.AR_1.590/1"],
"price": 250000,
"sellerName": "Jan Kowalski",
"sellerPhone": "+48 600 123 456",
"description": "Dzialka budowlana 1200m2, media na granicy."
}'Jeśli wszystko się zgadza, w odpowiedzi dostajecie identyfikator oferty, jej adres w serwisie i podstawowe dane, które udało się automatycznie wyliczyć, w tym powierzchnię i region. Jeśli czegoś zabraknie, na przykład ceny albo obu form kontaktu naraz, API grzecznie odpowie kodem błędu i wskaże dokładnie, czego brakuje, więc nie trzeba zgadywać.
Dla kogo to ma sens
Przede wszystkim dla osób i firm, które na co dzień pracują na większej liczbie ofert niż da się ręcznie wklejać do formularza. Jeśli prowadzicie własny system CRM dla biura nieruchomości, macie bazę działek w Excelu, którą regularnie aktualizujecie, albo budujecie narzędzie automatyzujące pracę agenta, to API pozwala wam jednym ruchem publikować te same oferty również na tuziemia.pl, bez podwójnej pracy. Świetnie sprawdza się też w narzędziach do automatyzacji, jak n8n, gdzie można podłączyć całą bazę działek do jednego węzła HTTP Request i zamienić import ofert w proces, który dzieje się sam, bez klikania.
Otwarte, bo tak powinno być
Świadomie zrezygnowaliśmy z rejestracji i kluczy API. Wiemy, że to nietypowe podejście, bo większość serwisów najpierw prosi o konto, potem o klucz, a czasem jeszcze o limity zapytań. My uznaliśmy, że skoro naszym celem jest jak najszersza, jak najbardziej otwarta baza ofert działek w Polsce, to najlepszym sposobem na jej budowanie jest usunięcie wszystkiego, co mogłoby kogokolwiek zniechęcić do dodania oferty.
Jeśli macie pytania techniczne, natrafiliście na problem z integracją albo po prostu chcecie się podzielić, do czego wykorzystaliście API, piszcie na kontakt@tuziemia.pl. Pełna dokumentacja, ze wszystkimi parametrami i przykładami w JavaScript oraz Pythonie, jest dostępna pod adresem tuziemia.pl/api.
