ThaiGeodata

A lightweight Ruby gem providing Thailand’s official administrative geography data (provinces, districts, subdistricts) and postal codes in a Ruby-friendly API.

ไลบรารี Ruby ขนาดเล็กที่ให้ข้อมูลภูมิศาสตร์ของประเทศไทย (จังหวัด, อำเภอ, ตำบล) พร้อมรหัสไปรษณีย์ ผ่าน API ที่ใช้งานง่าย

• Fast lookups of provinces, districts, subdistricts, and postal codes
• Dual-language (Thai & English) support for data values
• Zero external dependencies (only stdlib JSON)
• Lazy–loaded and cached in memory

Add to your application’s Gemfile:

gem "thai_geodata"

Then run:

bundle install

Or install directly:

gem install thai_geodata

require "thai_geodata"

ThaiGeodata.provinces.each do |prov|
  puts "#{prov['provinceCode']}: #{prov['provinceNameTh']} (#{prov['provinceNameEn']})"
end
# => 10: กรุงเทพมหานคร (Bangkok)
#    50: เชียงใหม่ (Chiang Mai)

# English or Thai name
prov = ThaiGeodata.find_province("Chiang Mai")
puts prov['provinceCode']  # => 50

# Thai name
prov_th = ThaiGeodata.find_province(10)
puts prov_th['provinceNameTh']  # => "กรุงเทพมหานคร"

dists = ThaiGeodata.districts_for_province(10)
puts dists.map { |d| d['districtNameTh'] }.join(", ")
# => พระนคร, ดุสิต, …

subs = ThaiGeodata.subdistricts_for_district("Phra Nakhon")
puts subs.map { |s| s['subdistrictNameTh'] }
# => พระบรมมหาราชวัง, วังบูรพาภิรมย์, …

pc = ThaiGeodata.postal_code_for_subdistrict("พระบรมมหาราชวัง")
puts pc  # => 10200

results = ThaiGeodata.geography.select { |row| row['postalCode'] == 10200 }
results.each do |row|
  puts "#{row['provinceNameTh']} > #{row['districtNameTh']} > #{row['subdistrictNameTh']} (#{row['postalCode']})"
end
# => กรุงเทพมหานคร > พระนคร > พระบรมมหาราชวัง (10200)

• ThaiGeodata.provinces → Array of province hashes
• ThaiGeodata.districts → Array of district hashes
• ThaiGeodata.subdistricts → Array of subdistrict hashes
• ThaiGeodata.geography → Combined array of all records
• find_province(code_or_name) → Single province hash or nil
• find_district(code_or_name) → Single district hash or nil
• find_subdistrict(code_or_name) → Single subdistrict hash or nil
• districts_for_province(code_or_name) → Array of districts
• subdistricts_for_district(code_or_name) → Array of subdistricts
• postal_code_for_subdistrict(code_or_name) → Integer or nil
• location_path_for_subdistrict(code_or_name) → {province:, district:, subdistrict:} or nil

All methods memoize their data on first call.

Geographical data licensed under MIT and maintained by the Thailand Geography JSON project.

1. Fork the repo
2. Create or update JSON files under lib/thai_geodata/data/
3. Write tests in test/ and ensure rake test passes
4. Submit a PR with a clear description of changes

© 2025 Chayut Orapinpatipat Released under the MIT License. See LICENSE.txt for details.