Metadata-Version: 2.4
Name: ruian-import
Version: 0.2.2
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 library for downloading and parsing ČÚZK (RÚIAN) registries: regions, districts, and municipalities.

## Installation

```bash
pip install ruian-import
# with coordinate support (S-JTSK -> WGS84):
pip install "ruian-import[coordinates]"
```

## Usage

```python
from ruian_import import fetch_regions, fetch_districts, fetch_municipalities

regions = fetch_regions()             # list[Region]
districts = fetch_districts()         # list[District]
municipalities = fetch_municipalities() # list[Municipality]
```

### Data classes

```python
@dataclass
class Region:
    code: str              # e.g. "19"
    name: str              # e.g. "Hlavní město Praha"
    nuts_lau: str | None   # e.g. "CZ010"
    abolished: str | None  # abolishment date "YYYY-MM-DD", or None if active

@dataclass
class District:
    code: str
    name: str
    region_code: str
    nuts_lau: str | None
    abolished: str | None

@dataclass
class Municipality:
    code: str              # 6-digit municipality code, e.g. "554979"
    name: str
    district_code: str
    lat: float | None      # WGS84, only available with [coordinates]
    lon: float | None
    abolished: str | None
```

Abolished records have `abolished` set to a date string; active records have `abolished = None`.

### Municipality coordinates

`UI_OBEC.csv` does not include coordinates. Use `fetch_municipalities_with_coordinates()` to make a second request to the ČÚZK ArcGIS REST API and return polygon centroids (accuracy ~100 m, one HTTP request for all municipalities):

```python
from ruian_import import fetch_municipalities_with_coordinates

municipalities = fetch_municipalities_with_coordinates()  # lat/lon populated
```

Or fetch coordinates separately:

```python
from ruian_import import fetch_municipality_coordinates

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

### Custom URL / local files

```python
from ruian_import._parse import parse_municipalities

data = Path("UI_OBEC.zip").read_bytes()
municipalities = parse_municipalities(data)
```

## Data sources

ČÚZK registries are updated daily:

- **Regions**: `https://services.cuzk.cz/sestavy/cis/UI_VUSC.zip`
- **Districts**: `https://services.cuzk.cz/sestavy/cis/UI_OKRES.zip`
- **Municipalities**: `https://services.cuzk.cz/sestavy/cis/UI_OBEC.zip`

## License

MIT
