# JanuszMap — Interaktywna Mapa Ogłoszeń OLX i Analiza Cenowa

Wizualizacja ogłoszeń z portalu **OLX.pl** na interaktywnej mapie z cenami w stylu Airbnb, analizą statystyczną rynku (średnia, mediana, ceny min/max) oraz eksportem do GeoJSON.

- **Adres strony**: https://januszmap.pl
- **Autor i kontakt**: janusz@januszmap.pl
- **Status projektu**: Bezpłatne narzędzie publiczne

---

## 1. Czym jest JanuszMap?

**JanuszMap** to aplikacja internetowa stworzona dla osób szukających nieruchomości (mieszkań, domów, działek), samochodów, ofert pracy lub przedmiotów codziennego użytku z naciskiem na **lokalizację geograficzną**.

Zamiast przeglądać setki stron z listami ogłoszeń tekstowych, JanuszMap nanosi wszystkie oferty na mapę w postaci czytelnych przypinek z cenami (wzorem Airbnb). Pozwala to w ułamku sekundy zorientować się w cenach w poszczególnych dzielnicach, ulicach czy miejscowościach podmiejskich.

---

## 2. Kluczowe funkcjonalności

1. **Interaktywna mapa (Leaflet.js + OpenStreetMap / CartoDB)**:
   - Dynamiczne przypinki z cenami (np. `450 000 zł`, `3 200 zł/mc`).
   - Automatyczne grupowanie znaczników (*Marker Clustering*) zapobiegające zlewaniu się ofert przy dużym zagęszczeniu.
   - Płynne centrowanie i dopasowywanie widoku do znalezionych punktów.
2. **Statystyki rynku i poziomy cenowe**:
   - Wyliczanie w czasie rzeczywistym: liczby ogłoszeń ogółem, liczby ofert z koordynatami na mapie, ceny minimalnej, średniej arytmetycznej, mediany rynkowej oraz ceny maksymalnej.
   - Porównanie cenowe wybranego ogłoszenia ze średnią i medianą w danym wyszukiwaniu.
3. **Wygodne filtrowanie i selekcja**:
   - `Cena od - do`: Precyzyjne widełki cenowe.
   - `Filtruj słowo / dzielnica`: Natychmiastowe przeszukiwanie wyników na mapie.
   - `Tylko w tytule`: Ograniczenie wyszukiwania do tytułów ogłoszeń, eliminujące przypadkowe dopasowania ze słów kluczowych w opisach.
   - `Top 3 najtańsze`: Szybkie wyróżnienie trzech najtańszych propozycji (bez ofert pracy).
   - `Bez ofert pracy`: Ukrywanie ogłoszeń z kategorii praca przy przeglądaniu innych ofert.
4. **Szczegółowy podgląd ogłoszenia**:
   - Po kliknięciu w przypinkę lub kartę: pełna galeria zdjęć, parametry techniczne (metraż, liczba pokoi, rocznik, paliwo itp.), pełny opis oraz bezpośredni przycisk do oryginalnego ogłoszenia na OLX.
5. **Eksport do formatu GeoJSON**:
   - Możliwość pobrania wszystkich przefiltrowanych punktów jako plik `.geojson`, gotowy do importu w Google My Maps, QGIS, ArcGIS lub własnych analizach przestrzennych.
6. **Udostępnianie wyników**:
   - Możliwość skopiowania unikalnego linku z parametrem wyszukiwania (np. `https://januszmap.pl/?url=...`) i przesłania go znajomym.

---

## 3. Jak działa aplikacja?

1. **Wyszukiwanie**:
   - Użytkownik wkleja dowolny link z wynikami wyszukiwania z portalu OLX.pl (np. `https://www.olx.pl/nieruchomosci/dzialki/sprzedaz/krakow/`) LUB wpisuje naturalną polską frazę (np. `działki budowlane Gdańsk`, `kawalerka Warszawa`, `Audi A4 Poznań`).
2. **Tłumaczenie zapytań**:
   - Wpisane frazy tekstowe są automatycznie zamieniane na optymalne zapytania OLX z rozpoznaniem miasta i kategorii.
3. **Pobieranie i agregacja danych**:
   - Serwer pobiera publicznie dostępne dane ofertowe (w tym współrzędne geograficzne `latitude` i `longitude` zapisane w publicznym stanie strony), łącząc kolejne strony wyników (do limitu OLX).
4. **Wizualizacja**:
   - Przeglądarka nanosi oferty na mapę, oblicza metryki statystyczne i udostępnia filtry.

---

## 4. Źródła danych, etyka i prywatność

- **Źródło danych**: JanuszMap wizualizuje wyłącznie dane publicznie udostępniane przez portal OLX.pl na stronach wyników wyszukiwania.
- **Brak magazynowania danych osobowych**: Aplikacja nie zbiera danych osobowych użytkowników, nie wymaga logowania, ani nie przechowuje historii wyszukiwań na serwerze.
- **Bezpośrednie transakcje na OLX**: JanuszMap nie pośredniczy w transakcjach ani płatnościach — każde ogłoszenie zawiera bezpośredni odsyłacz do portalu źródłowego.
- **Pamięć podręczna (Cache)**: Wyniki wyszukiwania są tymczasowo buforowane w pamięci serwera przez krótki czas (TTL 2h), aby chronić serwery źródłowe przed nadmiernym obciążeniem.

---

## 5. Ograniczenia techniczne

- **Limit 1 000 ogłoszeń na zapytanie**: Portal OLX nakłada limit 25 stron wyników (maksymalnie ok. 1 000 ogłoszeń) na pojedyncze zapytanie wyszukiwawcze. Wyszukiwanie dla całego województwa zwróci tylko wycinek ofert; zaleca się podanie konkretnej miejscowości lub promienia poszukiwań (np. +15 km).
- **Wymagane współrzędne geograficzne**: Ogłoszenia, w których autor nie podał lokalizacji lub portal nie przypisał koordynatów GPS, nie mogą zostać umieszczone na mapie (są uwzględniane w ogólnej liczbie ofert).
- **Zabezpieczenia antybotowe API**: Wewnętrzny punkt końcowy `/api/scrape` jest zabezpieczony limitami zapytań (*rate limiting*) i dedykowany wyłącznie działaniu interfejsu JanuszMap. Roboty indeksujące powinny korzystać z plików dokumentacji (`/about.md`, `/llms.txt`, `/sitemap.xml`).

---

## 6. Przykłady wyszukiwań

- Działki rolne i budowlane: `https://www.olx.pl/nieruchomosci/dzialki/sprzedaz/krakow/`
- Mieszkania na wynajem: `https://www.olx.pl/nieruchomosci/mieszkania/wynajem/warszawa/`
- Samochody osobowe: `https://www.olx.pl/motoryzacja/samochody/wroclaw/`
- Frazowe: `praca zdalna`, `iphone 13 poznań`, `hala magazynowa katowice`