Metadata-Version: 2.4
Name: plot-finder
Version: 0.2.0
Summary: Query Polish ULDK (GUGiK) API to find land parcels by TERYT ID or coordinates
Author: Ernest Ilchenko
License-Expression: MIT
Project-URL: Homepage, https://github.com/ernestilchenko/plot-finder
Project-URL: Documentation, https://ernestilchenko.github.io/plot-finder/
Keywords: uldk,gugik,parcel,plot,geodesy,poland,teryt
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.24
Requires-Dist: shapely>=2.0
Requires-Dist: pyproj>=3.6
Requires-Dist: astral>=3.2
Provides-Extra: viz
Requires-Dist: folium>=0.14; extra == "viz"
Requires-Dist: Pillow>=9.0; extra == "viz"
Provides-Extra: ai
Requires-Dist: openai>=1.0; extra == "ai"
Dynamic: license-file

# plot-finder

![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)
![Pydantic](https://img.shields.io/badge/Pydantic-v2-E92063?logo=pydantic&logoColor=white)
![OpenStreetMap](https://img.shields.io/badge/OpenStreetMap-7EBC6F?logo=openstreetmap&logoColor=white)
![OSRM](https://img.shields.io/badge/OSRM-Routing-blue)
![OpenWeather](https://img.shields.io/badge/OpenWeather-API-orange?logo=openweathermap&logoColor=white)
![Open-Meteo](https://img.shields.io/badge/Open--Meteo-Climate-1a73e8)

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

Query the [ULDK (GUGiK)](https://uldk.gugik.gov.pl/) API to get parcel data by TERYT ID or coordinates, then analyze nearby infrastructure using OpenStreetMap.

![Plot with geometry, radius and nearby places](assets/showcase.png)

## Installation

```bash
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

```python
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](docs/plot.md) | Finding parcels by TERYT ID or coordinates |
| [PlotAnalyzer](docs/analyzer.md) | Analyzing surroundings (education, shops, transport, etc.) |
| [Climate](docs/climate.md) | Temperature, precipitation, wind, frost/hot days (Open-Meteo) |
| [Air Quality](docs/air.md) | Air pollution data (OpenWeatherMap API) |
| [Sunlight](docs/sun.md) | Sunrise, sunset, daylight hours |
| [Place](docs/place.md) | Result model with travel times |
| [Report](docs/report.md) | Full structured report (PlotReporter) |
| [Visualizer](docs/visualizer.md) | Interactive HTML maps & static PNG images |
| [AI](docs/ai.md) | AI-powered plot analysis (OpenAI) |
| [API Reference](docs/api.md) | Full API reference |
| [Errors](docs/errors.md) | Exception handling and hierarchy |

## License

MIT — use it however you want.
