seaports 1.0.0 → 1.2.0

data/lib/seaports/boundaries.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Seaports
+  # Which subdivision a point falls in, from Natural Earth's admin-1 map.
+  #
+  # UN/LOCODE leaves the subdivision blank for about a quarter of its ports,
+  # Amsterdam among them, but publishes coordinates for half of those. Natural
+  # Earth's states-and-provinces layer (public domain) tags each polygon with
+  # its ISO 3166-2 code, so a port with a position can be placed in one.
+  #
+  # Build-time only, like Seaports::Subdivisions: the 40 MB map is read when
+  # the table is built and the codes it finds are written into the table.
+  class Boundaries
+    # Pinned to a commit rather than master, so the map only changes when
+    # someone moves this line and reads what moved with it. ca96624 (June
+    # 2022) is master's head at the time of pinning.
+    SOURCE_URL = "https://raw.githubusercontent.com/nvkelso/natural-earth-vector/ca96624a56bd078437bca8184e78163e5039ad19/geojson/ne_10m_admin_1_states_provinces.geojson"
+
+    # UN/LOCODE gives positions to the minute, about two kilometres, and a
+    # port's position is usually its waterfront, so a fair share of ports land
+    # just offshore of the coastline Natural Earth drew. Within this distance
+    # of a subdivision of the port's own country, the port is placed in the
+    # nearest one; further out, it gets none rather than a guess.
+    NEAREST_WITHIN_KM = 10
+
+    KM_PER_DEGREE_LAT = 110.57
+    KM_PER_DEGREE_LNG = 111.32
+
+    # +codes+ is the area's own ISO 3166-2 code, then the codes of what it
+    # sits in, as far as Natural Earth records them. The map is a few years
+    # behind ISO in places (Northern Ireland's districts were merged in 2015
+    # and it still draws the old ones), so when the area's own code has been
+    # retired, its parent still places the port: Larne is gone, but it was in
+    # GB-NIR.
+    Area = Data.define(:codes, :polygons, :bbox) do
+      def country
+        codes.first[0, 2]
+      end
+    end
+
+    CODE = /\A[A-Z]{2}-[A-Z0-9]{1,3}\z/
+
+    def self.parse(geojson)
+      areas = JSON.parse(geojson).fetch("features").filter_map do |feature|
+        codes = codes_of(feature.fetch("properties"))
+        next if codes.empty?
+
+        polygons = polygons_of(feature["geometry"])
+        next if polygons.empty?
+
+        Area.new(codes: codes, polygons: polygons, bbox: bbox(polygons))
+      end
+      new(areas)
+    end
+
+    # The area's code, then its region's ("ES.VC" is written with a dot), then,
+    # for the UK, its nation (gu_a3 is "ENG", "NIR", "SCT" or "WLS").
+    #
+    # Areas whose own code is not shaped like ISO 3166-2 (Natural Earth's
+    # placeholders: "BA-X01" for Republika Srpska's municipalities, Kosovo's
+    # "XK-" codes, "-99") are skipped entirely, so a port inside one but
+    # within 10 km of a coded neighbour is placed in the neighbour. No port in
+    # the shipped table is today.
+    def self.codes_of(properties)
+      code = properties["iso_3166_2"].to_s
+      return [] unless code.match?(CODE)
+
+      country = code[0, 2]
+      region = properties["region_cod"].to_s.tr(".", "-")
+      nation = country == "GB" ? "GB-#{properties['gu_a3']}" : ""
+      [code, region, nation].select { |candidate| candidate.match?(CODE) && candidate.start_with?("#{country}-") }.uniq
+    end
+
+    # [[outer ring, hole, …], …] for a Polygon or MultiPolygon, each ring an
+    # array of [lng, lat].
+    def self.polygons_of(geometry)
+      case geometry&.fetch("type")
+      when "Polygon" then [geometry.fetch("coordinates")]
+      when "MultiPolygon" then geometry.fetch("coordinates")
+      else []
+      end
+    end
+
+    def self.bbox(polygons)
+      points = polygons.flat_map(&:first)
+      lngs = points.map(&:first)
+      lats = points.map(&:last)
+      [lngs.min, lats.min, lngs.max, lats.max]
+    end
+
+    def initialize(areas)
+      @by_country = areas.group_by(&:country)
+    end
+
+    # The codes (see Area) of the +country+ subdivision containing the point,
+    # or of the nearest one within NEAREST_WITHIN_KM; empty when there is
+    # none. Only the port's own country is searched, so a port on a border
+    # cannot be handed to its neighbour.
+    def codes_at(country, lat, lng)
+      areas = @by_country.fetch(country.to_s.upcase, [])
+      return [] if areas.empty? || lat.nil? || lng.nil?
+
+      containing = areas.find { |area| within_bbox?(area, lat, lng, 0) && contains?(area, lat, lng) }
+      (containing || nearest(areas, lat, lng))&.codes || []
+    end
+
+    private
+
+    # +lat_margin+ and +lng_margin+ in degrees. They differ because a degree
+    # of longitude shrinks towards the poles: 10 km is 0.09° of latitude
+    # anywhere, but 0.2° of longitude in northern Norway.
+    def within_bbox?(area, lat, lng, lat_margin, lng_margin = lat_margin)
+      min_lng, min_lat, max_lng, max_lat = area.bbox
+      lng.between?(min_lng - lng_margin, max_lng + lng_margin) && lat.between?(min_lat - lat_margin, max_lat + lat_margin)
+    end
+
+    def contains?(area, lat, lng)
+      area.polygons.any? do |outer, *holes|
+        inside?(outer, lat, lng) && holes.none? { |hole| inside?(hole, lat, lng) }
+      end
+    end
+
+    # Ray casting: a point is inside a ring if a ray from it crosses the ring
+    # an odd number of times.
+    def inside?(ring, lat, lng)
+      inside = false
+      ring.each_cons(2) do |(x1, y1), (x2, y2)|
+        next unless (y1 > lat) != (y2 > lat)
+
+        crossing = x1 + ((lat - y1) * (x2 - x1) / (y2 - y1))
+        inside = !inside if lng < crossing
+      end
+      inside
+    end
+
+    # Longitudes are compared as given, so a port a few kilometres across the
+    # antimeridian from its coast (Fiji, Chukotka) is left unplaced. It is
+    # never placed wrongly.
+    def nearest(areas, lat, lng)
+      lat_margin = NEAREST_WITHIN_KM / KM_PER_DEGREE_LAT
+      lng_margin = NEAREST_WITHIN_KM / (KM_PER_DEGREE_LNG * [Math.cos(lat * Math::PI / 180), 0.01].max)
+      best = areas.select { |area| within_bbox?(area, lat, lng, lat_margin, lng_margin) }
+        .map { |area| [area, distance_km(area, lat, lng)] }
+        .min_by(&:last)
+      best && best.last <= NEAREST_WITHIN_KM ? best.first : nil
+    end
+
+    # Shortest distance from the point to any edge of the area, on a flat
+    # projection centred on the point. Over ten kilometres the earth's
+    # curvature is far below the source's own two-kilometre precision.
+    #
+    # Hole edges count as edges, so a port inside a hole (a lake, or an
+    # enclave the map does not code) but within 10 km of its shore is placed
+    # in the area around it. That is the right answer for a lake port.
+    def distance_km(area, lat, lng)
+      scale = Math.cos(lat * Math::PI / 180) * KM_PER_DEGREE_LNG
+      area.polygons.flatten(1).flat_map { |ring| ring.each_cons(2).to_a }.map do |(x1, y1), (x2, y2)|
+        segment_distance(
+          (x1 - lng) * scale, (y1 - lat) * KM_PER_DEGREE_LAT,
+          (x2 - lng) * scale, (y2 - lat) * KM_PER_DEGREE_LAT
+        )
+      end.min || Float::INFINITY
+    end
+
+    # Distance from the origin to the segment (ax, ay)–(bx, by).
+    def segment_distance(ax, ay, bx, by)
+      dx = bx - ax
+      dy = by - ay
+      length = (dx * dx) + (dy * dy)
+      t = length.zero? ? 0 : (-((ax * dx) + (ay * dy)) / length).clamp(0, 1)
+      Math.hypot(ax + (t * dx), ay + (t * dy))
+    end
+  end
+end

data/lib/seaports/builder.rb

@@ -24,7 +24,13 @@ module Seaports
     SOURCE_URL = "https://raw.githubusercontent.com/datasets/un-locode/main/data/code-list.csv"
     DATAPACKAGE_URL = "https://raw.githubusercontent.com/datasets/un-locode/main/datapackage.json"
 
-    HEADERS = %w[locode name lat lng].freeze
+    HEADERS = %w[locode name lat lng subdivision principal_subdivision subdivision_path subdivision_source].freeze
+
+    # Reviewed subdivisions for ports neither UN/LOCODE nor the map places:
+    # Valencia, Algeciras and Barcelona have no subdivision and no position.
+    # Kept outside data/*.csv so it is not shipped in the gem; only its result
+    # is.
+    OVERRIDES_PATH = File.expand_path("../../data/sources/subdivision_overrides.csv", __dir__)
 
     # The published list, straight off the network — or off disk, if what was
     # handed over is a path. Both, because a rebuild from an already-downloaded
@@ -50,11 +56,48 @@ module Seaports
       nil
     end
 
-    def initialize(source)
+    # Reads OVERRIDES_PATH (or +path+) into { locode => ISO 3166-2 code }.
+    #
+    # The file is typed by people, so a blank cell, a malformed locode or a
+    # port listed twice stops the build with the line to fix, rather than
+    # crashing on a nil or letting the second row quietly win.
+    def self.overrides(path = OVERRIDES_PATH)
+      return {} unless File.exist?(path)
+
+      CSV.foreach(path, headers: true).with_index(2).each_with_object({}) do |(row, line), overrides|
+        locode = row["locode"].to_s.strip.upcase
+        code = row["subdivision"].to_s.strip.upcase
+        raise ArgumentError, "#{path}:#{line}: #{locode.inspect} is not a locode" unless locode.match?(/\A[A-Z]{2}[A-Z0-9]{3}\z/)
+        raise ArgumentError, "#{path}:#{line}: #{locode} has no subdivision" if code.empty?
+        raise ArgumentError, "#{path}:#{line}: #{locode} is listed twice" if overrides.key?(locode)
+
+        overrides[locode] = code
+      end
+    end
+
+    # Where a port's subdivision comes from, best first:
+    #
+    # - +overrides+, { locode => code }, reviewed by a person;
+    # - UN/LOCODE's own subdivision column;
+    # - +boundaries+ (Seaports::Boundaries), the subdivision the port's
+    #   coordinates fall in.
+    #
+    # Every code is checked against +subdivisions+, the ISO 3166-2 list (see
+    # Seaports::Subdivisions), which also gives the principal subdivision
+    # above it. Without that list the subdivision columns stay empty, which
+    # keeps a test about something else from needing it.
+    def initialize(source, subdivisions: nil, boundaries: nil, overrides: {})
       @source = source
+      @subdivisions = subdivisions
+      @boundaries = boundaries
+      @overrides = overrides
+      @superseded = []
     end
 
-    # [locode, name, lat, lng] per port, deduplicated and sorted by locode.
+    # [locode, name, lat, lng, subdivision, principal_subdivision,
+    # subdivision_path, subdivision_source] per port, deduplicated and sorted
+    # by locode. The path is the subdivision and everything above it, space
+    # separated, most specific first (see Seaports::Subdivisions#path).
     # Sorted because the file is committed: a stable order means a refresh
     # diff shows what changed rather than the whole table moving.
     def rows
@@ -77,6 +120,27 @@ module Seaports
       rows.count { |row| !row[2].nil? }
     end
 
+    def subdivided_count
+      rows.count { |row| !row[5].nil? }
+    end
+
+    # Overrides worth a person's attention, written the way they should read
+    # in a refresh pull request. An override wins over everything, so one that
+    # has outlived its reason keeps masking better data until someone looks:
+    #
+    # - its port is no longer in UN/LOCODE's sea-port list;
+    # - UN/LOCODE now gives the port a subdivision of its own.
+    def override_report
+      rows # the report is a by-product of building them
+      stale = (@overrides.keys - rows.map(&:first)).sort
+        .map { |locode| "`#{locode}` is overridden but no longer a UN/LOCODE sea port: remove its row." }
+      superseded = @superseded.uniq.sort.map do |locode, own, override|
+        same = own == override ? "the same code" : "#{own}, not #{override}"
+        "`#{locode}` now has a UN/LOCODE subdivision (#{same}): its override can go."
+      end
+      stale + superseded
+    end
+
     private
 
     # UNECE classifies every entry by function, and position 1 of that string
@@ -94,8 +158,35 @@ module Seaports
     end
 
     def port_row(row)
+      locode = "#{row['Country']}#{row['Location']}".upcase
       lat, lng = decimal_degrees(row["Coordinates"])
-      ["#{row['Country']}#{row['Location']}".upcase, row["Name"].strip, lat, lng]
+      subdivision, source = subdivision_for(locode, row, lat, lng)
+      path = @subdivisions&.path(subdivision) || []
+      # A code whose chain breaks has no trustworthy top, so it is not kept.
+      subdivision = source = nil if path.empty?
+      [locode, row["Name"].strip, lat, lng, subdivision, path.last, path.empty? ? nil : path.join(" "), source]
+    end
+
+    # [code, source], or [nil, nil] when no source has a valid one.
+    def subdivision_for(locode, row, lat, lng)
+      return [nil, nil] if @subdivisions.nil?
+
+      country = row["Country"].to_s.strip.upcase
+      own = @subdivisions.code(country, row["Subdivision"])
+
+      if (override = @overrides[locode])
+        code = @subdivisions.code(country, override.delete_prefix("#{country}-"))
+        raise ArgumentError, "#{locode}: override #{override} is not an ISO 3166-2 code of #{country}" if code.nil?
+
+        @superseded << [locode, own, code] if own
+        return [code, "override"]
+      end
+
+      return [own, "unlocode"] if own
+
+      mapped = (@boundaries&.codes_at(country, lat, lng) || []).lazy
+        .filter_map { |candidate| @subdivisions.code(country, candidate.delete_prefix("#{country}-")) }.first
+      mapped ? [mapped, "boundaries"] : [nil, nil]
     end
 
     # UNECE writes coordinates as "2421N 11812E" — degrees and whole minutes,

data/lib/seaports/diff.rb

@@ -41,10 +41,16 @@ module Seaports
         locode = row["locode"].to_s.strip.upcase
         next if locode.empty?
 
-        ports[locode] = { name: row["name"].to_s.strip, point: point(row) }
+        ports[locode] = { name: row["name"].to_s.strip, point: point(row), path: path(row) }
       end
     end
 
+    # The port's subdivision chain as written, "GB-SFK GB-ENG". A table from
+    # before the path column existed has only the principal, which stands in.
+    def self.path(row)
+      (row["subdivision_path"] || row["principal_subdivision"]).to_s.split.join(" ")
+    end
+
     def self.point(row)
       lat = row["lat"].to_s.strip
       lng = row["lng"].to_s.strip
@@ -59,7 +65,7 @@ module Seaports
     end
 
     def changed?
-      !(added.empty? && removed.empty? && renamed.empty? && repositioned.empty?)
+      !(added.empty? && removed.empty? && renamed.empty? && repositioned.empty? && resubdivided.empty?)
     end
 
     def added
@@ -93,10 +99,33 @@ module Seaports
       end
     end
 
+    # [locode, name, was, now] for a port whose subdivision path changed at
+    # any level, each path a space-separated string ("" for none). A county
+    # that moves inside the same nation changes Seaports.subdivision without
+    # touching the principal one, and it still has to ship. Each change can
+    # move a port onto another holiday calendar, so all are listed, though
+    # none is a failure on its own.
+    def resubdivided
+      @resubdivided ||= common.filter_map do |locode|
+        was = @before[locode][:path].to_s
+        now = @after[locode][:path].to_s
+        [locode, @after[locode][:name], was, now] if was != now
+      end
+    end
+
+    # The subset of resubdivided whose principal subdivision went from one
+    # code to another: placed before, placed now, somewhere else. Gaining or
+    # losing a code is not in it.
+    def reassigned
+      @reassigned ||= resubdivided.select do |_, _, was, now|
+        !was.empty? && !now.empty? && was.split.last != now.split.last
+      end
+    end
+
     # Empty means the refresh may ship. Anything here is a reason it may not,
     # written the way it should read in an issue.
     def failures
-      [count_failure, shrinkage_failure, *anchor_failures, *excluded_failures].compact
+      [count_failure, shrinkage_failure, region_failure, reassignment_failure, *anchor_failures, *excluded_failures].compact
     end
 
     def ok?
@@ -110,7 +139,8 @@ module Seaports
         section("Removed", removed.map { |locode| "`#{locode}` #{@before[locode][:name]}" }, limit: nil),
         section("Added", added.map { |locode| "`#{locode}` #{@after[locode][:name]}" }),
         section("Renamed", renamed.map { |locode, was, now| "`#{locode}` #{was} → #{now}" }),
-        section("Coordinates", repositioned.map { |locode, name, kind| "`#{locode}` #{name} — #{POSITION_WORDS.fetch(kind)}" })
+        section("Coordinates", repositioned.map { |locode, name, kind| "`#{locode}` #{name} — #{POSITION_WORDS.fetch(kind)}" }),
+        section("Subdivision", resubdivided.map { |locode, name, was, now| "`#{locode}` #{name}: #{path_words(was)} → #{path_words(now)}" })
       ].compact.join("\n\n")
     end
 
@@ -125,11 +155,32 @@ module Seaports
     def headline
       "#{@after.size} sea ports (#{@before.size} before): " \
         "#{added.size} added, #{removed.size} removed, " \
-        "#{renamed.size} renamed, #{repositioned.size} repositioned."
+        "#{renamed.size} renamed, #{repositioned.size} repositioned, " \
+        "#{resubdivided.size} with a new subdivision (#{reassigned.size} moved to another principal one)."
     end
 
+    # A real refresh moves a handful of ports between regions, when UNECE
+    # corrects an entry or ISO redraws a country. Moving more than this share
+    # of the placed ports at once means a source reshuffled its codes.
+    MAXIMUM_REASSIGNMENT = 0.02
+
     private
 
+    def path_words(path)
+      path.empty? ? "none" : path.split.join(" › ")
+    end
+
+    def reassignment_failure
+      placed = regioned_count(@before)
+      return nil if placed.zero?
+
+      share = reassigned.size.to_f / placed
+      return nil if share <= MAXIMUM_REASSIGNMENT
+
+      "#{reassigned.size} ports moved to another principal subdivision, past the #{(MAXIMUM_REASSIGNMENT * 100).round}% limit: " \
+        "a source reshuffled its codes."
+    end
+
     def common
       @common ||= (@before.keys & @after.keys).sort
     end
@@ -149,6 +200,25 @@ module Seaports
       "The table shrank by #{(shrinkage * 100).round(1)}%, past the #{(MAXIMUM_SHRINKAGE * 100).round}% limit."
     end
 
+    # Losing subdivisions in bulk means the ISO 3166-2 list failed to load or
+    # UNECE dropped the column, not that ports moved country. A table that
+    # had none before (every table before this column existed) has nothing
+    # to lose.
+    def region_failure
+      was = regioned_count(@before)
+      return nil if was.zero?
+
+      now = regioned_count(@after)
+      shrinkage = (was - now).to_f / was
+      return nil if shrinkage <= MAXIMUM_SHRINKAGE
+
+      "Ports with a principal subdivision fell from #{was} to #{now}, past the #{(MAXIMUM_SHRINKAGE * 100).round}% limit."
+    end
+
+    def regioned_count(ports)
+      ports.count { |_, port| !port[:path].to_s.empty? }
+    end
+
     def anchor_failures
       ANCHORS.reject { |locode| @after.key?(locode) }
         .map { |locode| "`#{locode}` is gone, and a port that large does not disappear." }

data/lib/seaports/subdivisions.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Seaports
+  # ISO 3166-2, for turning UN/LOCODE's subdivision column into codes other
+  # datasets share.
+  #
+  # UN/LOCODE files Hamburg under "HH" and Felixstowe under "SFK". Read with
+  # the country in front, both are ISO 3166-2 codes, but at different levels:
+  # DE-HH is a German state, GB-SFK an English county. Public holiday
+  # calendars, address geocoders and most other datasets that split a country
+  # work at the top level, the principal subdivision: DE-HH, and GB-ENG for
+  # Felixstowe. ISO publishes which code sits inside which, so the climb from
+  # county to nation is a lookup, not a guess.
+  #
+  # Build-time only. The source is Debian's iso-codes, the ISO 3166-2 list
+  # most Linux systems ship, and nothing at runtime reads it: the resolved
+  # codes are written into the table.
+  class Subdivisions
+    SOURCE_URL = "https://salsa.debian.org/iso-codes-team/iso-codes/-/raw/main/data/iso_3166-2.json"
+
+    # A chain longer than this is a loop in the data, not a real hierarchy:
+    # ISO goes three levels deep at most.
+    MAX_DEPTH = 5
+
+    def self.parse(json)
+      new(JSON.parse(json).fetch("3166-2"))
+    end
+
+    def initialize(entries)
+      @parents = entries.to_h { |entry| [entry.fetch("code"), entry["parent"]] }
+    end
+
+    # "DE-HH" for ("DE", "HH"), or nil when the pair is not an ISO 3166-2
+    # code. UN/LOCODE carries a few codes ISO has retired or never had, and a
+    # code nobody else recognises is worse than none.
+    def code(country, subdivision)
+      return nil if subdivision.to_s.strip.empty?
+
+      candidate = "#{country.to_s.strip.upcase}-#{subdivision.to_s.strip.upcase}"
+      @parents.key?(candidate) ? candidate : nil
+    end
+
+    # +code+ and every subdivision above it, most specific first:
+    # ["FR-67", "FR-6AE", "FR-GES"] for Bas-Rhin, ["DE-HH"] for Hamburg.
+    #
+    # The whole chain rather than just its top, because ISO's top level is not
+    # always the one that matters. Alsace-Moselle (FR-6AE) has holidays the
+    # rest of Grand Est (FR-GES) does not, and Indonesia's top level is island
+    # groups, above the provinces that run anything. A caller matches on
+    # whichever level its own data uses.
+    #
+    # Empty for nil, and for a chain that breaks (a parent the list does not
+    # hold) or loops: a guessed top would be believed.
+    def path(code)
+      return [] if code.nil?
+
+      chain = [code]
+      MAX_DEPTH.times do
+        parent = @parents[chain.last]
+        return chain if parent.nil?
+        return [] unless @parents.key?(parent)
+
+        chain << parent
+      end
+      []
+    end
+
+    # The top of +code+'s path: GB-ENG for GB-SFK, ES-VC for ES-V, DE-HH for
+    # DE-HH itself. Nil when the path is empty.
+    def principal(code)
+      path(code).last
+    end
+
+    def size
+      @parents.size
+    end
+  end
+end

data/lib/seaports/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Seaports
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 
   # The UN/LOCODE edition the shipped table was built from. UNECE republishes
   # twice a year and names each release by year and half — "2024-2" is the

data/lib/seaports.rb

@@ -38,7 +38,31 @@ require_relative "seaports/version"
 module Seaports
   TABLE_PATH = File.expand_path("../data/un_locode_seaports.csv", __dir__)
 
-  Port = Data.define(:locode, :name, :coordinates)
+  # +subdivision+ is the ISO 3166-2 code of the area the port is in, at
+  # whatever level its source chose: "DE-HH" for Hamburg, "GB-SFK" (Suffolk)
+  # for Felixstowe. +subdivision_path+ is that code and every ISO subdivision
+  # above it, most specific first: ["GB-SFK", "GB-ENG"], or ["FR-67",
+  # "FR-6AE", "FR-GES"] for Strasbourg. +principal_subdivision+ is the last of
+  # them, ISO's top level.
+  #
+  # To join a port to other data, match on whichever level of the path that
+  # data uses. The top is usually right (German states, UK nations, Spanish
+  # communities) but not always: Alsace-Moselle (FR-6AE) has its own
+  # holidays inside Grand Est, and Indonesia's top level is island groups,
+  # above its provinces.
+  #
+  # The code comes from UN/LOCODE where it gives one, from the port's
+  # coordinates on Natural Earth's map where it does not, and from a reviewed
+  # list for ports neither places (Valencia, Barcelona). Nil, and an empty
+  # path, when none of the three does.
+  #
+  # The three were added in 1.2.0 with defaults, so a Port built from
+  # locode, name and coordinates alone, as before, still works.
+  Port = Data.define(:locode, :name, :coordinates, :subdivision, :principal_subdivision, :subdivision_path) do
+    def initialize(locode:, name:, coordinates:, subdivision: nil, principal_subdivision: nil, subdivision_path: [])
+      super
+    end
+  end
 
   class << self
     # Nil for anything the table does not hold, which callers must handle:
@@ -62,6 +86,23 @@ module Seaports
       find(locode)&.coordinates
     end
 
+    # "GB-SFK" for Felixstowe, or nil. See Port.
+    def subdivision(locode)
+      find(locode)&.subdivision
+    end
+
+    # "GB-ENG" for Felixstowe, "DE-HH" for Hamburg, or nil. See Port.
+    def principal_subdivision(locode)
+      find(locode)&.principal_subdivision
+    end
+
+    # ["GB-SFK", "GB-ENG"] for Felixstowe, [] for a port nothing places or a
+    # code the table does not hold. The codes to hand a holiday calendar that
+    # matches on any level: Trackberry::Holidays.holiday?(date, path).
+    def subdivision_path(locode)
+      find(locode)&.subdivision_path || []
+    end
+
     # Every port in the table, ordered by locode. Materialised on each call
     # rather than handed out from the cache, so a caller cannot mutate the
     # table everyone else reads.
@@ -104,7 +145,9 @@ module Seaports
         locode = normalize(row["locode"])
         next if locode.nil? || blank?(row["name"])
 
-        ports[locode] = Port.new(locode: locode, name: row["name"], coordinates: point(row))
+        ports[locode] = Port.new(locode: locode, name: row["name"], coordinates: point(row),
+          subdivision: presence(row["subdivision"]), principal_subdivision: presence(row["principal_subdivision"]),
+          subdivision_path: row["subdivision_path"].to_s.split.freeze)
       end
     end
 
@@ -117,5 +160,9 @@ module Seaports
     def blank?(value)
       value.to_s.strip.empty?
     end
+
+    def presence(value)
+      blank?(value) ? nil : value.strip
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: seaports
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Édouard Brière
@@ -24,10 +24,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.3'
 description: |
-  Every sea port UNECE publishes a UN/LOCODE for, as a lookup table with no
-  dependencies and no network calls. Turns the bare codes in an AIS or
-  carrier tracking feed back into port names and coordinates. The table is
-  regenerated from each UN/LOCODE release and shipped inside the gem.
+  Every sea port UNECE publishes a UN/LOCODE for, as a lookup table that
+  makes no network calls. Turns the bare codes in an AIS or carrier tracking
+  feed back into port names and coordinates. The table is regenerated from
+  each UN/LOCODE release and shipped inside the gem.
 email:
 - edouard.briere@gmail.com
 executables: []
@@ -39,8 +39,10 @@ files:
 - README.md
 - data/un_locode_seaports.csv
 - lib/seaports.rb
+- lib/seaports/boundaries.rb
 - lib/seaports/builder.rb
 - lib/seaports/diff.rb
+- lib/seaports/subdivisions.rb
 - lib/seaports/version.rb
 homepage: https://github.com/Trackberry/seaports
 licenses: