API Reference¶

Full reference for all public classes, methods, and exceptions.

Plot¶

Plot(*, plot_id=None, address=None, x=None, y=None, srid=2180)

Fetch parcel data from the ULDK API. Provide plot_id (TERYT ID), address (street address), or both x and y.

Parameter	Type	Default	Description
`plot_id`	`str \\| None`	`None`	TERYT parcel ID
`address`	`str \\| None`	`None`	Street address (geocoded via Nominatim)
`x`	`float \\| None`	`None`	X coordinate
`y`	`float \\| None`	`None`	Y coordinate
`srid`	`int`	`2180`	Coordinate reference system

Raises: PlotNotFoundError, ULDKError, GeocodeError, AddressNotFoundError

PlotAnalyzer¶

PlotAnalyzer(plot, *, radius=1000, openweather_api_key=None)

Create an analyzer for a Plot.

Parameter	Type	Default	Description
`plot`	`Plot`	required	Plot to analyze
`radius`	`int`	`1000`	Default search radius in meters
`openweather_api_key`	`str \\| None`	`None`	API key for air quality data

Methods¶

All place methods return list[Place] sorted by distance. All accept an optional radius: int parameter.

`all_places(radius=None)`¶

All categories in a single Overpass query. Returns dict[str, list[Place]].

`education(radius=None)`¶

Schools, kindergartens, universities, colleges.

`finance(radius=None)`¶

ATMs, banks.

`transport(radius=None)`¶

Bus stops, tram stops, train stations, airports, ferry terminals.

`infrastructure(radius=None)`¶

Supermarkets, convenience stores, malls, pharmacies, hospitals, clinics, doctors, dentists, post offices, fuel stations, police, fire stations, places of worship, restaurants, cafes.

`green_areas(radius=None)`¶

Parks, gardens, nature reserves, playgrounds, forests, woodlands.

`water(radius=None)`¶

Rivers, lakes, ponds, reservoirs, streams, canals.

`nuisances(radius=None)`¶

Power lines, transformers, industrial zones, factories.

Raises: NothingFoundError, OverpassError, OverpassTimeoutError, OverpassRateLimitError

`climate() -> Climate`¶

Historical climate data (last 365 days). Uses Open-Meteo Archive API — no API key needed.

Raises: OpenMeteoError

`elevation() -> Elevation`¶

Elevation, slope, and aspect. Uses Open-Meteo Elevation API — no API key needed.

Raises: OpenMeteoError

`air_quality() -> AirQuality`¶

Current air pollution data. Requires openweather_api_key.

Raises: OpenWeatherAuthError, OpenWeatherError

`sunlight(for_date=None) -> SunInfo`¶

Sun data (sunrise, sunset, daylight hours, golden hour, shadow length). No API key needed.

Parameter	Type	Default	Description
`for_date`	`date \\| None`	`None`	Date to calculate for (default: today)

`sunlight_seasonal() -> SeasonalSun`¶

Sun data for all four seasonal reference dates (summer/winter solstice, spring/autumn equinox).

`noise(voivodeship=None) -> Noise`¶

Noise level from GDDKiA strategic noise maps, with OSM fallback estimation.

Parameter	Type	Default	Description
`voivodeship`	`str \\| None`	`None`	Override voivodeship (default: from plot data)

`risks() -> RiskReport`¶

Environmental and geological risk assessment (flood, seismic, soil, landslide, noise, mining).

`mpzp() -> MPZP`¶

Local spatial development plan data from Geoportal. Requires pip install plot-finder[geo].

`suikzp() -> SUIKZP`¶

Study of Conditions and Directions of Spatial Development from Geoportal.

`pog() -> POG`¶

General Municipal Plan (adopted or projected) from Geoportal.

Async API¶

`create_plot_async`¶

plot = await create_plot_async(plot_id=None, address=None, x=None, y=None)

Async factory — same parameters as Plot(...), returns a Plot.

Raises: PlotNotFoundError, ULDKError, GeocodeError, AddressNotFoundError

`AsyncPlotAnalyzer`¶

async with AsyncPlotAnalyzer(plot, *, radius=1000, openweather_api_key=None) as analyzer:
    ...

Async context manager. Same methods as PlotAnalyzer — all async except sunlight() and sunlight_seasonal().

`AsyncPlotReporter`¶

report = await AsyncPlotReporter(analyzer).report(for_date=None)

Runs all analyses concurrently. Returns PlotReport.

See Async API docs for full details and performance benchmarks.

AirQuality¶

Pydantic BaseModel returned by air_quality().

Field	Type	Description
`aqi`	`int`	Air Quality Index (1-5)
`aqi_label`	`str`	Good / Fair / Moderate / Poor / Very Poor
`co`	`float`	Carbon monoxide (ug/m3)
`no`	`float`	Nitrogen monoxide (ug/m3)
`no2`	`float`	Nitrogen dioxide (ug/m3)
`o3`	`float`	Ozone (ug/m3)
`so2`	`float`	Sulphur dioxide (ug/m3)
`pm2_5`	`float`	Fine particulate matter (ug/m3)
`pm10`	`float`	Coarse particulate matter (ug/m3)
`nh3`	`float`	Ammonia (ug/m3)

Climate¶

Pydantic BaseModel returned by climate().

Field	Type	Description
`avg_temp`	`float \\| None`	Average daily temperature (°C)
`max_temp`	`float \\| None`	Highest recorded temperature (°C)
`min_temp`	`float \\| None`	Lowest recorded temperature (°C)
`total_precipitation_mm`	`float \\| None`	Total precipitation (mm)
`total_rain_mm`	`float \\| None`	Total rain (mm)
`total_snow_cm`	`float \\| None`	Total snowfall (cm)
`sunshine_hours`	`float \\| None`	Total sunshine hours
`avg_wind_speed`	`float \\| None`	Average daily max wind speed (km/h)
`max_wind_speed`	`float \\| None`	Highest recorded wind speed (km/h)
`frost_days`	`int \\| None`	Days with min temp below 0°C
`hot_days`	`int \\| None`	Days with max temp above 30°C
`rainy_days`	`int \\| None`	Days with rain > 0.1mm
`snow_days`	`int \\| None`	Days with snowfall > 0cm

Elevation¶

Pydantic BaseModel returned by elevation().

Field	Type	Description
`elevation_m`	`float`	Meters above sea level
`slope_deg`	`float \\| None`	Terrain slope (degrees)
`aspect`	`str \\| None`	Compass direction (N, NE, E, SE, S, SW, W, NW, flat)
`aspect_deg`	`float \\| None`	Aspect in degrees (0=N, 90=E, 180=S, 270=W)

SunInfo¶

Pydantic BaseModel returned by sunlight().

Field	Type	Description
`date`	`str`	Date (ISO format)
`dawn`	`time`	Civil dawn
`sunrise`	`time`	Sunrise
`solar_noon`	`time`	Solar noon
`sunset`	`time`	Sunset
`dusk`	`time`	Civil dusk
`daylight_hours`	`float`	Hours of daylight
`sun_elevation`	`float`	Current sun elevation (degrees)
`sun_azimuth`	`float`	Current sun azimuth (degrees)
`golden_hour_morning`	`time \\| None`	End of morning golden hour
`golden_hour_evening`	`time \\| None`	Start of evening golden hour
`shadow_length_10m`	`float \\| None`	Shadow length (m) for 10m object at noon

SeasonalSun¶

Pydantic BaseModel returned by sunlight_seasonal().

Field	Type	Description
`summer_solstice`	`SunInfo`	June 21
`winter_solstice`	`SunInfo`	December 21
`spring_equinox`	`SunInfo`	March 20
`autumn_equinox`	`SunInfo`	September 22

Noise¶

Pydantic BaseModel returned by noise().

Field	Type	Description
`noise_level_db`	`float`	Noise level in dB
`quality`	`str`	Polish quality label
`level`	`str`	English level key
`description`	`str`	Polish description
`color`	`str`	Indicator color
`sources`	`list[NoiseSource]`	Detected sources
`data_source`	`str`	Data origin

NoiseSource¶

Field	Type	Description
`type`	`str`	Source type
`name`	`str`	Source name
`distance_km`	`float`	Distance (km)
`impact_db`	`float`	Noise impact (dB)
`lat`	`float`	Latitude
`lon`	`float`	Longitude

RiskReport¶

Pydantic BaseModel returned by risks().

Field	Type	Description
`risks`	`list[RiskInfo]`	Detected risks
`total_risks`	`int`	Count

RiskInfo¶

Field	Type	Description
`risk_type`	`str`	flood / seismic / soil / landslide / noise / mining
`name`	`str`	Polish name
`level`	`str`	low / medium / high / unknown
`is_at_risk`	`bool`	Whether affected
`description`	`str`	Polish description
`color`	`str`	Indicator color

MPZP¶

Pydantic BaseModel returned by mpzp(). Requires pip install plot-finder[geo].

Field	Type	Description
`has_plan`	`bool`	Whether MPZP exists
`zone_symbol`	`str \\| None`	Zone symbol
`zone_name`	`str \\| None`	Zone description
`plan_name`	`str \\| None`	Plan name
`resolution`	`str \\| None`	Resolution number
`resolution_date`	`str \\| None`	Resolution date
`publication`	`str \\| None`	Publication reference
`effective_date`	`str \\| None`	Effective date
`wms_url`	`str \\| None`	WMS map URL

SUIKZP¶

Pydantic BaseModel returned by suikzp().

Field	Type	Description
`has_plan`	`bool`	Whether Studium exists
`plan_name`	`str \\| None`	Full plan name
`resolution`	`str \\| None`	Resolution number
`resolution_date`	`str \\| None`	Adoption date
`plan_type`	`str \\| None`	Document type
`legend_url`	`str \\| None`	Legend image URL
`document_url`	`str \\| None`	Resolution document URL
`wms_url`	`str \\| None`	WMS map URL

POG¶

Pydantic BaseModel returned by pog().

Field	Type	Description
`has_plan`	`bool`	Whether POG exists
`plan_name`	`str \\| None`	Plan title
`valid_from`	`str \\| None`	Validity date
`document_url`	`str \\| None`	Legal act URL
`is_draft`	`bool`	Whether this is a projected/draft plan
`zones`	`list[PlanZone]`	Planning zones
`infill_area`	`bool`	Building infill area
`downtown_area`	`bool`	Downtown development area
`wms_url`	`str \\| None`	WMS map URL

PlanZone¶

Field	Type	Description
`designation`	`str \\| None`	Zone designation (e.g. "63SW")
`symbol`	`str \\| None`	Zone type code (e.g. "SW")
`symbol_name`	`str \\| None`	Human-readable zone name
`valid_from`	`str \\| None`	Zone validity date
`max_building_intensity`	`float \\| None`	Max building intensity
`max_building_coverage_pct`	`float \\| None`	Max building coverage (%)
`max_building_height_m`	`float \\| None`	Max building height (m)
`min_bio_active_pct`	`float \\| None`	Min biologically active surface (%)

GugikEntry¶

Pydantic BaseModel returned by Plot.gugik(). Requires pip install plot-finder[geo].

Field	Type	Description
`organ`	`str`	Authority name
`nazwa`	`str`	Dataset name
`wms`	`str \\| None`	WMS URL
`wfs`	`str \\| None`	WFS URL

Place¶

Pydantic BaseModel returned by all analyzer methods.

Field	Type	Description
`name`	`str \\| None`	Place name from OSM
`kind`	`str`	Type identifier
`lat`	`float`	Latitude (WGS84)
`lon`	`float`	Longitude (WGS84)
`distance_m`	`float`	Straight-line distance (m)

PlotReport¶

Pydantic BaseModel returned by PlotReporter.report().

Field	Type	Default	Description
`plot_id`	`str`	—	TERYT parcel ID
`lat`	`float`	—	Centroid latitude (WGS84)
`lon`	`float`	—	Centroid longitude (WGS84)
`radius`	`int`	—	Search radius in meters
`education`	`list[Place]`	`[]`	Schools, kindergartens, universities
`finance`	`list[Place]`	`[]`	ATMs, banks
`transport`	`list[Place]`	`[]`	Bus stops, stations, airports
`infrastructure`	`list[Place]`	`[]`	Shops, healthcare, services
`green_areas`	`list[Place]`	`[]`	Parks, gardens, forests
`water`	`list[Place]`	`[]`	Rivers, lakes, ponds
`nuisances`	`list[Place]`	`[]`	Power lines, industrial zones, factories
`air_quality`	`AirQuality \\| None`	`None`	Air pollution data
`climate`	`Climate \\| None`	`None`	Temperature, precipitation, wind (last 365 days)
`elevation`	`Elevation \\| None`	`None`	Elevation, slope, and aspect
`sunlight`	`SunInfo \\| None`	`None`	Sun position and daylight
`seasonal_sun`	`SeasonalSun \\| None`	`None`	Seasonal sun data (4 dates)
`noise`	`Noise \\| None`	`None`	Noise level data
`risks`	`RiskReport \\| None`	`None`	Environmental risk assessment
`mpzp`	`MPZP \\| None`	`None`	Local spatial development plan
`suikzp`	`SUIKZP \\| None`	`None`	Study of conditions and directions
`pog`	`POG \\| None`	`None`	General municipal plan
`gugik`	`list[GugikEntry] \\| None`	`None`	GUGiK integration data

PlotReporter¶

PlotReporter(analyzer)

Parameter	Type	Description
`analyzer`	`PlotAnalyzer`	Analyzer to collect data from

Methods¶

`report(for_date=None) -> PlotReport`¶

Runs all analyzer methods. Catches NothingFoundError per category, skips air quality if no API key.

PlotVisualizer¶

from plot_finder.visualizer import PlotVisualizer — requires pip install plot-finder[viz]

PlotVisualizer(report, *, colors=None, plot_color="red")

Parameter	Type	Default	Description
`report`	`PlotReport`	required	Report to visualize
`colors`	`dict[str, str] \\| None`	`None`	Override category colours
`plot_color`	`str`	`"red"`	Centre marker and radius circle colour

Methods¶

`map() -> folium.Map`¶

Interactive HTML map with markers, radius circle, and layer control. Requires folium.

`image(width=800, height=600, zoom=None, marker_radius=6) -> PIL.Image.Image`¶

Static map image from OpenStreetMap tiles. Requires Pillow.

`save(path)`¶

Auto-detects by extension: .png/.jpg → static image, .html → interactive map.

PlotAI¶

from plot_finder.ai import PlotAI — requires pip install plot-finder[ai]

PlotAI(report, *, api_key, model="gpt-4o-mini")

Parameter	Type	Default	Description
`report`	`PlotReport`	required	Report to analyze
`api_key`	`str`	required	OpenAI API key
`model`	`str`	`"gpt-4o-mini"`	OpenAI model to use

Methods¶

All methods return str.

`summary()`¶

Natural language summary of the plot and surroundings.

`rate(purpose="living")`¶

Rate the plot 1–10 for a purpose (living / investment / farming) with explanation.

`advantages()`¶

Key advantages of this location.

`disadvantages()`¶

Key disadvantages and risks.

`ask(question)`¶

Freeform Q&A about the plot.

Exceptions¶

Exception	Parent	Description
`ULDKError`	`Exception`	Base ULDK API error
`PlotNotFoundError`	`ULDKError`	Parcel not found
`NothingFoundError`	`Exception`	No results in radius
`OverpassError`	`Exception`	Base Overpass API error
`OverpassTimeoutError`	`OverpassError`	Overpass timeout
`OverpassRateLimitError`	`OverpassError`	Overpass rate limit (429)
`OpenWeatherError`	`Exception`	Base OpenWeatherMap error
`OpenWeatherAuthError`	`OpenWeatherError`	Missing/invalid API key
`OpenMeteoError`	`Exception`	Open-Meteo API error
`GeoportalError`	`Exception`	Geoportal WMS/WFS error
`GDDKiAError`	`Exception`	GDDKiA noise map error
`SOPOError`	`Exception`	PIG-PIB SOPO landslide error
`GugikError`	`Exception`	GUGiK integration error
`GeocodeError`	`Exception`	Base Nominatim geocoding error
`AddressNotFoundError`	`GeocodeError`	No results for address

CLI¶

pip install plot-finder

All commands support --json for machine-readable output.

Command	Description
`plot-finder analyze <id> [--radius N] [--json]`	Full report
`plot-finder search --address "..." [--json]`	Find plot by address
`plot-finder search --plot-id <id> [--json]`	Find plot by TERYT ID
`plot-finder places <id> [--radius N] [--category C]`	Nearby places
`plot-finder elevation <id>`	Elevation, slope, aspect
`plot-finder climate <id>`	Climate (last 365 days)
`plot-finder sunlight <id> [--date YYYY-MM-DD]`	Sunrise, sunset, daylight
`plot-finder noise <id>`	Noise level
`plot-finder risks <id>`	Environmental risks

Also available as python -m plot_finder <command> ...

API Reference¶

Plot¶

PlotAnalyzer¶

Methods¶

all_places(radius=None)¶

education(radius=None)¶

finance(radius=None)¶

transport(radius=None)¶

infrastructure(radius=None)¶

green_areas(radius=None)¶

water(radius=None)¶

nuisances(radius=None)¶

climate() -> Climate¶

elevation() -> Elevation¶

air_quality() -> AirQuality¶

sunlight(for_date=None) -> SunInfo¶

sunlight_seasonal() -> SeasonalSun¶

noise(voivodeship=None) -> Noise¶

risks() -> RiskReport¶

mpzp() -> MPZP¶

suikzp() -> SUIKZP¶

pog() -> POG¶

Async API¶

create_plot_async¶

AsyncPlotAnalyzer¶

AsyncPlotReporter¶

AirQuality¶

Climate¶

Elevation¶

SunInfo¶

SeasonalSun¶

Noise¶

NoiseSource¶

RiskReport¶

RiskInfo¶

MPZP¶

SUIKZP¶

POG¶

PlanZone¶

GugikEntry¶

Place¶

PlotReport¶

PlotReporter¶

Methods¶

report(for_date=None) -> PlotReport¶

PlotVisualizer¶

Methods¶

map() -> folium.Map¶

image(width=800, height=600, zoom=None, marker_radius=6) -> PIL.Image.Image¶

save(path)¶

PlotAI¶

Methods¶

summary()¶

rate(purpose="living")¶

advantages()¶

disadvantages()¶

ask(question)¶

Exceptions¶

CLI¶

`all_places(radius=None)`¶

`education(radius=None)`¶

`finance(radius=None)`¶

`transport(radius=None)`¶

`infrastructure(radius=None)`¶

`green_areas(radius=None)`¶

`water(radius=None)`¶

`nuisances(radius=None)`¶

`climate() -> Climate`¶

`elevation() -> Elevation`¶

`air_quality() -> AirQuality`¶

`sunlight(for_date=None) -> SunInfo`¶

`sunlight_seasonal() -> SeasonalSun`¶

`noise(voivodeship=None) -> Noise`¶

`risks() -> RiskReport`¶

`mpzp() -> MPZP`¶

`suikzp() -> SUIKZP`¶

`pog() -> POG`¶

`create_plot_async`¶

`AsyncPlotAnalyzer`¶

`AsyncPlotReporter`¶

`report(for_date=None) -> PlotReport`¶

`map() -> folium.Map`¶

`image(width=800, height=600, zoom=None, marker_radius=6) -> PIL.Image.Image`¶

`save(path)`¶

`summary()`¶

`rate(purpose="living")`¶

`advantages()`¶

`disadvantages()`¶

`ask(question)`¶