"""The UKE lists of radio permits for mobile base stations, Poland.
The Office of Electronic Communications (UKE) publishes every month, on dane.gov.pl under
CC BY 4.0, one spreadsheet per system and band ("LTE1800", "5G3600", ...) listing the
permitted base stations with their operator, station identifier and position. The lists
give no height, direction, power or frequency block, only the band. The adapter joins the
rows of one operator, station and position into one antenna with all its bands; each band
is registered as its whole 3GPP downlink range, so the operators on a band share one
channel. Lists of other services (GSM-R, CDMA and LTE at 420/450 MHz) are skipped. A
permit does not guarantee that the station is built, and the lists name few Plus
(Polkomtel) stations.
The newest monthly archive is found through the dane.gov.pl API, downloaded once and
converted to a local point index pinned by its date and SHA-256.
"""
from __future__ import annotations
import asyncio
import io
import re
import zipfile
from pathlib import Path
import httpx
import pyarrow as pa
from defusedxml.ElementTree import fromstring
from openworld_radio_twin.config import Settings
from openworld_radio_twin.models import AntennaFeature, FrequencyBand
from openworld_radio_twin.providers.base import AntennaProviderError, AntennaQueryResult
from openworld_radio_twin.providers.snapshots import (
Snapshot,
current_snapshot,
download,
install_snapshot,
query_bounds,
read_point_index,
source_cache_root,
)
TITLE = "UKE base-station permits"
ATTRIBUTION = "Urząd Komunikacji Elektronicznej (UKE), via dane.gov.pl"
LICENSE = "CC BY 4.0"
LICENSE_URL = "https://creativecommons.org/licenses/by/4.0/"
RESOURCES_API = "https://api.dane.gov.pl/1.4/datasets/1075/resources"
MAX_EXPORT_BYTES = 100_000_000
# Downlink range of each list's band in the European band plan (3GPP 28, 20, 8, 3, 1, 7, n78).
BANDS = {
"700": (758.0, 788.0),
"800": (791.0, 821.0),
"900": (925.0, 960.0),
"1800": (1805.0, 1880.0),
"2100": (2110.0, 2170.0),
"2600": (2620.0, 2690.0),
"3600": (3400.0, 3800.0),
}
RADIOS = {"GSM": "GSM", "UMTS": "UMTS", "LTE": "LTE", "5G": "NR"}
PLMN = {
"Polkomtel sp. z o.o.": "260-01",
"T-Mobile Polska S.A.": "260-02",
"Orange Polska S.A.": "260-03",
"P4 sp. z o.o.": "260-06",
}
SHEET = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
LIST_NAME = re.compile(r"^(GSM|UMTS|LTE|5G)(\d{3,4}) - stan na (\d{4}-\d{2}-\d{2})\.xlsx$")
DMS = re.compile(r"(\d+)([NSEW])(\d+)'(\d+(?:[.,]\d+)?)\"")
[docs]
def snapshot_directory(settings: Settings) -> Path:
return source_cache_root(settings) / "uke"
def _degrees(value: str) -> float:
match = DMS.fullmatch(value.strip())
if not match:
raise ValueError(f"unrecognised coordinate {value!r}")
degrees, hemisphere, minutes, seconds = match.groups()
number = int(degrees) + int(minutes) / 60 + float(seconds.replace(",", ".")) / 3600
return -number if hemisphere in {"S", "W"} else number
[docs]
def sheet_rows(content: bytes) -> list[dict[str, str]]:
"""The rows of a list's first sheet, keyed by the header row."""
workbook = zipfile.ZipFile(io.BytesIO(content))
shared = [
"".join(item.itertext())
for item in fromstring(workbook.read("xl/sharedStrings.xml")).iter(SHEET + "si")
]
rows = []
for row in fromstring(workbook.read("xl/worksheets/sheet1.xml")).iter(SHEET + "row"):
values = {}
for cell in row.iter(SHEET + "c"):
column = re.sub(r"\d", "", cell.get("r", ""))
value = cell.find(SHEET + "v")
text = value.text if value is not None else "".join(cell.itertext())
values[column] = shared[int(text)] if cell.get("t") == "s" else (text or "")
rows.append(values)
header, *data = rows
return [{header[column]: row.get(column, "") for column in header} for row in data]
[docs]
def read_export(path: Path) -> tuple[pa.Table, dict[str, object]]:
"""One row per operator, station and position, with its bands."""
stations: dict[tuple, dict] = {}
lists, skipped, dates = [], [], set()
with zipfile.ZipFile(path) as archive:
for name in archive.namelist():
match = LIST_NAME.match(Path(name).name)
if not match or match[2] not in BANDS:
skipped.append(Path(name).name)
continue
system, band, state = match.groups()
lists.append(f"{system}{band}")
dates.add(state)
low, high = BANDS[band]
for row in sheet_rows(archive.read(name)):
operator = row["Nazwa Operatora"].strip()
longitude = _degrees(row["Dł geogr stacji"])
latitude = _degrees(row["Szer geogr stacji"])
key = (operator, row["IdStacji"].strip(), round(latitude, 5), round(longitude, 5))
entry = stations.setdefault(
key,
{"town": row["Miejscowość"], "bands": {}, "radios": set(), "decisions": set()},
)
entry["bands"][f"{system} {band}"] = (low, high)
entry["radios"].add(RADIOS[system])
entry["decisions"].add(row["Nr Decyzji"])
if not stations:
raise ValueError("The UKE archive holds no base-station list")
rows = []
for (operator, station, latitude, longitude), entry in stations.items():
labels = sorted(entry["bands"])
rows.append(
{
"operator": operator,
"station": station,
"latitude": latitude,
"longitude": longitude,
"town": entry["town"],
"radios": sorted(entry["radios"]),
"band_label": labels,
"band_low_mhz": [entry["bands"][label][0] for label in labels],
"band_high_mhz": [entry["bands"][label][1] for label in labels],
"decisions": sorted(entry["decisions"]),
}
)
table = pa.Table.from_pylist(
rows,
schema=pa.schema(
[
("operator", pa.string()),
("station", pa.string()),
("latitude", pa.float64()),
("longitude", pa.float64()),
("town", pa.string()),
("radios", pa.list_(pa.string())),
("band_label", pa.list_(pa.string())),
("band_low_mhz", pa.list_(pa.float64())),
("band_high_mhz", pa.list_(pa.float64())),
("decisions", pa.list_(pa.string())),
]
),
)
return table, {"lists": sorted(lists), "skipped_lists": sorted(skipped), "state": sorted(dates)}
[docs]
def antenna_records(table: pa.Table, release: str) -> list[AntennaFeature]:
records = []
for row in table.to_pylist():
site = f"{row['latitude']:.5f},{row['longitude']:.5f}"
plmn = PLMN.get(row["operator"])
records.append(
AntennaFeature(
feature_id=f"uke:{plmn or row['operator']}:{row['station']}@{site}",
source="uke",
source_release=release,
site_id=f"uke-site:{site}",
operator=row["operator"],
plmn=plmn,
radios=row["radios"],
bands=[
FrequencyBand(label=label, low_mhz=low, high_mhz=high)
for label, low, high in zip(
row["band_label"], row["band_low_mhz"], row["band_high_mhz"], strict=True
)
],
latitude=row["latitude"],
longitude=row["longitude"],
basis={"position": "source", "bands": "source"},
source_attributes={
"station": row["station"],
"town": row["town"],
"decisions": row["decisions"],
},
)
)
return records
[docs]
async def latest_export(client: httpx.AsyncClient) -> tuple[str, str]:
"""Date and URL of the newest monthly archive."""
response = await client.get(
RESOURCES_API, params={"sort": "-data_date", "per_page": "5"}, timeout=60
)
response.raise_for_status()
for item in response.json().get("data", []):
attributes = item.get("attributes", {})
if attributes.get("format") == "zip" and attributes.get("file_url"):
return str(attributes["data_date"]), str(attributes["file_url"])
raise ValueError("The UKE dataset lists no archive")
[docs]
class UkeProvider:
def __init__(self, settings: Settings, client: httpx.AsyncClient):
self.settings = settings
self.client = client
self.directory = snapshot_directory(settings)
self._lock = asyncio.Lock()
[docs]
async def snapshot(self, *, refresh: bool = False) -> Snapshot:
"""The installed snapshot; downloads the newest archive first when none is installed."""
async with self._lock:
installed = current_snapshot(self.directory)
if installed is not None and not refresh:
return installed
path = self.directory / "wykazy.zip"
try:
release, url = await latest_export(self.client)
sha256 = await download(self.client, url, path, maximum_bytes=MAX_EXPORT_BYTES)
table, metadata = await asyncio.to_thread(read_export, path)
return await asyncio.to_thread(
install_snapshot,
self.directory,
table,
release=release,
sha256=sha256,
metadata={"source": "uke", "source_url": url, "license": LICENSE, **metadata},
)
except httpx.HTTPError as exc:
raise AntennaProviderError(f"UKE archive download failed: {exc}") from exc
except (OSError, KeyError, ValueError, zipfile.BadZipFile, pa.ArrowException) as exc:
raise AntennaProviderError(f"UKE archive could not be installed: {exc}") from exc
finally:
path.unlink(missing_ok=True)
[docs]
async def antennas(
self, latitude: float, longitude: float, radius_m: float
) -> AntennaQueryResult:
snapshot = await self.snapshot()
table = await asyncio.to_thread(
read_point_index, snapshot.index, *query_bounds(latitude, longitude, radius_m)
)
records = await asyncio.to_thread(antenna_records, table, snapshot.identity)
warnings = (
[
"UKE lists give the band only, so each band is its whole downlink range and "
"the operators on it share one channel; select an operator to separate them. "
"A permit does not guarantee a built station, and the lists name few Plus "
"(Polkomtel) stations."
]
if records
else []
)
return AntennaQueryResult(
antennas=records, provider=TITLE, release=snapshot.identity, warnings=warnings
)