Polska ma własny system identyfikacji miejsca. Każde województwo, powiat, gmina, miejscowość i ulica mają swój kod w rejestrze TERYT. Powiat starachowicki, gmina Starachowice, konkretna ulica — wszystko ma numer w państwowym rejestrze.
Kiedy ktoś w juz-ide wpisuje adres zamieszkania, pierwszym krokiem weryfikacji jest pytanie: czy ten adres istnieje w TERYT?
Dlaczego oficjalny rejestr, nie mapy komercyjne
Mogłem użyć Google Maps API albo OpenStreetMap. Mają dobre dane adresowe, dobre API, znane interfejsy.
Wybrałem TERYT z jednego powodu: cel weryfikacji jest administracyjny, nie nawigacyjny.
Chcę wiedzieć, czy adres istnieje jako jednostka podziału terytorialnego Polski — tam, gdzie byłoby zameldowanie, gdzie są rejestry gminne, gdzie mieszkańcy mają prawne powiązanie z miejscem.
Google Maps zna kafejki i parkingi. TERYT zna gminy i numery posesji. Do weryfikacji zamieszkania potrzebuję drugiego.
Dwa poziomy weryfikacji
Tier 1 — istnienie adresu w Polsce: Czy podana ulica, numer i miejscowość tworzą zarejestrowany adres w TERYT? To łapie literówki, fikcyjne adresy, pomyłki w nazwie ulicy.
Tier 2 — przynależność do gminy: Czy ten adres należy do tej konkretnej gminy? juz-ide wymaga, żeby użytkownik był w strefie obsługi. Adres może istnieć w Polsce, ale poza gminą — Tier 2 to wyłapuje.
Późniejsze poziomy (Tier 3+) to weryfikacja przez instytucje lokalne — spółdzielnię, urząd — ale to już poza zakresem integracji TERYT.
Jak wygląda integracja
GUS udostępnia dane TERYT na kilka sposobów: pliki XML do pobrania, API SOAP (tak, SOAP w 2025), i nowsze REST-owe interfejsy w fazie wdrożenia.
Wybrałem podejście hybrydowe: lokalna kopia najważniejszych danych (pobierana raz na kwartał, gminy i miejscowości). Tam, gdzie trzeba sprawdzić konkretny numer budynku, sięgam już do państwowego rejestru adresów punktowych (GUGiK PRG) — bo to on, nie TERYT, zna adresy „do drzwi”. Z czasem to właśnie PRG stał się główną podstawą weryfikacji geograficznej.
Dlaczego lokalnie? Państwowe API mają limity zapytań i nie zawsze są dostępne z zerowym opóźnieniem. Dla setek weryfikacji dziennie — lokalna kopia gminy i ulic jest szybsza i niezawodna.
I jeszcze jedno, czego nauczyłem się boleśnie później: na oficjalnych kodach też można się przejechać. Pierwsza wersja moich danych miała wpisany zły kod powiatu — pomyliłem dwa sąsiednie powiaty województwa świętokrzyskiego o podobnych nazwach. „Autorytatywne źródło” nie chroni przed własną literówką przy przepisywaniu. Błąd siedział w migracji miesiącami, zanim go wyłapałem.
Mapa → weryfikacja → zaufanie
juz-ide to produkt o lokalnym zaufaniu. „Ten sąsiad naprawdę jest stąd” — to coś, co chcę móc powiedzieć z konkretną podstawą.
TERYT daje pierwszy stopień tej podstawy: adres fizycznie istnieje. To nie jest pełna weryfikacja. Ktoś może wpisać adres sąsiada, nie swój. Ale eliminuje fikcyjne adresy, losowe wpisy, próby podszywania się pod inne miejscowości.
Bo za każdym sprawdzonym adresem stoi prawdziwy człowiek, który mieszka kilka ulic dalej — ktoś, kogo pewnego dnia mógłbyś spotkać na żywo. I to jego, nie rekordu w bazie, próbuję tu nie zgubić.
Budowanie na danych państwowych to też decyzja polityczna: korzystam z infrastruktury, którą opłaca podatnik (w tym ja i moi potencjalni użytkownicy). To ma sens dla aplikacji, która chce być częścią lokalnej społeczności, nie kolejną platformą ekstrakcji danych.