iata 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 176d98285f415c8a930e02e73de40009fcf0d9fd9fae998bbb54fc48de8d908f
+  data.tar.gz: 247d5d264d9304aa94392b7a067ec04862f55f7e2a9db50e6310bd4cf811535a
+SHA512:
+  metadata.gz: e67416a8025bd8f6aa0de9d72aad336d7ad0190d6cb2fb5c2d7beb198182838ad573536923c4643ef132591118fc87af8386c79c15340a2237c698e89cfa9138
+  data.tar.gz: 18d0ac1d2a114631aaf0eb7c3378f60ed5b7b4eb992274883626e4a70ce5d4604dfa36e06dde3a54e644aefe766887f0ff7d2d69a3479880990480277ff8066e

data/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,142 @@
+= iata
+:toc: macro
+:homepage: https://github.com/metanorma/iata
+
+`iata` is a Ruby gem that exposes the IATA (International Air Transport
+Association) airport code list as a queryable in-memory registry.
+
+The dataset is sourced from Wikidata (property P238, "IATA airport code") and
+ships inside the gem as a JSON file so the registry works offline. Loading is
+lazy — the first call to `Iata.registry` parses the bundled JSON once.
+
+== Installation
+
+Ruby 3.1 or newer is required.
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem 'iata'
+----
+
+Or install directly:
+
+[source,sh]
+----
+gem install iata
+----
+
+== Usage
+
+[source,ruby]
+----
+require 'iata'
+
+# Lookup by 3-letter IATA code (case-insensitive)
+Iata.find('PVG').name          # => "Shanghai Pudong International Airport"
+Iata['HKG']                   # => #<Iata::Entry code="HKG" name="Hong Kong International Airport">
+
+# Filters — single value or array (any-of)
+Iata.where(country: 'CN').count       # => ~200 Chinese airports
+Iata.where(country: %w[CN HK]).count  # => airports in China or Hong Kong
+
+# Search by name (Regexp substring or case-insensitive String)
+Iata.where(name: /international/i).count
+Iata.where(name: 'narita').map(&:code)   # => ["NRT"]
+
+# Country listing
+Iata.countries                # => ["AE", "AR", "AT", ..., "ZW"] (200+ codes)
+Iata.counts_by_country.first(5)
+----
+
+=== What's in an Entry
+
+Each `Iata::Entry` exposes the fields the JSON-LD wire format populates:
+
+[cols="1,2", options="header"]
+|===
+|Attribute|Description
+|`code`|3-letter IATA airport code
+|`name`|English-language name
+|`wikidata_id`|Wikidata entity ID (Q-number) for cross-referencing
+|`country_iso2`|ISO 3166-1 alpha-2 country code
+|`country_name`|Display name for the country (from Wikidata)
+|`latitude`, `longitude`|WGS-84 decimal degrees
+|===
+
+[source,ruby]
+----
+entry = Iata.find('PVG')
+
+entry.country          # => "CN"
+entry.country_name     # => "China"
+entry.coordinates      # => #<Iata::Coordinates lat=31.1434 lon=121.8052>
+entry.coordinates.distance_to(Iata.find('HKG').coordinates)  # => ~1255 km
+----
+
+== Data refresh
+
+Wikidata updates daily; new airports are added as they receive IATA codes.
+
+The gem ships two workflows to keep the bundled data fresh:
+
+=== `check-upstream` (scheduled, weekly)
+
+`.github/workflows/check-upstream.yml` runs every Monday and queries
+Wikidata for the current IATA airport count. If it differs from the bundled
+count, the workflow opens a `data-update` issue with a refresh link.
+
+=== `update-data` (manual dispatch)
+
+`.github/workflows/update-data.yml` is what a maintainer runs after the
+weekly check flags drift. It re-queries Wikidata, commits the refreshed
+`lib/iata/data/airports.json` to a branch, and opens a PR. Merging the PR
+does not, by itself, publish a new gem — to ship a new version, trigger
+the `release` workflow with `next_version=patch`.
+
+End-to-end refresh flow:
+
+. `check-upstream` opens issue: "Wikidata IATA count N (bundled: M)"
+. Maintainer runs `update-data` workflow
+. Workflow opens PR with refreshed `airports.json`
+. Maintainer merges the PR
+. Maintainer triggers `release` workflow with `next_version=patch`
+
+Manual local equivalent:
+
+[source,sh]
+----
+bundle exec rake iata:fetch         # refresh bundled airports.json
+----
+
+== Cross-referencing with Wikidata
+
+Each `Entry` carries its Wikidata Q-number so you can link out to the
+authoritative record:
+
+[source,ruby]
+----
+entry = Iata.find('PVG')
+entry.wikidata_id                       # => "Q86792"
+# https://www.wikidata.org/wiki/Q86792
+----
+
+== Development
+
+[source,sh]
+----
+bundle install                       # install dev deps
+bundle exec rake                     # spec + rubocop
+bundle exec rake iata:fetch          # refresh bundled dataset
+----
+
+== Data attribution
+
+Bundled data is sourced from Wikidata (CC0). The IATA organisation does not
+publish its code list under an open license; the Wikidata community
+maintains IATA airport codes as structured data derived from public sources.
+
+== License
+
+BSD-2-Clause. See link:LICENSE[].

data/lib/iata/coordinates.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Iata
+  # Geographic coordinates (WGS-84) for an IATA airport entry.
+  class Coordinates
+    attr_reader :latitude, :longitude
+
+    def initialize(latitude: nil, longitude: nil)
+      @latitude = latitude&.to_f
+      @longitude = longitude&.to_f
+    end
+
+    def to_a
+      [latitude, longitude].compact
+    end
+
+    def ==(other)
+      other.is_a?(Coordinates) &&
+        latitude == other.latitude &&
+        longitude == other.longitude
+    end
+
+    def to_s
+      return '' if latitude.nil? || longitude.nil?
+
+      format('%<lat>.4f %<lon>.4f', lat: latitude, lon: longitude)
+    end
+
+    # Great-circle distance in kilometres to another Coordinates, using
+    # the haversine formula. Returns nil if either side lacks coordinates.
+    def distance_to(other)
+      return nil if latitude.nil? || longitude.nil? ||
+                    other.latitude.nil? || other.longitude.nil?
+
+      earth_radius_km = 6371.0
+      d_lat = (other.latitude - latitude) * (Math::PI / 180)
+      d_lon = (other.longitude - longitude) * (Math::PI / 180)
+      a = (Math.sin(d_lat / 2)**2) +
+          (Math.cos(latitude * (Math::PI / 180)) *
+           Math.cos(other.latitude * (Math::PI / 180)) *
+           (Math.sin(d_lon / 2)**2))
+      2 * earth_radius_km * Math.asin(Math.sqrt(a))
+    end
+  end
+end