JpLocalGov

Convert local government code based on JIS X 0402 to local government name in Japan.
Reference(Japanese): 全国地方公共団体コード - Wikipedia

Issues

If you find any bugs or concerns, or have suggestions for new features, please feel free to add them as an GitHub Issue!

There are issue templates for bug and feature. If neither, please use the blank template.

Special Thanks

This gem is based on and inspired by chocoby/jp_prefecture.
And I referenced kufu/jpostcode-data for the method of data acquisition.

Thanks!😁

Installation

Add this line to your application's Gemfile:

gem 'jp_local_gov'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install jp_local_gov

Usage

Requirement

require 'jp_local_gov'

Search Local Government by Code

Provide local government code to search local government's data.
Only a String can be used for 'code'.

chiyodaku = JpLocalGov.find("131016")
# => #<JpLocalGov::LocalGov:0x00007fe706a8f148 @code="131016", @prefecture_code="13", @prefecture="東京都", @prefecture_kana="トウキョウト", @city="千代田区", @city_kana="チヨダク", @prefecture_capital=false>
chiyodaku.code
# => "131016"
chiyodaku.prefecture_code
# => "13"
chiyodaku.prefecture
# => "東京都"
chiyodaku.prefecture_kana
# => "トウキョウト"
chiyodaku.city
# => "千代田区"
chiyodaku.city_kana
# => "チヨダク"
chiyodaku.prefecture_capital
# => false

About prefecture capital: List of capitals in Japan - Wikipedia

Filtered Search

Use the where to enable AND searches with multiple conditions(Hash).
This search function is an exact match search.

misato = JpLocalGov.where(city: "美郷町")
# => [#<JpLocalGov::LocalGov:0x00007fb1c594cb08 @code="054348", @prefecture_code="05", @prefecture="秋田県", @prefecture_kana="アキタケン", @city="美郷町", @city_kana="ミサトチョウ", @prefecture_capital=false>, #<JpLocalGov::LocalGov:8 @code="324485", @prefecture_code="32", @prefecture="島根県", @prefecture_kana="シマネケン", @city="美郷町", @city_kana="ミサトチョウ", @prefecture_capital=false>, #<JpLocalGov::LocalGov:0x00007fb1c1a3ce40 @code="454311", @prefecture="宮崎県", @prefecture_kana="ミヤザキケン", @city="美郷町", @city_kana="ミサトチョウ", @prefecture_capital=false>]
misato.map { "#{_1.prefecture}:#{_1.city}" }
# => ["秋田県:美郷町", "島根県:美郷町", "宮崎県:美郷町"]

JpLocalGov.where(prefecture: "東京都", prefecture_capital: true)
# => [#<JpLocalGov::LocalGov:0x00007fb1c219e418 @code="131041", @prefecture_code="13", @prefecture="東京都", @prefecture_kana="トウキョウト", @city="新宿区", @city_kana="シンジュクク", @prefecture_capital=true>]

JpLocalGov.where(prefecture: "東京")
# => nil
# Exact match search. You should specified "東京都" instead of "東京".

The following attributes can be specified for the condition.

Attributes	Type	Examples
code	String	"131016"
prefecture_code	String	"13"
prefecture	String	"東京都"
prefecture_kana	String	"トウキョウト"
city	String	"千代田区"
city_kana	String	"チヨダク"
prefecture_capital	true or false	false

All data

You can get all local governments using JpLocalGov.all

JpLocalGov.all
# =>  [#<JpLocalGov::LocalGov:0x00007fdf3a9c6758 @code="011002", @prefecture_code="01", @prefecture="北海道", @prefecture_kana="ホッカイドウ", @city="札幌市na="サッポロシ", @prefecture_capital=true>, #<JpLocalGov::LocalGov:0x00007fdf3a9c6730 @code="011011",...

Random data

You can create random code, city, city_kana, prefecture, prefecture_code and prefecture_kana by using JpLocalGov::Random.

JpLocalGov::Random.code
# => "281077"
JpLocalGov::Random.city
# => "大島町"
JpLocalGov::Random.city_kana
# => "チュウオウシ"
JpLocalGov::Random.prefecture
# => "青森県"
JpLocalGov::Random.prefecture_code
# => "46"
JpLocalGov::Random.prefecture_kana
# => "ヒョウゴケン"

It is useful to random factory data in rails app for example.

Usage on Rails (ActiveRecord)

Include JpLocalGov to Model which ActiveRecord::Base inherited.

# app/models/insurance_fee.rb:
class InsuranceFee < ActiveRecord::Base
  # local_gov_code:String

  include JpLocalGov
  jp_local_gov :local_gov_code
end

By JpLocalGov included, local_government method will be generated:

insurance_fee = InsuranceFee.new
insurance_fee.local_gov_code = "131016"
insurance_fee.local_government.city
# => "千代田区"

In Migration file, set local_gov_code column type to string.

class AddLocalGovCodeToInsuranceFees < ActiveRecord::Migration
  def change
    add_column :insurance_fees, :local_gov_code, :string
  end
end

Validation

You can use JpLocalGov.valid_code?(local_gov_code) in validate method.

class InsuranceFee < ApplicationRecord
  include JpLocalGov
  jp_local_gov :local_gov_code

  validate :valid_code?

  def valid_code?
    unless JpLocalGov.valid_code?(local_gov_code)
      errors.add(:local_gov_code, "is not valid code")
    end
  end
end

This method inspect code by check digits defined in JISX0402. (And also check code is String.)

View Template

Use collection_select to generate selector in view:

f.collection_select :local_gov_code, JpLocalGov.all, :code, :city # e.g. code: 131016, city: "千代田区"

Development

Steps

1. Fork it -> git clone https://github.com/IkumaTadokoro/jp_local_gov/fork
2. Run bin/setup to install dependencies
3. Create your feature branch
4. Implement feature and run bin/test, bin/lint, bin/steep to check your implementation
5. Push to the branch
6. Create a new Pull Request

Commands

Command	Details
bin/console	An interactive prompt that will allow you to experiment
bin/generate_rbs	Create rbs file in /sig for new ruby files in /lib
bin/test	Run rspec via Appraisal. To specify the version, use bin/test <version>（e.g. bin/test rails61）
bin/lint	Run Rubocop
bin/steep	Run steep stats and steep check

Running Test via JetBrains IDE (e.g. RubyMine)

This gem use 'Appraisal' to inspect several versions of Rails.

So you should run rspec by bundle exec appraisal rspec and you won't be able to run spec via IDE (only run via your terminal).

If you use JetBrains IDE and you want to run spec via IDE, try to configure the following steps.

1. Open 「Edit Configurations...」
2. Open 「Edit Configuration templates...」
3. Select 「RSpec」
4. Check 「Use custom RSpec runner script:」 and fill the script with [CLONE_DIR]/bin/spec_runner.rb
5. Click「APPLY」, then you can run spec via IDE!!🎉

If you have already run spec via IDE before configuration, delete the existing configuration and try to configure the above steps

Update local government data

This Gem update local government data (format: JSON) automatically once a month by GitHub Actions.

• Data source: https://www.soumu.go.jp/denshijiti/code.html
• Output: https://github.com/IkumaTadokoro/jp_local_gov/tree/main/data/json

Fetch script is written in Ruby and Rake Task. So you can run update data at local by the following command.

bundle exec rake jp_local_gov:data:update_all

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/IkumaTadokoro/jp_local_gov. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Spell Checking

We are running misspell which is mainly written in Golang to check spelling with GitHub Actions. Correct commonly misspelled English words quickly with misspell. misspell is different from most other spell checkers because it doesn't use a custom dictionary. You can run misspell locally against all files with:

$ find . -type f | xargs ./misspell -error

Notable misspell help options or flags are:

• -i string: ignore the following corrections, comma separated
• -w: Overwrite file with corrections (default is just to display)

We also run codespell with GitHub Actions to check spelling and codespell runs against a small custom dictionary. codespell is written in Python and you can run it with:

$ codespell --ignore-words=codespell.txt

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the JpLocalGov project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.