Metadata-Version: 2.4
Name: ruian-import
Version: 0.1.0
Summary: Download and parse Czech RUIAN (ČÚZK) data: municipalities, districts, and regions
Project-URL: Repository, https://gitlab.com/alexandra.tapkova/ruian-import
Author-email: Alexandra Ťapková <git@ouppy.space>
License: MIT
Keywords: cuzk,czech,gis,municipalities,ruian
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Provides-Extra: coordinates
Requires-Dist: pyproj>=3.4; extra == 'coordinates'
Provides-Extra: dev
Requires-Dist: pyproj>=3.4; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: responses; extra == 'dev'
Description-Content-Type: text/markdown

# ruian-import

Python knihovna pro stahování a parsování číselníků ČÚZK (RÚIAN): kraje, okresy a obce.

## Instalace

```bash
pip install ruian-import
# s podporou souřadnic (JTSK -> WGS84):
pip install "ruian-import[coordinates]"
```

## Použití

```python
from ruian_import import fetch_kraje, fetch_okresy, fetch_obce

kraje = fetch_kraje()   # list[Kraj]
okresy = fetch_okresy() # list[Okres]
obce = fetch_obce()     # list[Obec]
```

### Datové třídy

```python
@dataclass
class Kraj:
    kod: str          # např. "19"
    nazev: str        # např. "Hlavní město Praha"
    nuts_lau: str | None  # např. "CZ010"
    zrusen: str | None    # datum zrušení "YYYY-MM-DD" nebo None

@dataclass
class Okres:
    kod: str
    nazev: str
    kraj_kod: str
    nuts_lau: str | None
    zrusen: str | None

@dataclass
class Obec:
    kod: str          # 6místný kód obce, např. "554979"
    nazev: str
    okres_kod: str
    lat: float | None  # WGS84, dostupné jen s [coordinates]
    lon: float | None
    zrusen: str | None
```

Zrušené záznamy mají vyplněné pole `zrusen`; platné záznamy mají `zrusen = None`.

### Souřadnice obcí

`UI_OBEC.csv` souřadnice neobsahuje. Pro doplnění souřadnic použij `fetch_obce_with_coordinates()`, které provede druhý dotaz na ArcGIS REST API ČÚZK a vrátí centroidy polygonů (přesnost ~100 m, jeden HTTP request pro všechny obce):

```python
from ruian_import import fetch_obce_with_coordinates

obce = fetch_obce_with_coordinates()  # lat/lon vyplněné
```

Nebo načti souřadnice samostatně:

```python
from ruian_import import fetch_obec_coordinates

coords = fetch_obec_coordinates()  # dict[str, tuple[float, float]] - kod -> (lat, lon)
```

### Vlastní URL / lokální soubory

```python
from ruian_import._parse import parse_obce

data = Path("UI_OBEC.zip").read_bytes()
obce = parse_obce(data)
```

## Zdroje dat

Číselníky ČÚZK se aktualizují denně:

- **Kraje**: `https://services.cuzk.cz/sestavy/cis/UI_VUSC.zip`
- **Okresy**: `https://services.cuzk.cz/sestavy/cis/UI_OKRES.zip`
- **Obce**: `https://services.cuzk.cz/sestavy/cis/UI_OBEC.zip`

## Licence

MIT
