gaun 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88b84d5cbf0cef43c15e08df26b16612e43b93179efc25feb17b2f1396dfc964
+  data.tar.gz: ef7fee6cb9d2ff07eafaef78c0be8385933038c1b8eec3388b1b42bb61b1744a
+SHA512:
+  metadata.gz: dbadbd65d1bfc08c3f8038aa89135e26b85dd9cfacdbece309b8b37c55c1299d56071f2ae69a2cd868151cad4c9ac515226371d939dc9be367c19f558f843435
+  data.tar.gz: 163688126b4cd6b1ebe78767b168fdcd422691ad66fb5fbd199e51eece85f9ce97d0928acd54ddc706a9c74922269fabdd3cd5fa7944e80e03f665fa8721e0a5

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.1

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.2.0](https://github.com/open-ews/gaun/compare/v0.1.0...v0.2.0) (2026-03-03)
+
+
+### Features
+
+* Update data ([c8e5790](https://github.com/open-ews/gaun/commit/c8e579075cd7289c9d691320c2a5839fad69e7dc))
+* Update data ([60c5897](https://github.com/open-ews/gaun/commit/60c58974581441a5d2e724b13a9debe4f703bcc1))

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenEWS
+
+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.

data/README.md

@@ -0,0 +1,130 @@
+# gaun (गाउँ)
+
+[![Build](https://github.com/open-ews/gaun/actions/workflows/build.yml/badge.svg)](https://github.com/open-ews/gaun/actions/workflows/build.yml)
+
+**Gaun** is a Ruby library providing structured **geographical and administrative data for Nepal**, including provinces and districts.
+
+> *गाउँ (Gaun)* means **village** in Nepali.
+
+This gem is designed to be lightweight, easy to use, and suitable for applications that need reliable administrative region data—such as Early Warning Systems, humanitarian platforms, civic tech, and data validation pipelines.
+
+---
+
+## Features
+
+* 📍 Administrative geodata for **Nepal**
+* 🗺️ Hierarchical structure (Province → District)
+* 🧩 Easy Ruby API
+* 🚀 No external API dependencies
+* 📦 Designed for offline and embedded use
+* 🧑‍💻 Open source and extensible
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "gaun"
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install gaun
+```
+
+---
+
+## Usage
+
+### Provinces
+
+```ruby
+Gaun::Province.all
+```
+
+```ruby
+province = Gaun::Province.first
+province.name_en
+province.name_ne
+```
+
+### Districts
+
+```ruby
+Gaun::District.all
+```
+
+```ruby
+district = Gaun::District.find { |d| d.name_en == "Bhojpur" }
+district.name_en
+district.name_ne
+```
+
+## Use Cases
+
+* Early warning and disaster response systems
+* Address normalization and validation
+* Beneficiary management systems
+* Government and NGO platforms
+* Offline-first applications
+
+---
+
+## Data Sources
+
+The data in **gaun** is compiled from publicly available Government of Nepal administrative sources and verified datasets where possible.
+
+If you find inaccuracies or updates (e.g. administrative changes), contributions are very welcome.
+
+---
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/open-ews/gaun.git
+cd gaun
+bundle install
+```
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+---
+
+## Contributing
+
+Contributions are welcome!
+
+* Bug reports
+* Data corrections
+* New administrative layers
+* Performance or API improvements
+
+Please open an issue or submit a pull request.
+
+---
+
+## License
+
+This gem is released under the **MIT License**.
+
+---
+
+## Related Projects
+
+* **[baan](https://github.com/open-ews/baan)** – A library containing Geodata for administrative regions in Laos
+* **[pumi](https://github.com/dwilkie/pumi)**– A library containing Geodata for administrative regions in Cambodia

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/data/provinces.yml

@@ -0,0 +1,260 @@
+provinces:
+  - code: "NP-P1"
+    name_en: "Koshi"
+    name_ne: "कोशी"
+    districts:
+      - code: "0101"
+        name_en: "Bhojpur"
+        name_ne: "भोजपुर"
+      - code: "0102"
+        name_en: "Dhankuta"
+        name_ne: "धनकुटा"
+      - code: "0103"
+        name_en: "Ilam"
+        name_ne: "इलाम"
+      - code: "0104"
+        name_en: "Jhapa"
+        name_ne: "झापा"
+      - code: "0105"
+        name_en: "Khotang"
+        name_ne: "खोटाङ"
+      - code: "0106"
+        name_en: "Morang"
+        name_ne: "मोरङ"
+      - code: "0107"
+        name_en: "Okhaldhunga"
+        name_ne: "ओखलढुङ्गा"
+      - code: "0108"
+        name_en: "Panchthar"
+        name_ne: "पाँचथर"
+      - code: "0109"
+        name_en: "Sankhuwasabha"
+        name_ne: "सङ्खुवासभा"
+      - code: "0110"
+        name_en: "Solukhumbu"
+        name_ne: "सोलुखुम्बु"
+      - code: "0111"
+        name_en: "Sunsari"
+        name_ne: "सुनसरी"
+      - code: "0112"
+        name_en: "Taplejung"
+        name_ne: "ताप्लेजुङ"
+      - code: "0113"
+        name_en: "Terhathum"
+        name_ne: "तेह्रथुम"
+      - code: "0114"
+        name_en: "Udayapur"
+        name_ne: "उदयपुर"
+  - code: "NP-P2"
+    name_en: "Madhesh"
+    name_ne: "मधेश"
+    districts:
+      - code: "0201"
+        name_en: "Parsa"
+        name_ne: "पर्सा"
+      - code: "0202"
+        name_en: "Bara"
+        name_ne: "बारा"
+      - code: "0203"
+        name_en: "Rautahat"
+        name_ne: "रौतहट"
+      - code: "0204"
+        name_en: "Sarlahi"
+        name_ne: "सर्लाही"
+      - code: "0205"
+        name_en: "Dhanusha"
+        name_ne: "धनुषा"
+      - code: "0206"
+        name_en: "Siraha"
+        name_ne: "सिराहा"
+      - code: "0207"
+        name_en: "Mahottari"
+        name_ne: "महोत्तरी"
+      - code: "0208"
+        name_en: "Saptari"
+        name_ne: "सप्तरी"
+  - code: "NP-P3"
+    name_en: "Bagmati"
+    name_ne: "बागमती"
+    districts:
+      - code: "0301"
+        name_en: "Sindhuli"
+        name_ne: "सिन्धुली"
+      - code: "0302"
+        name_en: "Ramechhap"
+        name_ne: "रामेछाप"
+      - code: "0303"
+        name_en: "Dolakha"
+        name_ne: "दोलखा"
+      - code: "0304"
+        name_en: "Bhaktapur"
+        name_ne: "भक्तपुर"
+      - code: "0305"
+        name_en: "Dhading"
+        name_ne: "धादिङ"
+      - code: "0306"
+        name_en: "Kathmandu"
+        name_ne: "काठमाडौं"
+      - code: "0307"
+        name_en: "Kavrepalanchok"
+        name_ne: "काभ्रेपलाञ्चोक"
+      - code: "0308"
+        name_en: "Lalitpur"
+        name_ne: "ललितपुर"
+      - code: "0309"
+        name_en: "Nuwakot"
+        name_ne: "नुवाकोट"
+      - code: "0310"
+        name_en: "Rasuwa"
+        name_ne: "रसुवा"
+      - code: "0311"
+        name_en: "Sindhupalchok"
+        name_ne: "सिन्धुपाल्चोक"
+      - code: "0312"
+        name_en: "Chitwan"
+        name_ne: "चितवन"
+      - code: "0313"
+        name_en: "Makwanpur"
+        name_ne: "मकवानपुर"
+  - code: "NP-P4"
+    name_en: "Gandaki"
+    name_ne: "गण्डकी"
+    districts:
+      - code: "0401"
+        name_en: "Baglung"
+        name_ne: "बागलुङ"
+      - code: "0402"
+        name_en: "Gorkha"
+        name_ne: "गोरखा"
+      - code: "0403"
+        name_en: "Kaski"
+        name_ne: "कास्की"
+      - code: "0404"
+        name_en: "Lamjung"
+        name_ne: "लमजुङ"
+      - code: "0405"
+        name_en: "Manang"
+        name_ne: "मनाङ"
+      - code: "0406"
+        name_en: "Mustang"
+        name_ne: "मुस्ताङ"
+      - code: "0407"
+        name_en: "Myagdi"
+        name_ne: "म्याग्दी"
+      - code: "0408"
+        name_en: "Nawalpur"
+        name_ne: "नवलपुर"
+      - code: "0409"
+        name_en: "Parbat"
+        name_ne: "पर्वत"
+      - code: "0410"
+        name_en: "Syangja"
+        name_ne: "स्याङ्जा"
+      - code: "0411"
+        name_en: "Tanahun"
+        name_ne: "तनहुँ"
+  - code: "NP-P5"
+    name_en: "Lumbini"
+    name_ne: "लुम्बिनी"
+    districts:
+      - code: "0501"
+        name_en: "Kapilvastu"
+        name_ne: "कपिलवस्तु"
+      - code: "0502"
+        name_en: "Parasi"
+        name_ne: "परासी"
+      - code: "0503"
+        name_en: "Rupandehi"
+        name_ne: "रूपन्देही"
+      - code: "0504"
+        name_en: "Arghakhanchi"
+        name_ne: "अर्घाखाँची"
+      - code: "0505"
+        name_en: "Gulmi"
+        name_ne: "गुल्मी"
+      - code: "0506"
+        name_en: "Palpa"
+        name_ne: "पाल्पा"
+      - code: "0507"
+        name_en: "Dang"
+        name_ne: "दाङ"
+      - code: "0508"
+        name_en: "Pyuthan"
+        name_ne: "प्युठान"
+      - code: "0509"
+        name_en: "Rolpa"
+        name_ne: "रोल्पा"
+      - code: "0510"
+        name_en: "Eastern Rukum"
+        name_ne: "पूर्वी रुकुम"
+      - code: "0511"
+        name_en: "Banke"
+        name_ne: "बाँके"
+      - code: "0512"
+        name_en: "Bardiya"
+        name_ne: "बर्दिया"
+  - code: "NP-P6"
+    name_en: "Karnali"
+    name_ne: "कर्णाली"
+    districts:
+      - code: "0601"
+        name_en: "Western Rukum"
+        name_ne: "पश्चिमी रुकुम"
+      - code: "0602"
+        name_en: "Salyan"
+        name_ne: "सल्यान"
+      - code: "0603"
+        name_en: "Dolpa"
+        name_ne: "डोल्पा"
+      - code: "0604"
+        name_en: "Humla"
+        name_ne: "हुम्ला"
+      - code: "0605"
+        name_en: "Jumla"
+        name_ne: "जुम्ला"
+      - code: "0606"
+        name_en: "Kalikot"
+        name_ne: "कालिकोट"
+      - code: "0607"
+        name_en: "Mugu"
+        name_ne: "मुगु"
+      - code: "0608"
+        name_en: "Surkhet"
+        name_ne: "सुर्खेत"
+      - code: "0609"
+        name_en: "Dailekh"
+        name_ne: "दैलेख"
+      - code: "0610"
+        name_en: "Jajarkot"
+        name_ne: "जाजरकोट"
+  - code: "NP-P7"
+    name_en: "Sudurpashchim"
+    name_ne: "सुदूर-पश्चिम"
+    districts:
+      - code: "0701"
+        name_en: "Kailali"
+        name_ne: "कैलाली"
+      - code: "0702"
+        name_en: "Achham"
+        name_ne: "अछाम"
+      - code: "0703"
+        name_en: "Doti"
+        name_ne: "डोटी"
+      - code: "0704"
+        name_en: "Bajhang"
+        name_ne: "बझाङ"
+      - code: "0705"
+        name_en: "Bajura"
+        name_ne: "बाजुरा"
+      - code: "0706"
+        name_en: "Kanchanpur"
+        name_ne: "कञ्चनपुर"
+      - code: "0707"
+        name_en: "Dadeldhura"
+        name_ne: "डडेल्धुरा"
+      - code: "0708"
+        name_en: "Baitadi"
+        name_ne: "बैतडी"
+      - code: "0709"
+        name_en: "Darchula"
+        name_ne: "दार्चुला"

data/lib/gaun/administrative_division.rb

@@ -0,0 +1,31 @@
+module Gaun
+  AdministrativeDivision = Data.define(:code, :name_en, :name_ne, :subdivisions, :parent_division) do
+    class << self
+      def all
+        data.values
+      end
+
+      def first
+        all.first
+      end
+
+      def find(...)
+        all.find(...)
+      end
+
+      def [](code)
+        data[code]
+      end
+
+      private
+
+      def data
+        @data ||= cache.data.fetch(self)
+      end
+
+      def cache
+        @cache ||= Cache.new
+      end
+    end
+  end
+end

data/lib/gaun/cache.rb

@@ -0,0 +1,26 @@
+module Gaun
+  class Cache
+    attr_reader :parser
+
+    def initialize(parser: Parser.new)
+      @parser = parser
+    end
+
+    def data
+      @data ||= begin
+        dataset.each_with_object(Hash.new { |h, k| h[k] = {} }) do |(key, dataset), result|
+          dataset.each { result[key][it.code] = it }
+        end
+      end
+    end
+
+    private
+
+    def dataset
+      @dataset ||= begin
+        data = parser.parse
+        { Province => data.provinces, District => data.districts }
+      end
+    end
+  end
+end

data/lib/gaun/district.rb

@@ -0,0 +1,7 @@
+module Gaun
+  class District < AdministrativeDivision
+    def province
+      parent_division
+    end
+  end
+end

data/lib/gaun/parser.rb

@@ -0,0 +1,34 @@
+require "yaml"
+
+module Gaun
+  class Parser
+    DEFAULT_DATA_FILE = Pathname(File.join(__dir__, "..", "data", "provinces.yml")).freeze
+    DEFAULT_ROOT_KEY = "provinces".freeze
+    Result = Data.define(:provinces, :districts)
+
+    attr_reader :data_file, :root_key
+
+    def initialize(**options)
+      @data_file = options.fetch(:data_file) { DEFAULT_DATA_FILE }
+      @root_key = options.fetch(:root_key) { DEFAULT_ROOT_KEY }
+    end
+
+    def parse
+      data = YAML.load_file(data_file).fetch(root_key)
+      districts = []
+      provinces = data.map do |province_data|
+        province = Province.new(parent_division: nil, subdivisions: [], **province_data.transform_keys(&:to_sym).except(:districts))
+
+        province_data.fetch("districts").map do |district_data|
+          district = District.new(parent_division: province, subdivisions: [], **district_data.transform_keys(&:to_sym))
+          province.subdivisions << district
+          districts << district
+        end
+
+        province
+      end
+
+      Result.new(provinces:, districts:)
+    end
+  end
+end

data/lib/gaun/province.rb

@@ -0,0 +1,7 @@
+module Gaun
+  class Province < AdministrativeDivision
+    def districts
+      subdivisions
+    end
+  end
+end

data/lib/gaun/version.rb

@@ -0,0 +1,3 @@
+module Gaun
+  VERSION = "0.2.0"
+end

data/lib/gaun.rb

@@ -0,0 +1,9 @@
+require_relative "gaun/version"
+require_relative "gaun/administrative_division"
+require_relative "gaun/province"
+require_relative "gaun/district"
+require_relative "gaun/cache"
+require_relative "gaun/parser"
+
+module Gaun
+end

data/release-please-config.json

@@ -0,0 +1,16 @@
+{
+  "bootstrap-sha": "96e184a0cb4a3de5aa9ab838c8d0b90b59474f5d",
+  "include-component-in-tag": false,
+  "version-file": "lib/gaun/version.rb",
+  "packages": {
+    ".": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "ruby",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "draft": false,
+      "prerelease": false
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

data/sig/gaun.rbs

@@ -0,0 +1,4 @@
+module Gaun
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: gaun
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- David Wilkie
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Gaun is a Ruby library providing structured geographical and administrative
+  data for Nepal, including provinces and districts.
+  It is designed for offline use in civic tech, humanitarian, and early warning systems.
+email:
+- dwilkie@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".release-please-manifest.json"
+- ".tool-versions"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/data/provinces.yml
+- lib/gaun.rb
+- lib/gaun/administrative_division.rb
+- lib/gaun/cache.rb
+- lib/gaun/district.rb
+- lib/gaun/parser.rb
+- lib/gaun/province.rb
+- lib/gaun/version.rb
+- release-please-config.json
+- sig/gaun.rbs
+homepage: https://github.com/open-ews/gaun
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/open-ews/gaun
+  source_code_uri: https://github.com/open-ews/gaun
+  changelog_uri: https://github.com/open-ews/gaun/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Geographical and administrative data for Nepal
+test_files: []