README.md

plot-finder

Python library to find Polish land parcels and analyze their surroundings.

Query the ULDK (GUGiK) API to get parcel data by TERYT ID or coordinates, then analyze nearby infrastructure using OpenStreetMap.

Installation

pip install plot-finder           # base
pip install plot-finder[viz]      # + interactive maps & PNG export
pip install plot-finder[ai]       # + AI-powered analysis (OpenAI)

Requirements: Python 3.10+ | pydantic httpx shapely pyproj

Quick Start

from plot_finder import Plot, PlotAnalyzer, PlotReporter

# Find a parcel
plot = Plot(plot_id="141201_1.0001.6509")
print(plot.voivodeship)  # mazowieckie
print(plot.centroid)     # (x, y)

# Analyze surroundings
analyzer = PlotAnalyzer(plot, radius=3000)

for place in analyzer.education():
    print(f"{place.name} — {place.distance_m}m")

# Full report
report = PlotReporter(analyzer).report()
report.model_dump_json()

# Visualization (pip install plot-finder[viz])
from plot_finder.visualizer import PlotVisualizer
viz = PlotVisualizer(report)
viz.save("map.html")  # interactive map
viz.save("map.png")   # static image

CLI

plot-finder analyze 141201_1.0001.6509 --radius 2000
plot-finder analyze 141201_1.0001.6509 --json
plot-finder search --address "Warszawa, Marszalkowska 1"
plot-finder elevation 141201_1.0001.6509
plot-finder climate 141201_1.0001.6509
plot-finder sunlight 141201_1.0001.6509
plot-finder noise 141201_1.0001.6509
plot-finder risks 141201_1.0001.6509
plot-finder places 141201_1.0001.6509 --category education

Documentation

Full documentation: ernestilchenko.github.io/plot-finder

License

MIT — use it however you want.