zip-codes-pl 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f093d90a449c54edbdfe6298dd0d3d480ac666eaefb25daad255d9ce6f86877
+  data.tar.gz: 0b3ccc8540f608eb8f8c6cce891dc0d75fa62cf52e11ee2f166984d53760f7d1
+SHA512:
+  metadata.gz: 07ebb11afbc3b7a95663a5fabc6e23946c31862e3441aa3d0ab2122e67ce4527c90c79f88549bb9a2ceb453d254c21720fbfcf0f5d56e34db65148ee068706ef
+  data.tar.gz: 89ffefe6ec7f2c9e41061b5960e71b5cfda91b2484aae3e92eeb0547a34ce0bb2a2583d8c9991519625711acedbaf8aa38bb9c5372055ba189fa25839e4d334b

data/LICENSE.txt

@@ -0,0 +1,27 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Łukasz Kerl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The dataset this gem builds is derived from GeoNames (https://www.geonames.org),
+licensed under Creative Commons Attribution 4.0. Redistributing a built dataset
+requires crediting GeoNames.

data/README.md

@@ -0,0 +1,204 @@
+# zip-codes-pl
+
+Polish postal codes, places and voivodeships **with coordinates**, built and
+refreshed by a single rake task.
+
+*(Dokumentacja po polsku: [README.pl.md](README.pl.md))*
+
+**The dataset ships with the gem, so there is nothing to build before first
+use.** A rake task refreshes it into a directory of your choosing, asking the
+server with `If-None-Match` so a repeated run downloads nothing when the source
+has not changed. Your refreshed copy takes precedence over the bundled one.
+
+The dataset holds **72,899 rows**, **20,299 postal codes** and **52,325 places**
+across 16 voivodeships, as a 6.6 MB tab separated file. Lookups scan the file
+without building an index or retaining the whole dataset in memory.
+
+## Why this exists
+
+GeoNames is an excellent source of Polish postal codes and coordinates, and a
+poor source of Polish *names*. It labels all sixteen voivodeships in English and
+inconsistently - `Lower Silesia`, `Warmia-Masuria`, `Łódź Voivodeship` - which is
+not something you can put in front of a Polish user.
+
+This gem carries its own verified table of the sixteen voivodeships, mapped onto
+the official **TERYT** codes used by Polish public administration, and replaces
+the upstream labels with it. The TERYT county and commune codes that GeoNames
+does carry are passed through, so the result joins cleanly against any other
+Polish register.
+
+## Installation
+
+```ruby
+gem "zip-codes-pl"
+```
+
+## Refreshing the dataset
+
+GeoNames republishes daily. To pick up a newer extract than the one bundled with
+your installed version:
+
+```bash
+rake zip_codes:pl:update            # into the default directory (data/)
+rake zip_codes:pl:update[db/pna]    # into a directory you choose
+rake zip_codes:pl:info[db/pna]      # what is built, and when
+```
+
+When the GeoNames extract has changed, the build fetches county and commune
+names by TERYT code from the public Poczta Polska search.
+Requests are sequential and spaced by at least 0.25 seconds by default; a `429`
+response delays the next request according to `Retry-After`. A full enrichment
+currently takes about five minutes. Poczta Polska is not queried after a
+`304 Not Modified` response from GeoNames.
+
+In a Rails application a railtie loads the tasks for you. Elsewhere, add one
+line to your `Rakefile`:
+
+```ruby
+load Gem::Specification.find_by_name("zip-codes-pl").gem_dir + "/lib/zip_codes/pl/tasks/zip_codes_pl.rake"
+```
+
+The output directory can also be set once:
+
+```ruby
+ZipCodes::PL.configure do |config|
+  config.output_dir = Rails.root.join("db/pna").to_s
+  config.poczta_request_interval = 0.5 # optionally go even slower
+end
+```
+
+or through the `ZIP_CODES_PL_DIR` environment variable. Reads look there first
+and fall back to the bundled dataset, so configuring a directory that has not
+been refreshed yet changes nothing.
+
+## Usage
+
+```ruby
+ZipCodes::PL.find_by_postal_code("86-010")   # "86010" works too
+# => [#<data ZipCodes::PL::Record postal_code="86-010", city="Koronowo", ...>, ...]
+
+ZipCodes::PL.find_by_city("zlotow")          # case and diacritics insensitive
+ZipCodes::PL.find_by_city("Koronowo", voivodeship: "kujawsko-pomorskie")
+ZipCodes::PL.search_by_city("wie")           # name fragment, e.g. "Nowa Wieś"
+ZipCodes::PL.search_by_city("OS")            # exactly "Oś"
+
+ZipCodes::PL.voivodeships
+# => 16 records: TERYT code, Polish name, ASCII slug
+```
+
+Fragment searches ignore case and Polish diacritics. Queries of three or more
+characters behave like `%LIKE%`; a two-character query only matches a complete
+name, so the shortest place, `Oś`, remains searchable. One-character queries
+return an empty result without scanning the file.
+
+One record is one postal code in one place. A town with several codes has
+several records, and so does a code shared by several villages - `86-010` covers
+42 places around Koronowo.
+
+When you want **places rather than codes**, there is a ready aggregation:
+
+```ruby
+ZipCodes::PL.cities.first
+# => #<data ZipCodes::PL::City
+#      name="Abisynia", voivodeship="pomorskie", voivodeship_teryt="22",
+#      commune="Karsin", commune_teryt="220603",
+#      latitude=53.9244, longitude=17.9337, postal_codes=["83-440"]>
+```
+
+A place's coordinate is the mean of its rows, because the source gives one point
+per postal code and Bydgoszcz has 679 of them.
+
+Places are identified by name **and commune**, not by name alone. Poland has 119
+villages called `Nowa Wieś`, 28 of them in a single voivodeship; collapsing them
+by name puts the resulting point in a field up to 158 km from the farthest one.
+
+### Importing into a database
+
+Raw records can be imported in batches without loading the entire file:
+
+```ruby
+ZipCodes::PL.each_record.each_slice(1000) do |batch|
+  PostalCode.upsert_all(batch.map(&:to_h))
+end
+```
+
+Or import the aggregated places:
+
+```ruby
+ZipCodes::PL.cities.each_slice(1000) do |batch|
+  City.upsert_all(
+    batch.map do |city|
+      { name: city.name, province: city.voivodeship,
+        latitude: city.latitude, longitude: city.longitude }
+    end,
+    unique_by: %i[name province]
+  )
+end
+```
+
+## File format
+
+`zip-codes-pl.tsv` - tab separated with a header row, next to
+`zip-codes-pl.manifest.json` holding the source ETag, build time and row count.
+It is left uncompressed on purpose: the file is committed, and a refresh should
+produce a reviewable diff rather than a fresh opaque blob.
+
+| column | example | note |
+|---|---|---|
+| `postal_code` | `86-010` | |
+| `city` | `Nowa Wieś Wielka` | |
+| `voivodeship` | `kujawsko-pomorskie` | from this gem, not from the source |
+| `voivodeship_teryt` | `04` | official TERYT code |
+| `county` / `county_teryt` | `powiat bydgoski` / `0403` | Poczta Polska name joined by TERYT code |
+| `commune` / `commune_teryt` | `Koronowo` / `040304` | Poczta Polska name joined by TERYT code |
+| `latitude` / `longitude` | `53.3123` / `17.9539` | WGS84 |
+| `accuracy` | `6` | as reported by the source - see below |
+
+The file is written to a temporary path and renamed. A GeoNames download,
+Poczta Polska response, parsing or validation failure leaves the previous TSV
+and manifest unchanged.
+
+## What this gem does not pretend to do
+
+**These are postal-code centroids, not surveyed points.** GeoNames derives many
+of them algorithmically from place names, and falls back to an average of
+neighbouring postal codes where no match is found. They are good enough to sort
+by distance or draw on a map; they are not property-grade coordinates. The
+`accuracy` column is a source field, and for Poland it is currently `6` on all
+72,899 rows, so it carries no usable signal.
+
+**This is a postal dataset, not the official place register.** It covers places
+that have a postal code in the GeoNames extract, under GeoNames' spelling. The
+official Polish register (TERYT SIMC) is larger and authoritative on names; the
+gap between the two has not been measured here.
+
+**Administrative names are normalized by TERYT code.** The gem carries its own
+table for the 16 voivodeships and fetches current county and commune names from
+Poczta Polska during a refresh. The one explicit exception is historical code
+`320304` for the former Ostrowice commune, abolished on 1 January 2019, which is
+still present in GeoNames. **The `*_teryt` columns remain the dependable
+identifiers**, not the names.
+
+There are no streets or building numbers here, and this is not an address
+geocoder. For address-level lookups Poland has a free official service at
+`services.gugik.gov.pl/uug`.
+
+## Development
+
+```bash
+bin/setup        # or: bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+The test suite never touches the network: the source archive is generated in
+memory and the HTTP transport is exercised against stubbed responses.
+
+## Source and licence
+
+Postal data and coordinates come from [GeoNames](https://www.geonames.org)
+under **CC BY 4.0**. County and commune names are fetched from the public
+[Poczta Polska search](https://www.poczta-polska.pl/znajdz-kod-pocztowy/).
+The manifest carries a ready attribution string.
+
+The code is MIT licensed.

data/README.pl.md

@@ -0,0 +1,179 @@
+# zip-codes-pl
+
+*(English documentation: [README.md](README.md))*
+
+Polskie kody pocztowe, miejscowości i województwa **ze współrzędnymi**, budowane
+i odświeżane jednym zadaniem rake.
+
+**Zbiór jedzie razem z gemem, więc nie trzeba niczego budować przed pierwszym
+użyciem.** Zadanie rake odświeża go do wskazanego katalogu, pytając serwer
+nagłówkiem `If-None-Match`, więc powtórne uruchomienie nie pobiera ani bajta,
+kiedy źródło się nie zmieniło. Twoja odświeżona kopia ma pierwszeństwo przed
+tą z gema.
+
+Zbiór to **72 899 wierszy**, **20 299 kodów pocztowych** i **52 325
+miejscowości** w 16 województwach, w pliku TSV o rozmiarze 6,6 MB. Wyszukiwanie
+skanuje plik bez budowania indeksu i bez trzymania całego zbioru w pamięci.
+
+## Instalacja
+
+```ruby
+gem "zip-codes-pl"
+```
+
+## Odświeżanie zbioru
+
+GeoNames publikuje codziennie. Żeby wziąć nowszy zrzut niż ten w twojej wersji:
+
+```bash
+rake zip_codes:pl:update            # do katalogu domyślnego (data/)
+rake zip_codes:pl:update[db/pna]    # do wskazanego katalogu
+rake zip_codes:pl:info[db/pna]      # co jest zbudowane i z kiedy
+```
+
+Kiedy zrzut GeoNames się zmienił, build dociąga z publicznej wyszukiwarki
+Poczty Polskiej nazwy powiatów i gmin po kodach TERYT.
+Zapytania idą sekwencyjnie, domyślnie nie częściej niż co 0,25 s; odpowiedź
+`429` wstrzymuje kolejne zapytanie zgodnie z `Retry-After`. Pełne wzbogacenie
+zajmuje obecnie około pięciu minut. Przy odpowiedzi `304 Not Modified` Poczta
+Polska nie jest odpytywana.
+
+W aplikacji Rails zadanie podpina się samo przez railtie. Poza Railsami dodaj do
+swojego `Rakefile`:
+
+```ruby
+load Gem::Specification.find_by_name("zip-codes-pl").gem_dir + "/lib/zip_codes/pl/tasks/zip_codes_pl.rake"
+```
+
+Katalog wyjściowy ustawia się też na stałe:
+
+```ruby
+ZipCodes::PL.configure do |config|
+  config.output_dir = Rails.root.join("db/pna").to_s
+  config.poczta_request_interval = 0.5 # opcjonalnie jeszcze wolniej
+end
+```
+
+albo zmienną `ZIP_CODES_PL_DIR`. Odczyt najpierw zagląda tam, a w razie braku
+pliku sięga po zbiór z gema - ustawienie katalogu, którego jeszcze nie
+odświeżyłeś, niczego nie psuje.
+
+## Użycie
+
+```ruby
+ZipCodes::PL.find_by_postal_code("86-010")   # działa też "86010"
+# => [#<data ZipCodes::PL::Record postal_code="86-010", city="Koronowo", ...>, ...]
+
+ZipCodes::PL.find_by_city("zlotow")          # bez ogonków i wielkości liter
+ZipCodes::PL.find_by_city("Koronowo", voivodeship: "kujawsko-pomorskie")
+ZipCodes::PL.search_by_city("wie")           # fragment nazwy, np. "Nowa Wieś"
+ZipCodes::PL.search_by_city("OS")            # dokładnie "Oś"
+
+ZipCodes::PL.voivodeships
+# => 16 rekordów: kod TERYT, nazwa, slug bez polskich znaków
+```
+
+Wyszukiwanie fragmentu ignoruje wielkość liter i polskie znaki. Od trzech
+znaków działa jak `%LIKE%`; dwuznakowa fraza dopasowuje tylko całą nazwę, dzięki
+czemu nadal można znaleźć najkrótszą miejscowość „Oś”. Jednoznakowe zapytania
+zwracają pusty wynik bez skanowania pliku.
+
+Jeden rekord to jeden kod pocztowy w jednej miejscowości. Miejscowość z kilkoma
+kodami ma kilka rekordów, tak samo kod dzielony przez kilka wsi - `86-010` to
+42 miejscowości wokół Koronowa.
+
+Kiedy potrzebujesz **miejscowości, a nie kodów**, jest gotowa agregacja:
+
+```ruby
+ZipCodes::PL.cities.first
+# => #<data ZipCodes::PL::City
+#      name="Abisynia", voivodeship="pomorskie", voivodeship_teryt="22",
+#      commune="Karsin", commune_teryt="220603",
+#      latitude=53.9244, longitude=17.9337, postal_codes=["83-440"]>
+```
+
+Współrzędne miejscowości to średnia z jej wierszy, bo źródło daje punkt na kod
+pocztowy, a Bydgoszcz ma ich 679.
+
+Miejscowość jest identyfikowana nazwą **i gminą**, nie samą nazwą. W Polsce jest
+119 wsi „Nowa Wieś", z czego 28 w jednym województwie; sklejenie ich po nazwie
+wystawia punkt w polu, nawet 158 km od najdalszej z nich.
+
+### Import do bazy
+
+Surowe rekordy można importować partiami bez wczytywania całego pliku:
+
+```ruby
+ZipCodes::PL.each_record.each_slice(1000) do |batch|
+  PostalCode.upsert_all(batch.map(&:to_h))
+end
+```
+
+Albo zapisać zagregowane miejscowości:
+
+```ruby
+ZipCodes::PL.cities.each_slice(1000) do |batch|
+  City.upsert_all(
+    batch.map do |city|
+      { name: city.name, province: city.voivodeship,
+        latitude: city.latitude, longitude: city.longitude }
+    end,
+    unique_by: %i[name province]
+  )
+end
+```
+
+## Format pliku
+
+`zip-codes-pl.tsv` - TSV z nagłówkiem, obok `zip-codes-pl.manifest.json` z
+ETagiem źródła, datą budowy i liczbą wierszy. Celowo nieskompresowany: plik jest
+commitowany, więc odświeżenie ma dawać diff do przejrzenia, a nie nowy nieczytelny
+blob. Kolumny:
+
+| kolumna | przykład | uwagi |
+|---|---|---|
+| `postal_code` | `86-010` | |
+| `city` | `Nowa Wieś Wielka` | |
+| `voivodeship` | `kujawsko-pomorskie` | nazwa z tego gema, nie ze źródła |
+| `voivodeship_teryt` | `04` | urzędowy kod TERYT |
+| `county` / `county_teryt` | `powiat bydgoski` / `0403` | nazwa z Poczty Polskiej po kodzie TERYT |
+| `commune` / `commune_teryt` | `Koronowo` / `040304` | nazwa z Poczty Polskiej po kodzie TERYT |
+| `latitude` / `longitude` | `53.3123` / `17.9539` | WGS84 |
+| `accuracy` | `6` | pole źródła - patrz niżej |
+
+Plik jest zapisywany przez plik tymczasowy i `rename`. Błąd pobierania GeoNames,
+odpowiedzi Poczty Polskiej, parsowania albo walidacji zostawia poprzedni TSV i
+manifest bez zmian.
+
+## Czego ten gem nie udaje
+
+**To są centroidy kodów pocztowych, a nie punkty z pomiaru.** GeoNames wylicza
+wiele z nich algorytmicznie z nazw miejscowości, a tam gdzie nie znajdzie
+dopasowania, bierze średnią sąsiednich kodów. Nadają się do sortowania po
+odległości i do mapy; nie są współrzędnymi geodezyjnymi. Kolumna `accuracy`
+pochodzi ze źródła i dla Polski ma obecnie wartość `6` we **wszystkich** 72 899
+wierszach, więc nie niesie żadnej informacji.
+
+**To jest zbiór pocztowy, nie urzędowy rejestr miejscowości.** Obejmuje
+miejscowości, które mają kod pocztowy w zrzucie GeoNames, w pisowni GeoNames.
+Urzędowy TERYT SIMC jest większy i to on rozstrzyga o nazwach; różnicy między
+nimi tutaj nie zmierzyłem.
+
+**Nazwy administracyjne są ujednolicone po kodach TERYT.** Gem ma własną tabelę
+16 województw, a podczas odświeżenia pobiera z Poczty Polskiej aktualne nazwy
+powiatów i gmin. Jedynym jawnym wyjątkiem jest historyczny kod `320304` dawnej
+gminy Ostrowice, zniesionej 1 stycznia 2019, który nadal występuje w GeoNames.
+**Pewnym identyfikatorem pozostają kolumny `*_teryt`**, nie nazwy.
+
+Gem nie zawiera ulic ani numerów budynków i nie jest geokoderem adresów. Do
+adresu z dokładnością do numeru służy darmowe UUG GUGiK
+(`services.gugik.gov.pl/uug`).
+
+## Źródło i licencja
+
+Dane PNA i współrzędne pochodzą z [GeoNames](https://www.geonames.org) na
+licencji **CC BY 4.0**. Nazwy powiatów i gmin są pobierane z publicznej
+wyszukiwarki [Poczty Polskiej](https://www.poczta-polska.pl/znajdz-kod-pocztowy/).
+Manifest niesie gotową formułkę atrybucji.
+
+Sam kod jest na licencji MIT.

data/data/zip-codes-pl.manifest.json

@@ -0,0 +1,10 @@
+{
+  "source_url": "https://download.geonames.org/export/zip/PL.zip",
+  "attribution": "GeoNames (https://www.geonames.org), CC BY 4.0; county and commune names: Poczta Polska (https://www.poczta-polska.pl)",
+  "etag": "\"f1225-65b68b320a969\"",
+  "last_modified": "Mon, 14 Sep 2026 03:05:00 GMT",
+  "row_count": 72899,
+  "built_at": "2026-09-14T23:25:36Z",
+  "gem_version": "0.1.1",
+  "format_version": 1
+}