TERYT (Teryt)¶

Ostatnia aktualizacja dokumentacji: 2026-02-26 Stan synchronizacji z kodem: ✅ Zsynchronizowany

Polski rejestr adresowy — hierarchiczne dane o województwach, powiatach, gminach i miejscowościach.

Co to jest?¶

Domena TERYT integruje system z Krajowym Rejestrem Urzędowym Podziału Terytorialnego Kraju. To jak oficjalna mapa administracyjna Polski — zawiera wszystkie województwa, powiaty, gminy i miejscowości z ich oficjalnymi kodami. Dzięki temu adresy w systemie są zgodne z rejestrem państwowym.

System obsługuje: - 16 województw - ~380 powiatów - Tysiące gmin - Dziesiątki tysięcy miejscowości - Hierarchiczne wyszukiwanie

Jakie problemy rozwiązuje?¶

Kluczowe funkcjonalności¶

Dla użytkownika¶

Architektura domeny¶

Modele danych¶

Terc (app/Domain/TERYT/Model/Terc.php)¶

Model reprezentuje jednostkę terytorialną (województwo, powiat, gmina) z rejestru TERC.

• Tabela: terc
• Klucz główny: klucz kompozytowy ['woj', 'pow', 'gmi', 'rodz'] (brak auto-increment)
• Timestamps: brak
• Observer: TercObserver (pusty — szkielet)
• Fillable: woj, pow, gmi, rodz, nazwa, nazdod, stan_na

Logika wyróżniania poziomów hierarchii (przez filtrowanie):

Simc (app/Domain/TERYT/Model/Simc.php)¶

Model reprezentuje miejscowość z rejestru SIMC.

• Tabela: simc
• Klucz główny: sym (char 7, brak auto-increment)
• Timestamps: brak
• Observer: SimcObserver (pusty — szkielet)
• Fillable: woj, pow, gmi, rodz_gmi, rm, mz, nazwa, sym, sympod, stan_na
• Indeksy: simc_woj_index (woj), simc_pow_index (pow), simc_gmi_index (gmi)

Diagram relacji¶

flowchart TD
    A[Województwo\nTerc: pow=00, gmi=00] --> B[Powiat\nTerc: pow!=00, gmi=00]
    B --> C[Gmina\nTerc: gmi!=00]
    C --> D[Miejscowość\nSimc: sym PK]
    D --> D2[Miejscowość nadrzędna\nSimc: sympod]

Enum typów gminy (TERYTEnumService)¶

app/Domain/TERYT/Service/TERYTEnumService.php

API Endpoints¶

Wszystkie endpointy są publiczne (bez autoryzacji). Cała logika TERYT jest obsługiwana przez jeden parametryzowany endpoint:

Jeden endpoint — wiele poziomów¶

GET /api/no-auth/teryt/{provinceId?}/{districtId?}/{provinceName?}/{districtName?}/{cityName?}/{tercId?}/{cityId?}

Klasa: Domain\TERYT\Controller\TERYTController::run() Action: Domain\TERYT\Action\Controller\RunTERYTController Form Request: RunTerytControllerRequest

Endpoint dynamicznie dobiera poziom szczegółowości na podstawie podanych parametrów ścieżki:

Walidacja parametrów (RunTerytControllerRequest)¶

Poziom 1: Lista województw¶

GET /api/no-auth/teryt

Zapytanie DB: Terc gdzie pow = '00' AND gmi = '00', sortowanie po nazwa.

Odpowiedź (TerytVoivodeshipResource):

[
  {
    "provinceId": "02",
    "districtId": null,
    "communeId": null,
    "communeTypeId": null,
    "provinceName": null,
    "districtName": null,
    "communeName": null,
    "communeTypeName": null,
    "statusDate": "2025-01-01",
    "tercId": null,
    "name": "DOLNOŚLĄSKIE",
    "typeName": "województwo"
  },
  {
    "provinceId": "14",
    "districtId": null,
    "communeId": null,
    "communeTypeId": null,
    "provinceName": null,
    "districtName": null,
    "communeName": null,
    "communeTypeName": null,
    "statusDate": "2025-01-01",
    "tercId": null,
    "name": "WARMIŃSKO-MAZURSKIE",
    "typeName": "województwo"
  }
]

Poziom 2: Lista powiatów¶

GET /api/no-auth/teryt/{provinceId}

Przykład: /api/no-auth/teryt/14

Zapytanie DB: Terc gdzie woj = provinceId AND pow != '00' AND gmi = '00', sortowanie po nazwa.

Odpowiedź (TerytDistrictResource):

[
  {
    "provinceId": "14",
    "districtId": "01",
    "communeId": null,
    "communeTypeId": null,
    "provinceName": null,
    "districtName": null,
    "communeName": null,
    "communeTypeName": null,
    "statusDate": "2025-01-01",
    "tercId": null,
    "name": "bartoszycki",
    "typeName": "powiat"
  }
]

Poziom 3: Lista gmin¶

GET /api/no-auth/teryt/{provinceId}/{districtId}

Przykład: /api/no-auth/teryt/14/12

Zapytanie DB: Terc gdzie woj = provinceId AND pow = districtId AND gmi != '00', sortowanie po nazwa.

Odpowiedź (TerytCommuneResource):

[
  {
    "provinceId": "14",
    "districtId": "12",
    "communeId": "05",
    "communeTypeId": "2",
    "communeTypeIdLang": null,
    "provinceName": null,
    "districtName": null,
    "communeName": null,
    "communeTypeName": null,
    "statusDate": "2025-01-01",
    "tercId": 14120520,
    "name": "Olsztynek",
    "typeName": "gmina wiejska"
  }
]

Budowa tercId: konkatenacja woj + pow + gmi + rodz rzutowana na int.

Poziom 4: Lista miejscowości w gminie¶

GET /api/no-auth/teryt/{provinceId}/{districtId}/{provinceName}/{districtName}/{cityName}

Przykład: /api/no-auth/teryt/14/12/warmińsko-mazurskie/olsztyński/olsztynek

Wyszukiwanie: case-insensitive (używa LOWER(nazwa) = ? przez whereRaw). Przekazywane nazwy mogą być w dowolnej wielkości liter.

Logika zapytania (TERYTCommuneCities): 1. Znajdź województwo: LOWER(nazwa) = voivodeshipName AND pow = '00' AND gmi = '00' 2. Znajdź powiat: LOWER(nazwa) = districtName AND woj = woj_z_kroku_1 AND gmi = '00' AND pow != '00' 3. Znajdź gminę: LOWER(nazwa) = communeName AND woj/pow z poprzednich kroków AND gmi != '00' 4. Pobierz miejscowości z SIMC: - Jeśli commune.rodz === '3' (gmina miejsko-wiejska): rodz_gmi IN ('4', '5') - W pozostałych przypadkach: rodz_gmi = commune.rodz 5. Sortowanie po nazwa

Odpowiedź (TerytCityResource):

[
  {
    "provinceId": "14",
    "districtId": "12",
    "communeId": "05",
    "communeTypeId": "5",
    "provinceName": "WARMIŃSKO-MAZURSKIE",
    "districtName": "olsztyński",
    "communeName": "Olsztynek",
    "communeTypeName": null,
    "statusDate": "2025-01-01",
    "tercId": 14120552,
    "cityName": "Jemiołowo",
    "cityId": "0231483"
  }
]

Logika biznesowa¶

Normalizacja kodów (TerytNormalizeCode)¶

app/Domain/TERYT\Action\Other\TerytNormalizeCode.php

Codes imported from CSV are padded with leading zeros to the expected length:

terytNormalizeCode("2", 2)  → "02"
terytNormalizeCode("",  7)  → "0000000"
terytNormalizeCode(null, 2) → "00"

Parametry: value (string|null), length (int, domyślnie 2).

Reguły wyszukiwania miejscowości dla gmin miejsko-wiejskich¶

Gmina rodz = '3' (miejsko-wiejska) zawiera dwa składniki w SIMC: - rodz_gmi = '4' — miasto (część miejska gminy) - rodz_gmi = '5' — obszar wiejski (część wiejska gminy)

Dlatego zapytanie używa whereIn('rodz_gmi', ['4', '5']) — zamiast filtrowania po rodz_gmi = '3'.

Jak to działa?¶

Hierarchia terytorialna¶

flowchart TD
    A[Województwo] --> B[Powiat]
    B --> C[Gmina]
    C --> D[Miejscowość]

Przykład¶

WARMIŃSKO-MAZURSKIE (woj)
  └── olsztyński (pow)
       └── Olsztynek (gmi)
            └── Jemiołowo (miejscowość)

Caching¶

Dane TERYT są w całości cache'owane przez Redis/Cache z TTL = 86400 sekund (1 dzień).

Import danych¶

Komenda importu¶

php artisan teryt:import

Klasa: Domain\TERYT\Command\ImportTerytCommand Sygnatura: teryt:import Opis: Import TERYT data from csv

Komenda deleguje logikę do ImportTerytCmd (action), która: 1. Ustawia memory_limit = -1 (import dużych plików CSV) 2. Importuje TERC z storage/app/public/teryt/terc.csv 3. Importuje SIMC z storage/app/public/teryt/simc.csv 4. Uruchamia czyszczenie zbędnych wartości

Źródła danych¶

Separator CSV: ;. Kodowanie: UTF-8.

Proces importu¶

flowchart TD
    A[php artisan teryt:import] --> B[Ustaw memory_limit=-1]
    B --> C[TerytImportTerc\nUsuń wszystkie rekordy TERC]
    C --> D[Wczytaj terc.csv wiersz po wierszu\nInsert z normalizacją kodów]
    D --> E[TerytImportSimc\nUsuń wszystkie rekordy SIMC]
    E --> F[Wczytaj simc.csv wiersz po wierszu\nInsert z normalizacją kodów]
    F --> G[TerytDeleteUnnecessaryValues]
    G --> H[Usuń z TERC: rodz IN 4,5,8,9]
    H --> I[Usuń z SIMC: rodz_gmi IN 8,9]
    I --> J[Usuń duplikaty SIMC\nsame woj+pow+gmi+rodz_gmi+nazwa, wyższy sym]
    J --> K[Import zakończony]

Szczegóły TerytImportTerc¶

• Usuwa wszystkie rekordy z tabeli terc (DB::table('terc')->delete())
• Odczytuje CSV linia po linii, pomija nagłówek
• Pomija wiersze z mniej niż 7 kolumnami
• Normalizuje kody za pomocą TerytNormalizeCode: woj (2 znaki), pow (2 znaki), gmi (2 znaki), rodz (1 znak)
• Puste wartości nazdod zapisuje jako null

Szczegóły TerytImportSimc¶

• Usuwa wszystkie rekordy z tabeli simc (DB::table('simc')->delete())
• Pomija wiersze z mniej niż 10 kolumnami
• Normalizuje kody: woj (2), pow (2), gmi (2), rodz_gmi (1), rm (2), mz (2), sym (7), sympod (7 lub null)

Szczegóły TerytDeleteUnnecessaryValues¶

• TERC: Usuwa rekordy z rodz IN [4, 5, 8, 9] — czyli: Miasto w gminie miejsko-wiejskiej, Obszar wiejski, Dzielnica Warszawy, Delegatura
• SIMC: Usuwa rekordy z rodz_gmi IN [8, 9] — Dzielnica Warszawy, Delegatura
• Deduplikacja SIMC: SQL JOIN na samej sobie — dla rekordów z identycznym woj+pow+gmi+rodz_gmi+nazwa usuwa ten z wyższym sym (zachowuje starszy wpis)

Obserwatory (Observers)¶

Oba obserwatory są przypisane przez atrybut #[ObservedBy(...)] i mogą być rozszerzone w przyszłości.

Powiązania z innymi domenami¶

Przechowywanie adresu w modelach powiązanych¶

Modele Client, Organization, Item przechowują dane adresowe jako pola:

Przykład teryt_data:

{
  "provinceId": "14",
  "districtId": "12",
  "communeId": "05",
  "cityId": "0231483",
  "tercId": 14120520
}

Uprawnienia¶

Struktura danych TERC (tabela bazy)¶

Struktura danych SIMC (tabela bazy)¶

Statystyki danych¶

Wartość biznesowa¶

Aktualizacja danych¶

Źródło oficjalne¶

Dane TERYT pochodzą z Głównego Urzędu Statystycznego (GUS): - https://eteryt.stat.gov.pl

Harmonogram aktualizacji¶

Procedura aktualizacji¶

1. Pobierz nowe pliki CSV z GUS
2. Umieść w storage/app/public/teryt/
3. Uruchom php artisan teryt:import
4. Wyczyść cache: php artisan cache:clear

Best practices¶

Znane ograniczenia¶

• communeTypeName w odpowiedzi jest zawsze null (niezaimplementowane w TerytCityResource)
• communeTypeIdLang w gminie jest wypełniane tylko dla typów rodz > 3; dla standardowych gmin (1–3) zwraca null
• Obserwatory TercObserver i SimcObserver są puste — nie rejestrują żadnej aktywności (logOptions logOnly([]))