Adresy.app ID (AID) — stały identyfikator punktu adresowego

AID to 11-znakowy, stały, unikalny kod identyfikujący punkt adresowy w Polsce. Oparty na danych PRG (GUGiK) i kodach TERYT (GUS). Niezmienny przez całe życie punktu.

Co to jest adresy.app ID?

Adresy.app ID (AID) to stały, unikalny identyfikator każdego punktu adresowego w Polsce, nadawany przez serwis Adresy.app na podstawie danych PRG (Państwowy Rejestr Granic) GUGiK i kodów TERYT GUS.

AID jednoznacznie wskazuje konkretny budynek (wejście do budynku) w Polsce i pozostaje niezmieniony przez całe życie punktu — nawet jeśli zmieni się ulica, kod pocztowy czy nazwa miejscowości. Identyfikator nigdy nie jest reużywany: po usunięciu punktu z PRG jego AID przechodzi w stan „tombstone” i pozostaje zarezerwowany na zawsze.

Format — 11 znaków

AID to ciąg 11 małych liter i cyfr w alfabecie Crockford base32 (bez liter i, l, o, u, które łatwo pomylić):

1cpnk 000z8 4
└─┬─┘ └─┬─┘ └ znak kontrolny (Luhn mod 32)
  │     └ sekwencja punktu w gminie (5 znaków)
  └ kod TERYT gminy (7 cyfr) → base32 (5 znaków)
  • Prefiks gminy (5 zn.) — 7-cyfrowy kod TERYT (TERC) zakodowany w base32. Bezstratny: 325 = 33 554 432 > maks. kod TERYT 3 299 999.
  • Sekwencja (5 zn.) — monotoniczny licznik punktów w gminie; nigdy nie jest reużywany.
  • Znak kontrolny (1 zn.) — algorytm Luhn mod 32. Wyłapuje wszystkie pojedyncze błędy znaku i większość transpozycji sąsiadów.

Przykładowe AID: 1cpnk00001h (Kraków, punkt 1), 16jcz0001an (Warszawa, punkt 42), 07ywk00007t (Gdańsk, punkt 7).

Dlaczego warto używać AID?

  • Trwałość — AID nie zmienia się przy zmianie ulicy, kodu pocztowego ani nazwy miejscowości.
  • Unikalność — jeden AID = jeden punkt adresowy w Polsce, bez wyjątków.
  • Weryfikowalność — każdy AID można zwalidować lokalnie (checksum) bez połączenia z API.
  • Publiczny algorytm — format jest jawny; każda instytucja może samodzielnie implementować walidację i dekodowanie.
  • Czytelność — 11 znaków, łatwe do przepisania, bezpieczne w QR kodach i URL-ach.

Numer lokalu — format AID-lokal

PRG rejestruje wyłącznie punkty wejść do budynków — nie poszczególne lokale. Dlatego numer lokalu kodowany jest poza AID, po myślniku:

1cpnk000z84-5      → lokal 5
1cpnk000z84-12A    → lokal 12A
1cpnk000z84-P3     → lokal P3 (piwnica)
1cpnk000z84-U2     → lokal U2 (użytkowy)

Myślnik nie należy do alfabetu Crockford base32, więc podział jest zawsze jednoznaczny. Część AID (pierwsze 11 znaków) pozostaje w pełni walidowalna niezależnie od sufiksu lokalu.

Jak korzystać z AID?

Resolver punktu

Każdy AID ma stały URL:

https://id.adresy.app/<aid>          → strona punktu (HTML)
https://id.adresy.app/<aid>.json     → dane maszynowe (JSON)

API — walidacja i dekodowanie

GET /id/codec/validate?aid=1cpnk000z84
GET /id/codec/decode?aid=1cpnk000z84
GET /id/codec/encode?terc=1465011&seq=1000

Endpointy codec działają bez bazy danych — odpowiadają na podstawie samego algorytmu. Dostępne wersje wsadowe (POST, max 1000 elementów).

Dopasowanie adresu → AID

GET /id/api/encode?q=Kraków, Floriańska 1

Silnik matchingu Adresy.app dopasowuje tekst adresu do punktu PRG i zwraca jego AID.

Koder i dekoder online

Interaktywne narzędzie: id.adresy.app.

Samodzielne generowanie AID przez instytucje

Algorytm jest w pełni publiczny — TERYT jest danymi publicznymi GUS, a alfabet Crockford base32 i algorytm Luhn mod 32 są powszechnie znane. Instytucja posiadająca własne dane adresowe (np. z ewidencji gruntów i budynków — egib) może samodzielnie generować AID, stosując wzór:

AID = encode_aid(teryt_terc, własny_licznik_gminy)

Uwaga na kolizje: przestrzeń sekwencji jest współdzielona. Rejestr Adresy.app używa sekwencji 1–~150 000 na gminę (maks. PRG). Aby uniknąć kolizji z naszymi AID i AID innych instytucji, zalecamy koordynację zakresu sekwencji — napisz na [email protected]. Implementacje referencyjne (Python, JavaScript) dostępne w dokumentacji technicznej.