Core concepts

Parcels and parcel ids

A parcel (działka ewidencyjna) is the unit of land ownership in the national cadastre, EGiB. Zonio holds all ~38.7 M of them; see the cadastral parcels layer on zonio.tech. Each has a nationally unique id:

126101_1.0018.AR_1.100/1
└──┬───┘ └┬─┘ └─┬─┘ └─┬─┘
   │      │     │     └ parcel number (may contain "/")
   │      │     └ map sheet (optional)
   │      └ cadastral precinct (obręb)
   └ cadastral unit (jednostka ewidencyjna, TERYT-based)

Because parcel numbers contain /, URL-encode it in paths: 100/1 → 100%2F1. In JSON bodies, send the id as-is.

Regions and TERYT codes

Poland has 16 voivodeships (województwa), 380 powiats and ~2,477 gminas. Every one of them has its own page on the Zonio national map. Every unit has a TERYT code: 2 digits for a voivodeship, 4 for a powiat, 7 for a gmina. Wherever the API takes a region, pass a TERYT code. Gmina names repeat across the country (there are several Ostrów), so resolve names with GET /regions or let the natural-language search do it for you.

Planning instruments

Instrument	What it is	In the API
MPZP (miejscowy plan zagospodarowania przestrzennego)	The binding local zoning plan. Covers roughly a third of Poland. Defines zones (e.g. `MN` single-family, `MW` multi-family, `U` services, `P` production) and parameters such as max height and coverage.	`regulations.mpzp`
Plan Ogólny	The new general plan every gmina must adopt. It replaces the Studium and gates development permits outside an MPZP. What it changes.	`regulations.plan_ogolny`
Studium	The legacy, non-binding directional study. Still informative where no Plan Ogólny exists yet.	`regulations.studium`
WZ (warunki zabudowy)	A case-by-case building permit outside an MPZP.	inferred via Plan Ogólny zone

Zone symbols are not standardised between gminas. Zonio maps every raw symbol to a common category (residential_single_family, industrial, renewable_energy, …) and keeps the original symbol, so you can filter nationally and still show the user the exact legal designation.

Constraints

A constraint is anything that limits what can be built: Natura 2000 and other protected areas, flood-risk zones, heritage protection, mining areas, aviation obstacle limitation surfaces, groundwater protection zones, statutory wind-turbine setbacks, forest land. Each is reported with a severity: blocking, restrictive or informational.

Coverage

Not every public dataset covers all of Poland. Local plans are published by each gmina; some layers are only available for some regions. Zonio never treats "no data" as "no constraint". Every search and report returns a coverage block that tells you, criterion by criterion, whether it was checked:

"coverage": [
  { "criterion": "zone_residential", "mode": "requires", "status": "available" },
  { "criterion": "no_env_risk_nearby", "mode": "screens", "status": "available" },
  { "criterion": "not_contaminated", "mode": "screens", "status": "missing" }
]

requires criteria with missing data block the search (blocked: true) rather than returning nothing. screens criteria with missing data still return results, flagged as unscreened. Agents are instructed to tell users about every missing criterion. See Coverage & freshness.

Coordinates

Purpose	CRS	Where you see it
Storage and every calculation	EPSG:2180 (PUWG 1992)	distances, areas, buffers, always metres
Wire format	EPSG:4326 (WGS84)	all GeoJSON, all `lng`/`lat` inputs and outputs
Rendering	EPSG:3857	inside vector tiles only

You send and receive WGS84. Zonio measures in metres on Poland's national grid, where scale error stays below 0.1 % country-wide. Degree-based buffers would under-reach east–west by 34–42 % at Polish latitudes.

Scenarios

A scenario is a named, tunable site-selection screen (solar_farm_site, bess_storage, housing_estate_site) made of hard filters (all must pass), parameters with sensible defaults (e.g. max distance to a substation) and ranking signals with default weights. See the scenario catalogue.