trackberry-airports 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca7818ec91a88ba3d1c18e8fcb9517f87d89cfc94c937c1909fd816c50877608
+  data.tar.gz: 9973e103fe6303cd960d54db00b117da582830eba75ac969890c11a11c890d12
+SHA512:
+  metadata.gz: f84769f1883adff0d24a33eb84a42852fd141aad7a0d4759e33347d600c1bb094cf6db3a452843f2e194b05edf3741403af6fa48096403616cdfeb24b99dd73e
+  data.tar.gz: 11a2a886ebe1ca31ca2b0ec7d59ed35eff2d84d967988fe2aeb6d8c0ed24bc0764bd06fdbd036ad0900db8496193c04ee2c9ae2f7b0518cedc087c7af16fcf12

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+Data refreshes are minor versions, opened as pull requests by the monthly refresh workflow. Code changes are written here by hand.
+
+## 0.1.1 — 2026-10-26
+
+Published on rubygems.org instead of GitHub Packages. The table is licensed under the ODbL, as a derivative of OpenFlights' database; the code stays MIT.
+
+## 0.1.0 — 2026-10-20
+
+First release: every OurAirports airport with an IATA code, with the city it serves (from OpenFlights), the town it stands in, its position and its ISO 3166-2 subdivision path, and the monthly refresh.

data/LICENSE.txt

@@ -0,0 +1,38 @@
+MIT License
+
+Copyright (c) 2026 Édouard Brière
+
+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 MIT License above covers the code. It does not cover the airport table.
+
+data/airports.csv and data/sources/served_cities.csv contain information from
+OpenFlights (https://openflights.org/data), © OpenFlights contributors, which
+is made available under the Open Database License (ODbL) 1.0:
+https://opendatacommons.org/licenses/odbl/1-0/. Any rights in individual
+contents of the database are licensed under the Database Contents License:
+https://opendatacommons.org/licenses/dbcl/1-0/. Both files are made available
+under the same terms.
+
+The rest of the table comes from public-domain sources: OurAirports
+(https://ourairports.com/data/) for the airports, and Natural Earth
+(https://www.naturalearthdata.com) for the states-and-provinces map that
+places some of them.

data/README.md

@@ -0,0 +1,92 @@
+# trackberry-airports
+
+Every airport with an IATA code (about 9,000), with its name, city, position and ISO 3166-2 subdivision, as a table shipped inside the gem. No network calls.
+
+```ruby
+require "trackberry/airports"
+
+Trackberry::Airports.find("FRA")              # => #<data Trackberry::Airports::Airport iata="FRA", icao="EDDF", ...>
+Trackberry::Airports.city("FRA")              # => "Frankfurt"
+Trackberry::Airports.country("FRA")           # => "DE"
+Trackberry::Airports.coordinates("FRA")       # => { "lat" => 50.0267, "lng" => 8.5584 }
+Trackberry::Airports.subdivision_path("SXB")  # => ["FR-67", "FR-6AE", "FR-GES"]
+```
+
+An unknown code answers `nil` (or `[]` for a path): carriers send city codes ("LON") and codes of airports that have closed, and that is ordinary, not an error.
+
+## Why not the `airports` gem
+
+[`airports`](https://github.com/timrogers/airports) is the established gem for this, and it does the plain lookup well. This one exists for what it does not do:
+
+- **Fresh data.** `airports` is built from OpenFlights, which stopped updating in 2019, and adds the airports opened since by hand (`BER`, `HYD`). This one is built from OurAirports, which is still maintained, and rebuilt every month behind checks that stop a bad download from shipping.
+- **Where the airport is, inside its country.** `airports` gives the country as a name ("United Kingdom"). This one gives the ISO 3166-2 country code and subdivision path, which is what a regional holiday calendar or a customs rule keys on.
+- **Numbers as numbers.** Coordinates are floats, not strings.
+
+`airports` has time zones; this one does not. If that is all you need, use it.
+
+## Subdivisions
+
+`subdivision_path` is the ISO 3166-2 code of the area the airport is in and every code above it, most specific first, the same shape [seaports](https://github.com/Trackberry/seaports) gives for a port. Hand it to a holiday calendar that matches a holiday at any level of the path, such as Trackberry's own (not published):
+
+```ruby
+Trackberry::Holidays.holiday?(Date.new(2027, 5, 27), Trackberry::Airports.subdivision_path("MUC"))  # => true, Corpus Christi in Bavaria
+Trackberry::Holidays.holiday?(Date.new(2027, 5, 27), Trackberry::Airports.subdivision_path("HAM"))  # => false, not in Hamburg
+```
+
+Where the code comes from, best first (the `subdivision_source` column says which):
+
+| Source | Airports | Example |
+| --- | --- | --- |
+| `override`: a reviewed list, `data/sources/subdivision_overrides.csv` | 0 | |
+| `boundaries`: the airport's position on Natural Earth's states-and-provinces map | 831 | Strasbourg `FR-67`, Beijing `CN-BJ` |
+| `ourairports`: OurAirports' `iso_region` | 7,903 | Frankfurt `DE-HE`, Hamburg `DE-HH` |
+
+The map is used two ways:
+- **To go below OurAirports.** OurAirports stops at the top level: Grand Est for Strasbourg. When the map finds an area inside that code, the airport gets the longer path: Bas-Rhin, inside the European Collectivity of Alsace, inside Grand Est. Some rules are kept at those levels. Alsace and Moselle have two public holidays the rest of France does not, which a calendar would key on `FR-6AE` and `FR-57`; Nager.Date does not list them yet. When the map disagrees with OurAirports, OurAirports wins. The map answers with the area containing the airport, and only for an airport outside every area (built on reclaimed land, past the drawn coastline) with the nearest one within 10 km.
+- **To fill a gap.** OurAirports still writes some codes ISO has replaced, such as China's pre-2017 numeric ones, and `XX-U-A` for "unassigned".
+
+8,734 of 9,051 airports are placed. The 317 left have no subdivision because both sources still use codes ISO has retired (Poland, Norway, South Africa, Czechia, Kazakhstan) or the territory has none (French Polynesia, Puerto Rico). None of them is in a country whose public holidays differ by region, so a holiday lookup by country is complete for them.
+
+Every code is checked against ISO 3166-2 when the table is built. The ISO hierarchy and the map lookup are seaports' `Seaports::Subdivisions` and `Seaports::Boundaries`, used by the build only: the gem itself depends on neither.
+
+## Cities
+
+`city` is the city the airport serves, the one a carrier, a courier or a person names: "Brussels", "Athens", "Leipzig". `municipality` is the town it stands in, as OurAirports gives it: "Zaventem", "Spata-Artemida", "Schkeuditz". They are the same for most airports.
+
+The served city comes from [OpenFlights](https://openflights.org/data) for the 6,000 airports it lists. OpenFlights stopped updating in 2019, so its cities were extracted once into `data/sources/served_cities.csv` by `script/extract_served_cities.rb`, from a pinned commit. A city carries over only when OpenFlights puts the airport within 50 km of OurAirports' position, so a code IATA has since given to another airport does not bring the old city with it. Every other airport takes its municipality, without a trailing note in brackets: "Helsinki", not "Helsinki (Vantaa)".
+
+The subdivision always follows where the airport is, not the city it serves: Cincinnati's airport is in Kentucky (`US-KY`), not Ohio.
+
+## Data
+
+[OurAirports](https://ourairports.com/data/) (public domain), filtered to airports with an IATA code that are not closed. When two rows share a code, the one with scheduled flights wins, then the larger airport. Coordinates are rounded to four decimal places (about ten metres).
+
+Served cities: [OpenFlights](https://openflights.org/data), © OpenFlights contributors, available under the [Open Database License](https://opendatacommons.org/licenses/odbl/1-0/).
+
+## License
+
+The code is MIT. The table (`data/airports.csv`) is a derivative of OpenFlights' database, so it is under the [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/): a database you build from it and use publicly has to credit OpenFlights and be offered under the ODbL too. Using the gem to look airports up does not. See `LICENSE.txt`.
+
+## Refresh
+
+`.github/workflows/refresh.yml` runs on the 3rd of every month:
+
+1. `rake airports:refresh` downloads OurAirports, the ISO 3166-2 list and the Natural Earth map, and rebuilds `data/airports.csv`.
+2. `Trackberry::Airports::Diff` checks the result before anything ships:
+   - at least 8,500 airports;
+   - the table shrinks by no more than 2%;
+   - airports with a subdivision fall by no more than 2%;
+   - no more than 2% move to another principal subdivision;
+   - two dozen major airports (FRA, LHR, JFK, LIM…) are all present;
+   - fourteen of them, in countries whose holidays differ by region, keep their principal subdivision (FRA in `DE-HE`, MUC in `DE-BY`…), because one country's codes breaking stays under the percentage caps.
+3. If it passes, the job opens a pull request listing every added, removed, renamed, moved, re-citied and resubdivided airport, and starts CI on it. If it fails, or a download fails, it opens an issue instead.
+
+Merging a refresh bumps the minor version, and `.github/workflows/release.yml` publishes it to [rubygems.org](https://rubygems.org/gems/trackberry-airports).
+
+To rebuild from files already on disk: `bundle exec rake "airports:refresh[airports.csv,iso_3166-2.json,admin1.geojson]"`.
+
+## Install
+
+```ruby
+gem "trackberry-airports", "~> 0.1", require: "trackberry/airports"
+```