Pumi

Pumi (ភូមិ pronounced Poom, which means Village in Khmer) is an Open Source library containing Geodata for administrative regions in Cambodia including Provinces, Districts, Communes and Villages.

Demo and API

A JSON API is available to if you're not using Ruby or if you just don't want to install a local copy of the data. The API Start Page also shows a Demo of a UI for for entering any location in Cambodia.

Usage

Rails

Using Pumi with Rails gives you some javascript helpers as well as an API to filter and select Provinces (ខេត្ត), Districts (ស្រុក / ខណ្ឌ), Communes (ឃុំ / សង្កាត់) and Villages (ភូមិ) in both latin and Khmer as seen below and in the Pumi API Start Page

To use Pumi with Rails first, require "pumi/rails" in your Gemfile:

gem "pumi", require: "pumi/rails"

Next, mount the Pumi routes in config/routes

# config/routes.rb

mount Pumi::Engine => "/pumi"

Then require the pumi javascript in app/assets/javascripts/application.js

//= require jquery
//= require pumi

Note: jquery is a dependency of pumi and must be required before pumi

Finally setup your view with selects for the province, district, commune and village. See the dummy application for an example and refer to the configuration below.

Plain Ol' Ruby

Rails is not a dependency of Pumi so you can use it with Plain Ol' Ruby if you don't need the javascript and route helpers.

Add this line to your application's Gemfile:

gem "pumi"

And then execute:

$ bundle

  require 'pumi'

  # Working with Provinces (ខេត្ត)

  # Get all provinces
  Pumi::Province.all

  # Find a province by id
  Pumi::Province.find_by_id("12")

  # Find a province by its latin name
  Pumi::Province.where(name_latin: "Phnom Penh")

  # Find a province by its Khmer name
  Pumi::Province.where(name_km: "បន្ទាយមានជ័យ")

  # Get a list of links for a province
  province = Pumi::Province.find_by_id("12")
  province.links
  # => {:wikipedia=>"https://en.wikipedia.org/wiki/Phnom_Penh"}

  # Get Geodata
  province.geodata
  # => #<struct Pumi::Geodata lat="11.5730391", long="104.857807", bounding_box=["11.4200852", "11.7349524", "104.7204046", "105.0440261"]>

  # Get ISO3166_2 code
  province.iso3166_2
  # => "KH-12"

  # Working with Districts (ស្រុក / ខណ្ឌ)

  # Get all districts
  Pumi::District.all

  # Get all districts by province_id
  Pumi::District.where(province_id: "12")

  # Find district by its Khmer name and Province ID
  district = Pumi::District.where(province_id: "12", name_km: "ចំការមន").first

  # Return the district's province name in latin
  district.province.name_latin
  # => "Phnom Penh"

  # Return the district's province name in UNGEGN
  district.province.name_ungegn
  # => "Phnum Pénh"

  # Working with Communes (ឃុំ / សង្កាត់)

  # Get all communes by district_id
  Pumi::Commune.where(district_id: "1201")

  # Find a commune by its latin name and District ID
  commune = Pumi::Commune.where(district_id: "1201", name_latin: "Tonle Basak").first

  # Return the commune's district name in Khmer
  commune.district.name_km
  # => "ចំការមន"

  # Return the commune's province name in Khmer
  commune.province.name_km
  # => "ភ្នំពេញ"

  # Working with Villages (ភូមិ)

  # Get all villages by commune_id
  Pumi::Village.where(commune_id: "010201")

  # Find a village by it's Khmer name and Commune ID
  village = Pumi::Village.where(commune_id: "010201", name_km: "អូរធំ").first

  # Return the village's commune name in latin
  village.commune.name_latin
  # => "Banteay Neang"

  # Return the village's district name in Khmer
  village.district.name_km
  => "មង្គលបូរី"

  # Return the village's province name in Khmer
  village.province.name_km
  # => "បន្ទាយមានជ័យ"

  # Get the villages address in Latin
  village.address_latin
  # => "Phum Ou Thum, Khum Banteay Neang, Srok Mongkol Borei, Khaet Banteay Meanchey"

  # In English
  village.address_en
  # => "Ou Thum Village, Banteay Neang Commune, Mongkol Borei District, Banteay Meanchey Province"

  # In Khmer
  village.address_en
  # => "ភូមិអូរធំ ឃុំបន្ទាយនាង ស្រុកមង្គលបូរី ខេត្តបន្ទាយមានជ័យ"

Configuration

The following html5 data-attributes can be used to configure Pumi.

data-pumi-select-id

A unique id of the select input which is looked up by data-pumi-select-target

data-pumi-select-target

The data-pumi-select-id of the select input in which to update the options when this input is changed

data-pumi-select-collection-url

The url in which to lookup the values for this select input. If this option is not given then no ajax request will be made. Hint: You can use the Rails url helpers here e.g. pumi.districts_path(:province_id => "FILTER")

data-pumi-select-collection-url-filter-interpolation-key

The key value to interpolate for filtering via the collection url. E.g. if you set data-pumi-select-collection-url="/pumi/districts?province_id=FILTER", then a value of "FILTER" here will replace the collection URL with the value of the select input which this select input is the target of

data-pumi-select-collection-label-method

The name of the label method. E.g. data-pumi-select-collection-label-method="name_en" will display the labels in Latin or data-pumi-select-collection-label-method="name_km" will display the labels in Khmer

data-pumi-select-collection-value-method

The name of the value method. E.g. data-pumi-select-collection-value-method="id" will set the value of the select input to the Pumi of the location

data-pumi-select-disabled-target

The target of a parent selector in which to apply the class data-pumi-select-disabled-class to when the input is disabled

data-pumi-select-disabled-class

When the input is disabled this class will be applied to data-pumi-select-disabled-target

data-pumi-select-populate-on-load

Set to true to populate the select input with options on load. Default: false

data-pumi-select-has-hidden-value

Set to true if you also have a hidden field for this input with the same name. Useful for remembering the selection across page reloads. Default: false

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dwilkie/pumi.