plot-finder 0.1.0

Query Polish ULDK (GUGiK) API to find land parcels by TERYT ID or coordinates

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, walk {place.walk_min}min")

# 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

Documentation

Page	Description
Plot	Finding parcels by TERYT ID or coordinates
PlotAnalyzer	Analyzing surroundings (education, shops, transport, etc.)
Climate	Temperature, precipitation, wind, frost/hot days (Open-Meteo)
Air Quality	Air pollution data (OpenWeatherMap API)
Sunlight	Sunrise, sunset, daylight hours
Place	Result model with travel times
Report	Full structured report (PlotReporter)
Visualizer	Interactive HTML maps & static PNG images
AI	AI-powered plot analysis (OpenAI)
API Reference	Full API reference
Errors	Exception handling and hierarchy

License

MIT — use it however you want.