# PL-QGIS-Demografia

> **Wtyczka QGIS do automatycznej analizy demograficznej gmin i powiatów Polski**  
> *QGIS plugin for automated demographic analysis of Polish municipalities and counties*

[![QGIS](https://img.shields.io/badge/QGIS-3.22+-green)](https://qgis.org)
[![License: GPL v2](https://img.shields.io/badge/License-GPL_v2-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.9+-blue)](https://python.org)

---

## 🇵🇱 Polski

### Co robi wtyczka?

PL-QGIS-Demografia łączy dwa urzędowe źródła danych GIS w jednym kliknięciu:

- **GUS BDL** (Bank Danych Lokalnych) – pobiera wskaźniki demograficzne dla każdej gminy w Polsce
- **PRG GUGiK** (Państwowy Rejestr Granic) – ładuje granice administracyjne przez WFS

Wynik to gotowy **kartogram choropletowy** z automatycznym podziałem na klasy metodą Jenks Natural Breaks i paletą ColorBrewer Blues.

### Dostępne wskaźniki (13 zmiennych MVP)

| Wskaźnik | Źródło |
|----------|--------|
| Ludność ogółem | GUS BDL |
| Ludność – Mężczyźni / Kobiety | GUS BDL |
| Wskaźnik urbanizacji (%) | GUS BDL |
| Urodzenia żywe / Zgony (na 1000 osób) | GUS BDL |
| Przyrost naturalny | GUS BDL |
| Gospodarstwa domowe (ogółem, 1–4 osobowe) | GUS BDL |
| Współczynnik zmian struktury ludności | GUS BDL |

### Instalacja

**Metoda 1 – z pliku ZIP (zalecane):**

1. Pobierz najnowszy plik `pl_qgis_demografia_v1.0.0.zip` z [Releases](../../releases)
2. W QGIS: **Wtyczki → Zarządzaj wtyczkami → Zainstaluj z pliku ZIP**
3. Wskaż pobrany plik → Zainstaluj

**Metoda 2 – ręcznie:**

```bash
# Linux/macOS
unzip pl_qgis_demografia_v1.0.0.zip -d ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/

# Windows (PowerShell)
Expand-Archive pl_qgis_demografia_v1.0.0.zip "$env:APPDATA\QGIS\QGIS3\profiles\default\python\plugins\"
```

### Wymagania

- QGIS 3.22 lub nowszy
- Python 3.9+
- Pakiet `requests` (zazwyczaj dołączony do QGIS)
- Połączenie z Internetem (API GUS BDL + WFS GUGiK)

### Użytkowanie

1. Uruchom wtyczkę z paska narzędzi lub menu **Wtyczki → PL-QGIS-Demografia**
2. Wybierz wskaźnik demograficzny z listy
3. Wybierz rok analizy (2015–2023)
4. Opcjonalnie: ogranicz do województwa lub wklej klucz API GUS BDL
5. Kliknij **OK** – wtyczka pobierze dane i wygeneruje kartogram

> **Klucz API GUS BDL jest opcjonalny.** Bez niego obowiązuje limit 5 zapytań/sekundę,
> co wystarczy do normalnego użytkowania. Klucz uzyskasz bezpłatnie na
> [bdl.stat.gov.pl](https://bdl.stat.gov.pl/BDL/developer).

### Architektura techniczna

```
GUS BDL REST API ──► GUSClient (paginacja, backoff)
                          │
                    TERYTNormalizer (urban-rural split)
                          │
                     DBHandler (cache: SQLite 30 dni)
                          │
PRG WFS GUGiK ──────► WFSClient ──► DBHandler (GPKG 90 dni)
                          │
                   QgsVectorLayerJoinInfo (Table Join)
                          │
              QgsGraduatedSymbolRenderer (Jenks, Blues, 5 klas)
```

### Licencja

GNU General Public License v2.0 – szczegóły w pliku [LICENSE](LICENSE).

---

## 🇬🇧 English

### What does the plugin do?

PL-QGIS-Demografia connects two official Polish GIS data sources in a single click:

- **GUS BDL** (Local Data Bank) – fetches demographic indicators for every municipality in Poland
- **PRG GUGiK** (National Register of Boundaries) – loads administrative boundaries via WFS

The result is a ready-to-use **choropleth map** with automatic Jenks Natural Breaks classification and ColorBrewer Blues palette.

### Available indicators (13 MVP variables)

Population (total, male, female), Urbanisation rate, Live births, Deaths (per 1000), Natural increase, Households (total, 1–4 person), Population structure change coefficient.

### Installation

**Method 1 – from ZIP (recommended):**

1. Download the latest `pl_qgis_demografia_v1.0.0.zip` from [Releases](../../releases)
2. In QGIS: **Plugins → Manage and Install Plugins → Install from ZIP**
3. Select the downloaded file → Install

**Method 2 – manual:**

```bash
# Linux/macOS
unzip pl_qgis_demografia_v1.0.0.zip -d ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/

# Windows (PowerShell)
Expand-Archive pl_qgis_demografia_v1.0.0.zip "$env:APPDATA\QGIS\QGIS3\profiles\default\python\plugins\"
```

### Requirements

- QGIS 3.22 or newer
- Python 3.9+
- `requests` package (usually bundled with QGIS)
- Internet connection (GUS BDL API + GUGiK WFS)

### Usage

1. Launch the plugin from the toolbar or **Plugins → PL-QGIS-Demografia**
2. Select a demographic indicator
3. Select the analysis year (2015–2023)
4. Optionally: filter by voivodeship or enter a GUS BDL API key
5. Click **OK** – the plugin fetches data and generates the choropleth

> **GUS BDL API key is optional.** Without it, the rate limit is 5 req/s,
> sufficient for normal use. Get a free key at
> [bdl.stat.gov.pl](https://bdl.stat.gov.pl/BDL/developer).

### License

GNU General Public License v2.0 – see [LICENSE](LICENSE).

### Author

Mikołaj Matwiejuk  
University of Warmia and Mazuria in Olsztyn (UWM), Poland  
geoinformatykauwmmailroku@gmail.com

---

*Funded by: personal research project | Department of Geoinformatics, UWM Olsztyn*
