Spis PNA — dokumentacja API

Części spisu

Każda część ma inną strukturę kolumn, więc jest osobną tabelą. Część 4, jednostki organizacyjne Poczty Polskiej, nie jest załadowana.

Część	Ścieżka	Co zawiera
1. Miejscowości i ulice	`/v1/addresses`	Kod, miejscowość, ulica, zakres numerów, gmina, powiat, województwo.
2. Podmioty z odrębnym PNA	`/v1/institutions`	64 kody należące do instytucji, na przykład banków i oddziałów ZUS.
3. Placówki Poczty Polskiej	`/v1/facilities`	Urzędy pocztowe oraz kody skrytek i przegródek.

Wielkość liter i polskie znaki w filtrach nie mają znaczenia: Krakow znajduje Kraków. limit domyślnie wynosi 50, najwyżej 200.

Zasady zapytań

locality=Kraków obejmuje też Kraków (Kraków-Śródmieście). Pełna nazwa z dzielnicą w nawiasie zostawia tylko tę dzielnicę.
Pusta komórka numbers oznacza, że kod obejmuje całą ulicę. Pusta ulica i puste numery oznaczają całą miejscowość.
Gdy miejscowość jest podzielona na ulice, numer domu bez ulicy zwraca błąd 400.
Rekordy oznaczone przy parsowaniu jako „do sprawdzenia” są w wynikach z needsReview: true.
Nieznany kod w formacie 00-000 zwraca 404. Zły format zwraca 400.

Wypróbuj

Miejscowość Ulica Numer

Wynik pojawi się tutaj.

GET /v1/lookup

Kod pocztowy dla adresu. Parametry: locality (wymagany), street, number, oraz limit i offset, gdy nie podano numeru.

GET /v1/lookup?locality=Kraków&street=Grzegórzecka&number=50

match mówi, skąd wzięło się dopasowanie: numbers (numer mieści się w zakresie), street (cała ulica ma jeden kod) albo locality (cała miejscowość ma jeden kod). uncertain zawiera wiersze tej ulicy, których zapisu numerów nie udało się odczytać.

GET /v1/postal-codes/{kod}

Wszystkie rekordy z podanym kodem, z trzech części naraz: addresses, facilities i institutions.

GET /v1/postal-codes/31-559
GET /v1/postal-codes/00-923

Listy

GET /v1/addresses

Filtry: pna, locality, street, commune, county, voivodeship, q (dowolny fragment, co najmniej 2 znaki), review (1 tylko do sprawdzenia, 0 tylko zgodne), limit, offset.

GET /v1/facilities

Filtry: pna, locality, name, street, entryType (facility albo po_boxes dla skrytek i przegródek), facilityType (FUP, UP, AP), q, limit, offset.

GET /v1/institutions

Filtry: pna, locality, name, q, limit, offset.

GET /v1/stats

Liczba rekordów w każdej części i liczba rekordów do sprawdzenia.

GET /v1/voivodeships

Województwa wraz z liczbą adresów.

GET /v1

Ta sama lista endpointów w JSON, dla programów.

Invoke-RestMethod "http://127.0.0.1:3000/v1/lookup?locality=Kraków&street=Grzegórzecka&number=50"

Numery domów

Zakres w kolumnie numbers jest listą odcinków rozdzielonych przecinkami.

Zapis	Znaczenie
`(n)` / `(p)`	Strona nieparzysta albo parzysta. Liczy się liczba, więc `5a` jest nieparzyste.
`50-DK(p)`	Każdy parzysty numer od 50 w górę. `DK` oznacza brak górnej granicy.
`2-2b`	Litera jest po gołym numerze: `2 < 2a < 2b < 3`.
`38/52`	Jeden adres. Zapytanie o `38` go znajduje, zapytanie o `52` nie.
`1/3-75(n)`	Nieparzyste od 1 do 75. W zakresie liczy się liczba przed ukośnikiem.
`17-22/24`	Numery od 17 do 22. `22/24` pasuje jako adres końcowy, `24` samo nie.

Pola odpowiedzi

Nazwy pól są po angielsku. Adres ma pna, locality, street, numbers, commune, county, voivodeship. Placówka ma dodatkowo name, number, entryType i facilityType. Podmiot ma name, number i group.

Każdy rekord ma needsReview oraz source.record i source.pdfPage, czyli identyfikator i stronę w pliku PDF. Listy zwracają total, limit, offset i data.