Site selection with scenarios

A scenario packages everything an expert checks for one asset type (zoning, constraints, grid, terrain, transport) into one call. This guide finds battery-storage sites in Wielkopolskie.

Pick the criteria

Start from the matching entry in the scenario catalogue. For battery storage (bess_storage) that is: no blocking zone, available grid capacity near a substation, no environmental risk nearby, and a gentle slope, ranked mostly by available capacity.

Run it on a region

Find the region's TERYT code with GET /regions?q=wielkopolskie (→ 30), then express the criteria as filters, tightened to a 20 MW project:

curl https://api.zonio.tech/v1/search/parcels \
  -H "Authorization: Bearer $ZONIO_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "region": "30",
    "filters": {
      "area_sqm": { "min": 2000 },
      "slope_pct": { "max": 15 },
      "near": [
        { "layer": "grid_capacity", "within_m": 3000, "where": { "available_mw_gte": 20 } },
        { "layer": "power_substations", "within_m": 5000, "where": { "voltage_kv_gte": 110 } }
      ],
      "exclude": [{ "layer": "env_layers", "kinds": ["natura2000", "flood_risk_1pct"], "buffer_m": 100 }]
    },
    "rank_by": [
      { "signal": "grid_capacity_mw", "weight": 70 },
      { "signal": "grid_distance_km", "weight": 20 },
      { "signal": "area", "weight": 10 }
    ],
    "limit": 25
  }'

Agents get the same result in one step: the find_sites MCP tool applies a scenario by name, and plain-language search picks one from a sentence like "sites for a 20 MW BESS in Wielkopolskie".

Read the ranking

{
  "count": 25,
  "blocked": false,
  "coverage": [
    { "criterion": "grid_capacity_available", "mode": "requires", "status": "available" },
    { "criterion": "no_env_risk_nearby", "mode": "screens", "status": "available" },
    { "criterion": "slope_within_tolerance", "mode": "screens", "status": "partial" }
  ],
  "results": [
    {
      "parcel_id": "3064011_1.0021.88/4",
      "area_sqm": 6120,
      "gmina": "Poznań",
      "score": 97,
      "components": [
        { "signal": "grid_capacity_mw", "value": 46, "contribution": 70 },
        { "signal": "grid_distance_km", "value": 0.8, "contribution": 18.4 },
        { "signal": "area", "value": 6120, "contribution": 8.6 }
      ]
    }
  ]
}

Scores are relative (0–100 within this result set) and components shows exactly how each was earned, so you can explain the ranking to a user or an investment committee.

Check the coverage

slope_within_tolerance is partial here: terrain statistics are not yet available for every parcel in the region, so some results were not screened on slope. Show that to your user. If a requires criterion is missing, the search returns blocked: true and no results, rather than an empty list that looks like "no sites exist".

Drill into the shortlist

Take the top results into due diligence or ask your agent to compare_parcels.

Build your own screen

POST /search/parcels is not limited to the catalogue: any combination of area, zoning, slope, vacancy, near and exclude clauses over any layer, plus your own ranking weights. See the API reference.