seaports 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58b616c89654cb06c7c095c1106a16bc7164835cd6cedeaf40e10f22b23089be
-  data.tar.gz: 9366dc14c643f638d73d6a288c2b10442698a03219afa0bc241a41e2e672b7f9
+  metadata.gz: 878655485e54ba5bb3f0ac454ff4ca7279d4725c8672325221cca9955b314d7c
+  data.tar.gz: c453a0e9b208fc027ea45d722ba13e7472a14785dfc534b4b936e367f204953a
 SHA512:
-  metadata.gz: ae4bd49fb6adad08534857a84df567724347dc21d7d3ef7163f3760f9e0ac470b78e15db27ae35fbe60bdd8d63a25a1ab3d12da5cedbfdeb827ca6de45f8b5cc
-  data.tar.gz: 134cc3f0980934cc76e251719a1ea47f0c142975c792485c4355e8ced35f25f3f9b47298c321c20f80e15ddbe80b22af0592ef212b6aaa32f0980c59c2b048e5
+  metadata.gz: 16c90431ed6304d4404ff2f02f816abf44bc1ed93fbb7bfbe453ab8303c662616ca27b4d8daf9a725d8edc27afa7622fdf596b99b51a0dc4fd75cd43416ab0c3
+  data.tar.gz: c9923419e7a8567153cd0c2e2643496cc3335089ca05dbcc2a3377132f8f7e96b7ed30f63cf66e1322dc927b189a6fbfa45a6066f8e5dd622ee65a84a1716630

data/CHANGELOG.md

@@ -3,6 +3,22 @@
 Every entry below the first is a UN/LOCODE refresh, opened as a pull request by
 `.github/workflows/refresh.yml` and merged by a person.
 
+## 1.2.0 — 2026-10-20
+
+Each port now carries its ISO 3166-2 subdivision, the path of every subdivision above it, and the principal (top-level) one: `Seaports.subdivision("GBFXT")` is `"GB-SFK"` (Suffolk), `Seaports.subdivision_path("FRSXB")` is `["FR-67", "FR-6AE", "FR-GES"]`, `Seaports.principal_subdivision("GBFXT")` is `"GB-ENG"`. Match on whichever level of the path other data uses: the principal one usually, but not for Alsace-Moselle, Irish counties or Indonesian provinces.
+
+14,567 of 17,527 ports have one: 13,149 from UN/LOCODE's subdivision column, 1,312 placed by their coordinates on Natural Earth's states-and-provinces map (Amsterdam), and 106 from a reviewed list for ports neither places (Valencia, Algeciras, Barcelona). Every code is checked against ISO 3166-2 (Debian iso-codes) at build time.
+
+`Seaports::Port` gains three members, all optional, so `Port.new(locode:, name:, coordinates:)` still works. A positional pattern match on a three-element Port (`in [locode, name, coordinates]`) no longer matches; match by key instead.
+
+Refreshes now ship a change at any level of a port's path, refuse a rebuild that moves more than 2% of ports to another principal subdivision, report overrides that have outlived their reason, and turn a failed download into a refusal issue rather than a failed build.
+
+Same UN/LOCODE 2024-2 ports, names and positions as 1.1.0.
+
+## 1.1.0 — 2026-10-19
+
+UN/LOCODE release unknown. 17527 sea ports (17520 before): 7 added, 0 removed, 1 renamed, 83 repositioned.
+
 ## 1.0.0 — 2026-08-21
 
 First release. Extracted from the Trackberry application, where this table

data/README.md

@@ -6,9 +6,10 @@
 A locode in, a port name and a position out.
 
 ```ruby
-Seaports.name("CNXMG")         # => "Xiamen Pt"
-Seaports.coordinates("AUBNE")  # => { "lat" => -27.4667, "lng" => 153.0167 }
-Seaports.find("KRPUS")         # => #<data Seaports::Port locode="KRPUS", name="Busan", ...>
+Seaports.name("CNXMG")                   # => "Xiamen Pt"
+Seaports.coordinates("AUBNE")            # => { "lat" => -27.4667, "lng" => 153.0167 }
+Seaports.principal_subdivision("DEHAM")  # => "DE-HH"
+Seaports.find("KRPUS")                   # => #<data Seaports::Port locode="KRPUS", name="Busan", ...>
 ```
 
 Tracking feeds speak in codes. An AIS provider names some port calls and sends
@@ -29,11 +30,12 @@ out of the default gems.
 
 ## What is in it
 
-Every entry UN/LOCODE classifies as a sea port: **17,520 ports**, 11,762 of them
-with published coordinates, built from **UN/LOCODE 2024-2**.
+Every entry UN/LOCODE classifies as a sea port: **17,527 ports**, 11,820 of them
+with published coordinates and 14,567 with a subdivision, built from
+**UN/LOCODE 2024-2**.
 
 ```ruby
-Seaports.count          # => 17520
+Seaports.count          # => 17527
 Seaports.all            # => [#<data Seaports::Port ...>, ...]
 Seaports.data_release   # => "2024-2"
 ```
@@ -53,6 +55,63 @@ Roughly a third of the table has no position published. That is a fact about
 the source, not a failure — the name is still worth having, and a map simply
 draws no marker.
 
+### Subdivisions
+
+UN/LOCODE files each place under a subdivision of its country, which joined to
+the country is an ISO 3166-2 code. It picks whatever level suits the country:
+a state for Hamburg, a county for Felixstowe. Each port carries that code, the
+**path** of every ISO subdivision above it, and the **principal subdivision**
+at the top:
+
+```ruby
+Seaports.subdivision("GBFXT")            # => "GB-SFK"  Suffolk
+Seaports.principal_subdivision("GBFXT")  # => "GB-ENG"  England
+Seaports.subdivision_path("FRSXB")       # => ["FR-67", "FR-6AE", "FR-GES"]  Bas-Rhin › Alsace › Grand Est
+Seaports.principal_subdivision("DEHAM")  # => "DE-HH"   Hamburg, already top level
+Seaports.principal_subdivision("ESVLC")  # => "ES-VC"   Comunitat Valenciana
+```
+
+To join a port to other data, a public holiday calendar say, match on
+whichever level of the path that data uses. The principal subdivision is
+usually the one (German states, UK nations, Spanish communities), but ISO's
+top level is not always where things are decided: Alsace-Moselle (`FR-6AE`)
+keeps holidays the rest of Grand Est does not, Ireland's top level is its four
+provinces rather than its counties, and Indonesia's is island groups (`ID-JW`
+Java) rather than provinces (`ID-JK` Jakarta). The path carries every level, so
+matching on any of it is always safe.
+
+A port's subdivision comes from the first of three sources that has one, and
+the table records which (`subdivision_source`):
+
+| Source | Ports | How |
+| --- | --- | --- |
+| `override` | 106 | A reviewed list, `data/sources/subdivision_overrides.csv`, for ports neither of the others places: Valencia, Algeciras and Barcelona have no subdivision and no position in UN/LOCODE. Each row says where its code came from. |
+| `unlocode` | 13,149 | UN/LOCODE's own subdivision column. |
+| `boundaries` | 1,312 | The port's coordinates placed on [Natural Earth](https://www.naturalearthdata.com/)'s states-and-provinces map (public domain, pinned to one commit), or the nearest subdivision within 10 km when a waterfront position lands just offshore. Amsterdam is placed this way. |
+
+Every code is checked against ISO 3166-2, and the path follows ISO's own
+hierarchy, taken from
+[Debian's iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes). A code
+whose chain is broken in that list is dropped rather than shipped without a
+trustworthy top. Both maps are read when the table is built; nothing is
+fetched at runtime.
+
+2,960 ports stay without one, mostly offshore fields and moorings, and ports in
+countries with no regional distinctions worth drawing. To place more, run
+`ruby script/suggest_subdivision_overrides.rb candidates.csv`: it searches each
+port's name on OpenStreetMap's Nominatim and prints suggestions with the place
+it matched, for a person to check before adding them to the overrides file. A
+name search does find the wrong Puerto de Santa María. Place names in the
+overrides file are © OpenStreetMap contributors, under the
+[ODbL](https://www.openstreetmap.org/copyright).
+
+Each refresh lists, for review, overrides that have outlived their reason: a
+port that left UN/LOCODE, or one UN/LOCODE now places itself.
+
+`Seaports::Port` gained `subdivision`, `principal_subdivision` and
+`subdivision_path` in 1.2.0, all optional, so a `Port` built from locode, name
+and coordinates as before still works.
+
 ### What is deliberately not in it
 
 Only entries UNECE marks with function `1`, "port", are kept. A road terminal,
@@ -73,6 +132,42 @@ from a three-character carrier code, which is a heuristic: a code that is not a
 locode tail could pair with a country to form a valid-looking locode for some
 inland village, and a table of ports is far less likely to name it.
 
+## What it costs
+
+A lookup is a hash fetch. The table is parsed once, on the first lookup rather
+than at require time, and after that nothing touches the disk again.
+
+| | |
+| --- | --- |
+| lookup | **0.31 µs** — about 3.2M per second |
+| miss | 0.28 µs |
+| malformed input | 0.25 µs — rejected on shape before the table is consulted |
+| first lookup, which parses the table | ~140 ms, once per process |
+| resident table | 3.9 MB |
+
+Measured on Ruby 4.0, Apple Silicon, against the shipped 468 KB table. Reading
+the file off disk is 0.4 ms of that first 140 ms; the rest is CSV parsing and
+building the 17,520 objects, so it is CPU rather than I/O.
+
+There is no database, no ActiveRecord, and no query per lookup. That is worth
+saying because the alternative approach in this corner of the ecosystem is to
+ship a SQLite file and read it through ActiveRecord, which puts a second
+database connection and a version-pinned ORM into the dependency graph of an
+application that only wanted to turn `CNXMG` into `Xiamen Pt`. A CSV and a hash
+answer the same question with one dependency and no connection.
+
+Nothing here is cached, because there is nothing left to cache: the table
+already is the cache. A `Rails.cache` round trip costs around a millisecond,
+which is some three thousand times slower than the lookup it would be caching.
+
+The one cost worth managing is that first 140 ms, and the fix is to move it off
+the request path rather than to cache it:
+
+```ruby
+# config/initializers/seaports.rb
+Rails.application.config.after_initialize { Seaports.count }
+```
+
 ## How the table stays current
 
 UNECE republishes twice a year and does not announce it. A scheduled workflow