iata 0.1.0

data/lib/iata/data/fetcher.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'fileutils'
+
+module Iata
+  module Data
+    # Downloads the IATA airport code list from Wikidata via SPARQL and
+    # writes it to `lib/iata/data/airports.json` as a single JSON object
+    # keyed by IATA code.
+    #
+    # Data source: Wikidata property P238 ("IATA airport code"). Each
+    # result is an airport with its English label, ISO 3166-1 alpha-2
+    # country code, and WGS-84 coordinates.
+    module Fetcher
+      SPARQL_ENDPOINT = 'https://query.wikidata.org/sparql'
+      USER_AGENT = 'metanorma-iata-gem/0.1 (https://github.com/metanorma/iata)'
+      DATA_DIR = File.expand_path(__dir__)
+      OUTPUT_PATH = File.join(DATA_DIR, 'airports.json')
+
+      QUERY = <<~SPARQL
+        SELECT ?iata ?name ?country ?countryIso2 ?coord ?wdId WHERE {
+          ?airport wdt:P238 ?iata .
+          ?airport wdt:P17 ?country .
+          ?airport rdfs:label ?name . FILTER(LANG(?name) = "en")
+          OPTIONAL { ?country wdt:P297 ?countryIso2 . }
+          OPTIONAL { ?airport wdt:P625 ?coord . }
+          BIND(STRAFTER(STR(?airport), "/entity/") AS ?wdId)
+        }
+        ORDER BY ?iata
+      SPARQL
+
+      class << self
+        # @return [String] the path written
+        def call
+          results = query
+          data = transform(results)
+          write(data, fetched_at: Time.now.utc.iso8601, result_count: results.size)
+          warn "Fetched #{data.size} IATA airports from Wikidata (#{File.size(OUTPUT_PATH)} bytes)"
+          OUTPUT_PATH
+        end
+
+        # @return [Array<Hash>] raw SPARQL bindings, each as a hash of {key: {value:, type:}}
+        def query
+          uri = URI(SPARQL_ENDPOINT)
+          uri.query = URI.encode_www_form(
+            query: QUERY,
+            format: 'json'
+          )
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == 'https')
+          http.open_timeout = 30
+          http.read_timeout = 180
+
+          request = Net::HTTP::Get.new(uri.request_uri)
+          request['User-Agent'] = USER_AGENT
+          request['Accept'] = 'application/sparql-results+json'
+
+          response = http.request(request)
+          unless response.is_a?(Net::HTTPSuccess)
+            raise "Wikidata SPARQL query failed: HTTP #{response.code} #{response.message}\n#{response.body[0..500]}"
+          end
+
+          JSON.parse(response.body, symbolize_names: true)[:results][:bindings]
+        end
+
+        # @param bindings [Array<Hash>] SPARQL result bindings
+        # @return [Hash<String, Hash>] keyed by IATA code
+        def transform(bindings)
+          data = {}
+          bindings.each do |row|
+            code = row[:iata]&.dig(:value)
+            next if code.nil?
+
+            data[code] = build_entry(row)
+          end
+          data
+        end
+
+        def write(data, fetched_at:, result_count:)
+          FileUtils.mkdir_p(DATA_DIR)
+          payload = {
+            '_meta' => {
+              'fetched_at' => fetched_at,
+              'source' => 'Wikidata (property P238)',
+              'result_count' => result_count,
+              'entry_count' => data.size
+            }
+          }.merge(data)
+          File.write(OUTPUT_PATH, JSON.pretty_generate(payload))
+        end
+
+        private
+
+        def build_entry(row)
+          {
+            'code' => row[:iata]&.dig(:value),
+            'name' => row[:name]&.dig(:value),
+            'wikidata_id' => row[:wdId]&.dig(:value),
+            'country_iso2' => row[:countryIso2]&.dig(:value),
+            'country_name' => extract_country_label(row[:country]),
+            'latitude' => extract_lat(row[:coord]),
+            'longitude' => extract_lon(row[:coord])
+          }
+        end
+
+        def extract_country_label(country_binding)
+          return nil unless country_binding
+
+          uri = country_binding[:value].to_s
+          # Use the entity's last URL segment as a placeholder; the human
+          # name comes from the rdfs:label via SERVICE wikibase:label
+          # which we don't include in the query. The dedicated
+          # `unlocode-iso3166` gem is the proper way to resolve a full
+          # country name; this is just a hint.
+          uri.split('/').last
+        end
+
+        def extract_lat(coord_binding)
+          return nil unless coord_binding
+
+          point = coord_binding[:value].to_s
+          match = point.match(/Point\(([-\d.]+)\s+([-\d.]+)/)
+          match && match[2].to_f
+        end
+
+        def extract_lon(coord_binding)
+          return nil unless coord_binding
+
+          point = coord_binding[:value].to_s
+          match = point.match(/Point\(([-\d.]+)\s+([-\d.]+)/)
+          match && match[1].to_f
+        end
+      end
+    end
+  end
+end

data/lib/iata/data.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Iata
+  module Data
+    autoload :Fetcher, "#{__dir__}/data/fetcher"
+  end
+end

data/lib/iata/entry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'coordinates'
+
+module Iata
+  # A single IATA airport entry.
+  #
+  # Stores wire-level fields as `lutaml-model` attributes (so the bundled
+  # JSON can be parsed round-trip) and exposes typed helpers (#coordinates,
+  # #country_name) for ergonomic queries.
+  class Entry < Lutaml::Model::Serializable
+    attribute :code, :string
+    attribute :name, :string
+    attribute :wikidata_id, :string
+    attribute :country_iso2, :string
+    attribute :country_name, :string
+    attribute :latitude, :float
+    attribute :longitude, :float
+
+    def coordinates
+      return Coordinates.new(latitude: nil, longitude: nil) if latitude.nil? && longitude.nil?
+
+      Coordinates.new(latitude: latitude, longitude: longitude)
+    end
+
+    def ==(other)
+      other.is_a?(Entry) && code == other.code
+    end
+
+    def hash
+      code&.hash || super
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def to_s
+      "#{code} #{name}".strip
+    end
+  end
+end

data/lib/iata/loader.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'entry'
+
+module Iata
+  # Parses the bundled IATA airport JSON file into {Entry} instances.
+  #
+  # File format:
+  #
+  #   {
+  #     "_meta": {
+  #       "fetched_at": "2026-07-02T12:00:00Z",
+  #       "source": "Wikidata (P238)",
+  #       "count": 12345
+  #     },
+  #     "PVG": {
+  #       "code": "PVG",
+  #       "name": "Shanghai Pudong International Airport",
+  #       "wikidata_id": "Q86792",
+  #       "country_iso2": "CN",
+  #       "country_name": "China",
+  #       "latitude": 31.1434,
+  #       "longitude": 121.8052
+  #     },
+  #     ...
+  #   }
+  class Loader
+    class << self
+      # @param path [String]
+      # @return [Array<Iata::Entry>]
+      def load_file(path)
+        load_json(File.read(path))
+      end
+
+      # @param json [String]
+      # @return [Array<Iata::Entry>]
+      def load_json(json)
+        parse(JSON.parse(json, symbolize_names: false))
+      end
+
+      # @param data [Hash]
+      # @return [Array<Iata::Entry>]
+      def parse(data)
+        entries = data.is_a?(Hash) ? data.except('_meta') : {}
+        entries.map { |_code, attrs| build_entry(attrs) }
+      end
+
+      private
+
+      def build_entry(attrs)
+        Entry.new(
+          code: attrs['code'],
+          name: attrs['name'],
+          wikidata_id: attrs['wikidata_id'],
+          country_iso2: attrs['country_iso2'],
+          country_name: attrs['country_name'],
+          latitude: attrs['latitude'],
+          longitude: attrs['longitude']
+        )
+      end
+    end
+  end
+end

data/lib/iata/registry.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'loader'
+
+module Iata
+  # In-memory, lazily-indexed registry over a set of {Entry} instances.
+  #
+  # The default registry is loaded from the vendored dataset bundled with the
+  # gem (see {.load_default}). Callers can also construct a registry from any
+  # other source via {.from_entries} or {.load_file}.
+  class Registry
+    include Enumerable
+    extend Forwardable
+
+    attr_reader :entries
+
+    def_delegators :@entries, :size, :count, :to_a, :empty?
+
+    # Map of `#where` filter keys to the Entry attribute they read.
+    # `name` is intentionally NOT in this map — it gets routed through
+    # filter_name so Regexp / substring matching works (see apply_filter).
+    SCALAR_FILTERS = {
+      code: :code,
+      country: :country_iso2,
+      country_iso2: :country_iso2,
+      wikidata_id: :wikidata_id
+    }.freeze
+
+    def initialize(entries = [])
+      @entries = entries.freeze
+    end
+
+    def each(&)
+      @entries.each(&)
+    end
+
+    class << self
+      # Load the bundled dataset shipped inside the gem.
+      # @return [Registry]
+      def load_default
+        from_entries(Loader.load_file(default_data_path))
+      end
+
+      # Load a specific JSON file from disk.
+      # @param path [String]
+      # @return [Registry]
+      def load_file(path)
+        from_entries(Loader.load_file(path))
+      end
+
+      # Build a registry from an existing list of entries.
+      # @param entries [Array<Iata::Entry>]
+      # @return [Registry]
+      def from_entries(entries)
+        new(entries)
+      end
+
+      private
+
+      def default_data_path
+        File.expand_path('data/airports.json', __dir__)
+      end
+    end
+
+    # Exact-code lookup.
+    # @param code [String] 3-letter IATA code (case-insensitive)
+    # @return [Iata::Entry, nil]
+    def find(code)
+      return nil if code.nil?
+
+      by_code[code.to_s.upcase]
+    end
+
+    alias [] find
+
+    # Filter entries by one or more predicates. Scalar filters accept either
+    # a single value or an array (any-of). `name` accepts a String
+    # (case-insensitive equality) or a Regexp.
+    #
+    # @example
+    #   registry.where(country: 'CN')
+    #   registry.where(country: %w[CN HK], name: /international/i)
+    #
+    # @return [Array<Iata::Entry>]
+    def where(filters)
+      filters.reduce(entries) { |scope, (key, value)| apply_filter(scope, key, value) }
+    end
+
+    # All distinct country codes present in the registry, sorted.
+    # @return [Array<String>]
+    def countries
+      entries.map(&:country_iso2).compact.uniq.sort
+    end
+
+    # Count of entries per country.
+    # @return [Hash{String=>Integer}]
+    def counts_by_country
+      entries.each_with_object(Hash.new(0)) { |e, h| h[e.country_iso2] += 1 if e.country_iso2 }
+    end
+
+    private
+
+    def by_code
+      @by_code ||= entries.each_with_object({}) do |e, h|
+        h[e.code.to_s.upcase] = e if e.code
+      end
+    end
+
+    def apply_filter(scope, key, value)
+      if SCALAR_FILTERS.key?(key)
+        filter_scalar(scope, SCALAR_FILTERS.fetch(key), value)
+      elsif key == :name
+        filter_name(scope, value)
+      else
+        raise ArgumentError, "unknown filter: #{key.inspect}"
+      end
+    end
+
+    def filter_scalar(scope, attr_name, value)
+      candidates = Array(value).map { |v| v.to_s.upcase }
+      scope.select do |e|
+        attr_val = e.public_send(attr_name)
+        attr_val && candidates.include?(attr_val.to_s.upcase)
+      end
+    end
+
+    def filter_name(scope, value)
+      scope.select { |e| e.name && name_matches?(e.name, value) }
+    end
+
+    def name_matches?(string, value)
+      value.is_a?(Regexp) ? string.match?(value) : string.casecmp?(value.to_s)
+    end
+  end
+end

data/lib/iata/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Iata
+  VERSION = '0.1.0'
+end

data/lib/iata.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'lutaml/model'
+require 'json'
+
+require_relative 'iata/version'
+
+# Vendored IATA airport code list as a queryable Ruby registry.
+#
+# The data is sourced from Wikidata (property P238, "IATA airport code") and
+# ships inside the gem as a small JSON file so the registry works offline.
+# All entries are loaded lazily on first call to {.registry}.
+module Iata
+  extend SingleForwardable
+
+  class << self
+    # @return [Iata::Registry] the process-wide registry, loaded lazily
+    def registry
+      @registry ||= Registry.load_default
+    end
+
+    # Reset the process-wide registry. Used by specs to swap fixtures.
+    def reset_registry!
+      @registry = nil
+    end
+
+    # The Wikidata query timestamp bundled with this gem version
+    # (UTC ISO8601). nil if the data file lacks this metadata.
+    # @return [String, nil]
+    def source_timestamp
+      @source_timestamp ||= registry.entries.first&.source_timestamp
+    end
+  end
+
+  def_delegators :registry, :find, :where, :each, :size, :count, :countries, :counts_by_country
+
+  autoload :Coordinates, 'iata/coordinates'
+  autoload :Entry, 'iata/entry'
+  autoload :Loader, 'iata/loader'
+  autoload :Registry, 'iata/registry'
+  autoload :Data, 'iata/data'
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: iata
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: |
+  Vendored, offline access to the IATA (International Air Transport
+  Association) airport code list, sourced from Wikidata. Provides a
+  model-driven Ruby registry for looking up airports by IATA code,
+  country, or name.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.adoc
+- lib/iata.rb
+- lib/iata/coordinates.rb
+- lib/iata/data.rb
+- lib/iata/data/airports.json
+- lib/iata/data/fetcher.rb
+- lib/iata/entry.rb
+- lib/iata/loader.rb
+- lib/iata/registry.rb
+- lib/iata/version.rb
+homepage: https://github.com/metanorma/iata
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/metanorma/iata
+  source_code_uri: https://github.com/metanorma/iata
+  bug_tracker_uri: https://github.com/metanorma/iata/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: IATA airport codes as a queryable Ruby registry
+test_files: []