psgc-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d1fd4a6936426a2a2efc694827ffd4d5fd0d33e13a8933ff5df64626edfb1ab
+  data.tar.gz: 552c45ca68904de0614b5d474ba1e055e4b3ef4139b80d6ecad0314de6b97a3c
+SHA512:
+  metadata.gz: e4e8fd85a964fefa515233771a7551fe3dbd5070ab583aa9d8e45caefd76d084816e5fa46d6f0316c77485ae2da9b3dc5ff77b5594ac982d1d8692e5c74bbd7e
+  data.tar.gz: 7734822468ff709b6b093162220773ce207619ac5453481c4b58a9abeab4e2a555b75ea03533980811a638f7e99570d9e66d6f02ffe27622ac155da14bab98e8

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests (`rake test`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## Data Updates
+
+When PSA releases new PSGC data:
+
+1. Download the Excel file from https://psa.gov.ph/classification/psgc/
+2. Run `rake "data:parse[data/PSGC-Filename.xlsx]"`
+3. Commit the updated JSON files

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Al Kevin Tan
+
+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,56 @@
+# Psgc
+
+A Ruby gem providing up-to-date Philippine geographic data from the PSA (Philippine Statistics Authority). Includes Philippine Standard Geographic Codes (PSGC) for regions, provinces, cities/municipalities, and barangays.
+
+## Installation
+
+```bash
+gem install psgc-rb
+```
+
+Or add to Gemfile:
+
+```ruby
+gem "psgc-rb"
+```
+
+## Usage
+
+```ruby
+require "psgc"
+
+# Get all regions
+Psgc.regions
+# => [{:code=>"1300000000", :name=>"National Capital Region (NCR)"}, ...]
+
+# Get all provinces
+Psgc.provinces
+# => [{:code=>"1400100000", :name=>"Abra", :region_code=>"14"}, ...]
+
+# Get all cities and municipalities
+Psgc.cities_municipalities
+# => [{:code=>"1400101000", :name=>"Bangued", :province_code=>"1400"}, ...]
+
+# Get all barangays
+Psgc.barangays
+# => [{:code=>"1400101001", :name=>"Bagtayan", :city_municipality_code=>"1400101000"}, ...]
+```
+
+## Data Source
+
+Data is sourced from the PSA PSGC Publication Datafile, released quarterly.
+- URL: https://psa.gov.ph/classification/psgc/
+- Current data: 1Q 2026
+
+To update data:
+1. Download the latest Excel file from PSA
+2. Run `rake "data:parse[path/to/file.xlsx]"`
+3. Commit the updated JSON files
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "json"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+
+namespace :data do
+  PSA_URL = "https://psa.gov.ph/classification/psgc/"
+
+  desc "Fetch latest PSGC data from PSA"
+  task :fetch do
+    puts "Fetching PSGC data from #{PSA_URL}"
+    puts "Note: Manual download required - PSA provides Excel files"
+    puts "Download: #{PSA_URL}"
+  end
+
+  desc "Parse PSGC Excel file and generate JSON fixtures"
+  task :parse, [:file] do |_t, args|
+    file = args[:file] || "data/PSGC-1Q-2026-Publication-Datafile.xlsx"
+    unless File.exist?(file)
+      abort "Excel file not found: #{file}. Run 'rake data:fetch' to download."
+    end
+
+    puts "Parsing #{file}..."
+    puts "(Using Python openpyxl)"
+
+    parse_with_python(file)
+
+    puts "Done."
+  end
+
+  def parse_with_python(file)
+    script = <<~PYTHON
+      import openpyxl
+      import json
+      import sys
+
+      wb = openpyxl.load_workbook(sys.argv[1])
+      ws = wb["PSGC"]
+
+      regions = []
+      provinces = []
+      cities_municipalities = []
+      barangays = []
+
+      for row in ws.iter_rows(min_row=2, values_only=True):
+          code = row[0]
+          name = row[1]
+          level = row[3]
+          if not code or not name or not level:
+              continue
+
+          code = str(code).strip()
+          name = str(name).strip()
+
+          entry = {"code": code, "name": name}
+
+          if level == "Reg":
+              regions.append(entry)
+          elif level == "Prov":
+              entry["region_code"] = code[:2]
+              provinces.append(entry)
+          elif level in ("City", "Mun", "SubMun"):
+              entry["province_code"] = code[:4]
+              cities_municipalities.append(entry)
+          elif level == "Bgy":
+              entry["city_municipality_code"] = code[:6]
+              barangays.append(entry)
+
+      with open("data/regions.json", "w") as f:
+          json.dump(regions, f, indent=2)
+      with open("data/provinces.json", "w") as f:
+          json.dump(provinces, f, indent=2)
+      with open("data/cities_municipalities.json", "w") as f:
+          json.dump(cities_municipalities, f, indent=2)
+      with open("data/barangays.json", "w") as f:
+          json.dump(barangays, f, indent=2)
+
+      print(f"Generated {len(regions)} regions, {len(provinces)} provinces, {len(cities_municipalities)} cities/municipalities, {len(barangays)} barangays")
+    PYTHON
+
+    py_pid = spawn("python3", "-c", script, file)
+    _, status = Process.wait2(py_pid)
+    raise "Python parsing failed" unless status.success?
+  end
+end
+
+desc "Update PSGC data (fetch + parse)"
+task update: ["data:fetch", "data:parse"]