basho 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +7 -0
- data/README.ja.md +313 -0
- data/README.md +74 -72
- data/data/prefectures.json +1 -1
- data/lib/basho/region.rb +2 -1
- data/lib/basho/version.rb +1 -1
- metadata +6 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e38e0a84ecc6f82fccd684a40e4cc052a937d0196aceb89721c0644ff4909e45
|
|
4
|
+
data.tar.gz: dea2597db16fb5da4dac29a88dceeff6a66a9721c260a30836abc0eb88594657
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 747ea39aae2cd61adbb472e23d0e76a5dd8201781eb13114c13cf7d7b3c9723029a978def0567a735522607287cb0ba2bd9314f372b7e9a295ce213ddf17b900
|
|
7
|
+
data.tar.gz: 80ea60f18441c2ebca630a20ac341f2d81e84f71d6fec09e88abacc74fe7a21003b5647bd64b2609d8518fd746b2db91b2bb1b1a7f0f6d3009f7685ba130acdd
|
data/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.1.2] - 2026-02-08
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- 沖縄県を九州地方から分離し「沖縄」地方として独立(8地方区分 → 9地方区分)
|
|
13
|
+
|
|
8
14
|
## [0.1.0] - 2026-02-08
|
|
9
15
|
|
|
10
16
|
### Added
|
|
@@ -20,4 +26,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
20
26
|
- GitHub Actions CI(Ruby 3.2/3.3/3.4)
|
|
21
27
|
- 月次データ自動更新ワークフロー
|
|
22
28
|
|
|
29
|
+
[0.1.2]: https://github.com/wagai/basho/releases/tag/v0.1.2
|
|
23
30
|
[0.1.0]: https://github.com/wagai/basho/releases/tag/v0.1.0
|
data/README.ja.md
ADDED
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
[English](README.md)
|
|
2
|
+
|
|
3
|
+
# Basho
|
|
4
|
+
|
|
5
|
+
日本の住所データ(都道府県・市区町村・郵便番号・地方区分)を統一的に扱うRuby gem。
|
|
6
|
+
|
|
7
|
+
## なぜ作ったか
|
|
8
|
+
|
|
9
|
+
日本の住所まわりは扱いが面倒です。
|
|
10
|
+
|
|
11
|
+
- 郵便番号から住所を引きたいだけなのに、CSVを自前でパースしてDBに入れる必要がある
|
|
12
|
+
- 都道府県・市区町村のマスタデータを持つためにマイグレーションを書かされる
|
|
13
|
+
- 郵便番号の自動入力、都道府県→市区町村の連動セレクトは毎回同じコードを書いている
|
|
14
|
+
- 既存gemはRails依存が強い、データが古い、Hotwire非対応、など
|
|
15
|
+
|
|
16
|
+
Bashoはこれらをまとめて解決します。
|
|
17
|
+
|
|
18
|
+
- **DBマイグレーション不要** — 全データをJSON同梱。`gem install`だけで使える
|
|
19
|
+
- **ActiveRecord統合** — `include Basho` + 1行のマクロで郵便番号→住所の自動保存
|
|
20
|
+
- **Hotwire対応** — 郵便番号自動入力・カスケードセレクトをビルトインEngine提供
|
|
21
|
+
- **軽量** — `Data.define`によるイミュータブルモデル、遅延読み込み、外部依存なし
|
|
22
|
+
|
|
23
|
+
## 対応バージョン
|
|
24
|
+
|
|
25
|
+
- Ruby 3.2 / 3.3 / 3.4 / 4.0
|
|
26
|
+
|
|
27
|
+
## インストール
|
|
28
|
+
|
|
29
|
+
```ruby
|
|
30
|
+
# Gemfile
|
|
31
|
+
gem "basho"
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
bundle install
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## クイックスタート
|
|
39
|
+
|
|
40
|
+
### 郵便番号から住所を引く
|
|
41
|
+
|
|
42
|
+
```ruby
|
|
43
|
+
postal = Basho::PostalCode.find("154-0011").first
|
|
44
|
+
postal.prefecture_name # => "東京都"
|
|
45
|
+
postal.city_name # => "世田谷区"
|
|
46
|
+
postal.town # => "上馬"
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### モデルで郵便番号→住所を自動保存
|
|
50
|
+
|
|
51
|
+
```ruby
|
|
52
|
+
class User < ApplicationRecord
|
|
53
|
+
include Basho
|
|
54
|
+
basho_postal :postal_code,
|
|
55
|
+
prefecture: :pref_name,
|
|
56
|
+
city: :city_name,
|
|
57
|
+
town: :town_name
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
user = User.new(postal_code: "154-0011")
|
|
61
|
+
user.save
|
|
62
|
+
user.pref_name # => "東京都"
|
|
63
|
+
user.city_name # => "世田谷区"
|
|
64
|
+
user.town_name # => "上馬"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 都道府県・市区町村を検索
|
|
68
|
+
|
|
69
|
+
```ruby
|
|
70
|
+
Basho::Prefecture.find(13).name # => "東京都"
|
|
71
|
+
Basho::Prefecture.where(region: "関東") # => 7件
|
|
72
|
+
Basho::City.find("131016").name # => "千代田区"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## 使い方
|
|
76
|
+
|
|
77
|
+
### Prefecture(都道府県)
|
|
78
|
+
|
|
79
|
+
```ruby
|
|
80
|
+
Basho::Prefecture.find(13) # コードで検索
|
|
81
|
+
Basho::Prefecture.find(name: "東京都") # 名前で検索
|
|
82
|
+
Basho::Prefecture.all # 全47件
|
|
83
|
+
Basho::Prefecture.where(region: "関東") # 地方で絞り込み
|
|
84
|
+
|
|
85
|
+
pref = Basho::Prefecture.find(13)
|
|
86
|
+
pref.code # => 13
|
|
87
|
+
pref.name # => "東京都"
|
|
88
|
+
pref.name_en # => "Tokyo"
|
|
89
|
+
pref.name_kana # => "トウキョウト"
|
|
90
|
+
pref.name_hiragana # => "とうきょうと"
|
|
91
|
+
pref.type # => "都"
|
|
92
|
+
pref.region # => Region
|
|
93
|
+
pref.cities # => Array<City>
|
|
94
|
+
pref.capital # => City(県庁所在地)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### City(市区町村)
|
|
98
|
+
|
|
99
|
+
```ruby
|
|
100
|
+
Basho::City.find("131016") # 自治体コードで検索
|
|
101
|
+
Basho::City.where(prefecture_code: 13) # 都道府県で絞り込み
|
|
102
|
+
Basho::City.valid_code?("131016") # チェックディジット検証
|
|
103
|
+
|
|
104
|
+
city = Basho::City.find("131016")
|
|
105
|
+
city.code # => "131016"
|
|
106
|
+
city.prefecture_code # => 13
|
|
107
|
+
city.name # => "千代田区"
|
|
108
|
+
city.name_kana # => "チヨダク"
|
|
109
|
+
city.capital? # => false
|
|
110
|
+
city.prefecture # => Prefecture
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### PostalCode(郵便番号)
|
|
114
|
+
|
|
115
|
+
```ruby
|
|
116
|
+
results = Basho::PostalCode.find("154-0011") # 常にArrayを返す
|
|
117
|
+
results = Basho::PostalCode.find("1540011") # ハイフンなしも可
|
|
118
|
+
|
|
119
|
+
postal = results.first
|
|
120
|
+
postal.code # => "1540011"
|
|
121
|
+
postal.formatted_code # => "154-0011"
|
|
122
|
+
postal.prefecture_code # => 13
|
|
123
|
+
postal.prefecture_name # => "東京都"
|
|
124
|
+
postal.city_name # => "世田谷区"
|
|
125
|
+
postal.town # => "上馬"
|
|
126
|
+
postal.prefecture # => Prefecture
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Region(地方区分)
|
|
130
|
+
|
|
131
|
+
```ruby
|
|
132
|
+
Basho::Region.all # 8地方
|
|
133
|
+
Basho::Region.find("関東") # 名前で検索
|
|
134
|
+
|
|
135
|
+
region = Basho::Region.find("関東")
|
|
136
|
+
region.name # => "関東"
|
|
137
|
+
region.name_en # => "Kanto"
|
|
138
|
+
region.prefectures # => Array<Prefecture>
|
|
139
|
+
region.prefecture_codes # => [8, 9, 10, 11, 12, 13, 14]
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## ActiveRecord統合
|
|
143
|
+
|
|
144
|
+
### 自治体コードから都道府県・市区町村を引く
|
|
145
|
+
|
|
146
|
+
```ruby
|
|
147
|
+
class Shop < ApplicationRecord
|
|
148
|
+
include Basho
|
|
149
|
+
basho :local_gov_code
|
|
150
|
+
end
|
|
151
|
+
|
|
152
|
+
shop.prefecture # => Prefecture
|
|
153
|
+
shop.city # => City
|
|
154
|
+
shop.full_address # => "東京都千代田区"
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### 郵便番号から住所文字列を取得
|
|
158
|
+
|
|
159
|
+
```ruby
|
|
160
|
+
class Shop < ApplicationRecord
|
|
161
|
+
include Basho
|
|
162
|
+
basho_postal :postal_code
|
|
163
|
+
end
|
|
164
|
+
|
|
165
|
+
shop.postal_address # => "東京都世田谷区上馬"
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### 郵便番号から住所カラムを自動保存
|
|
169
|
+
|
|
170
|
+
`basho_postal`にマッピングオプションを渡すと、`before_save`で郵便番号から住所カラムを自動入力します。
|
|
171
|
+
|
|
172
|
+
```ruby
|
|
173
|
+
class User < ApplicationRecord
|
|
174
|
+
include Basho
|
|
175
|
+
basho_postal :postal_code,
|
|
176
|
+
prefecture: :pref_name,
|
|
177
|
+
city: :city_name,
|
|
178
|
+
town: :town_name
|
|
179
|
+
end
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
- `postal_code`が変更された時だけ解決を実行
|
|
183
|
+
- マッピングは部分指定可能(`prefecture:`だけでもOK)
|
|
184
|
+
- オプションなしの場合は`postal_address`メソッドのみ定義(後方互換)
|
|
185
|
+
|
|
186
|
+
## Hotwire Engine
|
|
187
|
+
|
|
188
|
+
Turbo Frame + Stimulusによる住所自動入力・カスケードセレクトをビルトインで提供するRails Engineです。自前でコントローラーを書かずに使えます。
|
|
189
|
+
|
|
190
|
+
### セットアップ
|
|
191
|
+
|
|
192
|
+
```ruby
|
|
193
|
+
# config/application.rb
|
|
194
|
+
require "basho/engine"
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
```ruby
|
|
198
|
+
# config/routes.rb
|
|
199
|
+
mount Basho::Engine, at: "/basho"
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### 郵便番号自動入力
|
|
203
|
+
|
|
204
|
+
郵便番号を入力すると都道府県・市区町村・町域フィールドを自動入力します。
|
|
205
|
+
|
|
206
|
+
```erb
|
|
207
|
+
<%= form_with(model: @shop) do |f| %>
|
|
208
|
+
<div data-controller="basho--auto-fill"
|
|
209
|
+
data-basho--auto-fill-url-value="<%= basho.postal_code_lookup_path %>">
|
|
210
|
+
|
|
211
|
+
<%= f.text_field :postal_code,
|
|
212
|
+
data: { action: "input->basho--auto-fill#lookup",
|
|
213
|
+
"basho--auto-fill-target": "input" } %>
|
|
214
|
+
|
|
215
|
+
<turbo-frame id="basho-result"
|
|
216
|
+
data-basho--auto-fill-target="frame"></turbo-frame>
|
|
217
|
+
|
|
218
|
+
<%= f.text_field :prefecture,
|
|
219
|
+
data: { "basho--auto-fill-target": "prefecture" } %>
|
|
220
|
+
<%= f.text_field :city,
|
|
221
|
+
data: { "basho--auto-fill-target": "city" } %>
|
|
222
|
+
<%= f.text_field :town,
|
|
223
|
+
data: { "basho--auto-fill-target": "town" } %>
|
|
224
|
+
</div>
|
|
225
|
+
<% end %>
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
1. ユーザーが郵便番号を入力(7桁)
|
|
229
|
+
2. 300msデバウンス後、Turbo Frameでサーバーに問い合わせ
|
|
230
|
+
3. Stimulusが都道府県・市区町村・町域フィールドを自動入力
|
|
231
|
+
|
|
232
|
+
### 都道府県・市区町村カスケードセレクト
|
|
233
|
+
|
|
234
|
+
都道府県を選択すると、対応する市区町村がJSON APIで動的に読み込まれます。
|
|
235
|
+
|
|
236
|
+
```erb
|
|
237
|
+
<%= form_with(model: @shop) do |f| %>
|
|
238
|
+
<div data-controller="basho--cascade-select"
|
|
239
|
+
data-basho--cascade-select-prefectures-url-value="<%= basho.prefectures_path %>"
|
|
240
|
+
data-basho--cascade-select-cities-url-template-value="<%= basho.cities_prefecture_path(':code') %>">
|
|
241
|
+
|
|
242
|
+
<select data-basho--cascade-select-target="prefecture"
|
|
243
|
+
data-action="change->basho--cascade-select#prefectureChanged">
|
|
244
|
+
<option value="">都道府県を選択</option>
|
|
245
|
+
</select>
|
|
246
|
+
|
|
247
|
+
<select data-basho--cascade-select-target="city">
|
|
248
|
+
<option value="">市区町村を選択</option>
|
|
249
|
+
</select>
|
|
250
|
+
</div>
|
|
251
|
+
<% end %>
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
`basho_cascade_data`ヘルパーでdata属性を簡潔に書けます。
|
|
255
|
+
|
|
256
|
+
```erb
|
|
257
|
+
<div <%= tag.attributes(data: basho_cascade_data) %>>
|
|
258
|
+
...
|
|
259
|
+
</div>
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
1. ページ読み込み時、都道府県セレクトが空ならAPIから47件を取得
|
|
263
|
+
2. 都道府県を選択すると、市区町村セレクトをAPIから再構築
|
|
264
|
+
3. 都道府県を変更すると、市区町村セレクトがリセットされ再取得
|
|
265
|
+
|
|
266
|
+
### JSON APIエンドポイント
|
|
267
|
+
|
|
268
|
+
Engineをマウントすると以下のエンドポイントが利用可能になります。
|
|
269
|
+
|
|
270
|
+
```
|
|
271
|
+
GET /basho/prefectures # => [{"code":1,"name":"北海道"}, ...]
|
|
272
|
+
GET /basho/prefectures/13/cities # => [{"code":"131016","name":"千代田区"}, ...]
|
|
273
|
+
GET /basho/postal_codes/lookup?code=1540011 # => Turbo Frame HTML
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## Engine不要の場合
|
|
277
|
+
|
|
278
|
+
Engineを使わず、`PostalCode.find`で自由にエンドポイントを作ることもできます。
|
|
279
|
+
|
|
280
|
+
```ruby
|
|
281
|
+
# JSON API
|
|
282
|
+
class PostalCodesController < ApplicationController
|
|
283
|
+
def lookup
|
|
284
|
+
results = Basho::PostalCode.find(params[:code])
|
|
285
|
+
|
|
286
|
+
render json: results.map { |r|
|
|
287
|
+
{ prefecture: r.prefecture_name, city: r.city_name, town: r.town }
|
|
288
|
+
}
|
|
289
|
+
end
|
|
290
|
+
end
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
## データソース
|
|
294
|
+
|
|
295
|
+
| データ | ソース | 更新頻度 |
|
|
296
|
+
|--------|--------|----------|
|
|
297
|
+
| 都道府県 | 総務省 JIS X 0401 | ほぼ変わらない |
|
|
298
|
+
| 市区町村 | 総務省 全国地方公共団体コード | 年に数回 |
|
|
299
|
+
| 郵便番号 | 日本郵便 KEN_ALL.csv | 月次(GitHub Actions自動更新) |
|
|
300
|
+
| 地方区分 | 8地方(ハードコード) | 変わらない |
|
|
301
|
+
|
|
302
|
+
## 開発
|
|
303
|
+
|
|
304
|
+
```bash
|
|
305
|
+
git clone https://github.com/wagai/basho.git
|
|
306
|
+
cd basho
|
|
307
|
+
bin/setup
|
|
308
|
+
bundle exec rspec
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
## ライセンス
|
|
312
|
+
|
|
313
|
+
MIT License
|
data/README.md
CHANGED
|
@@ -1,28 +1,30 @@
|
|
|
1
|
+
[日本語版はこちら](README.ja.md)
|
|
2
|
+
|
|
1
3
|
# Basho
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
A Ruby gem for working with Japanese address data — prefectures, cities, postal codes, and regions — in a unified interface.
|
|
4
6
|
|
|
5
|
-
##
|
|
7
|
+
## Why Basho
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Dealing with Japanese addresses is tedious.
|
|
8
10
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
11
|
+
- Looking up an address from a postal code requires parsing CSVs and loading them into a database
|
|
12
|
+
- Maintaining master data for prefectures and cities means writing migrations
|
|
13
|
+
- Postal code auto-fill and prefecture-city cascading selects end up being rewritten every project
|
|
14
|
+
- Existing gems are tightly coupled to Rails, have outdated data, or lack Hotwire support
|
|
13
15
|
|
|
14
|
-
Basho
|
|
16
|
+
Basho solves all of these.
|
|
15
17
|
|
|
16
|
-
- **DB
|
|
17
|
-
- **ActiveRecord
|
|
18
|
-
- **Hotwire
|
|
19
|
-
-
|
|
18
|
+
- **No DB migrations** — All data is bundled as JSON. Just `gem install` and go
|
|
19
|
+
- **ActiveRecord integration** — `include Basho` + a one-line macro for automatic postal code to address resolution on save
|
|
20
|
+
- **Hotwire-ready** — Built-in Rails Engine with postal code auto-fill and cascade select
|
|
21
|
+
- **Lightweight** — Immutable models via `Data.define`, lazy loading, zero external dependencies
|
|
20
22
|
|
|
21
|
-
##
|
|
23
|
+
## Supported Versions
|
|
22
24
|
|
|
23
25
|
- Ruby 3.2 / 3.3 / 3.4 / 4.0
|
|
24
26
|
|
|
25
|
-
##
|
|
27
|
+
## Installation
|
|
26
28
|
|
|
27
29
|
```ruby
|
|
28
30
|
# Gemfile
|
|
@@ -33,9 +35,9 @@ gem "basho"
|
|
|
33
35
|
bundle install
|
|
34
36
|
```
|
|
35
37
|
|
|
36
|
-
##
|
|
38
|
+
## Quick Start
|
|
37
39
|
|
|
38
|
-
###
|
|
40
|
+
### Look up an address from a postal code
|
|
39
41
|
|
|
40
42
|
```ruby
|
|
41
43
|
postal = Basho::PostalCode.find("154-0011").first
|
|
@@ -44,7 +46,7 @@ postal.city_name # => "世田谷区"
|
|
|
44
46
|
postal.town # => "上馬"
|
|
45
47
|
```
|
|
46
48
|
|
|
47
|
-
###
|
|
49
|
+
### Auto-save address columns from a postal code
|
|
48
50
|
|
|
49
51
|
```ruby
|
|
50
52
|
class User < ApplicationRecord
|
|
@@ -62,23 +64,23 @@ user.city_name # => "世田谷区"
|
|
|
62
64
|
user.town_name # => "上馬"
|
|
63
65
|
```
|
|
64
66
|
|
|
65
|
-
###
|
|
67
|
+
### Search prefectures and cities
|
|
66
68
|
|
|
67
69
|
```ruby
|
|
68
70
|
Basho::Prefecture.find(13).name # => "東京都"
|
|
69
|
-
Basho::Prefecture.where(region: "関東") # => 7
|
|
71
|
+
Basho::Prefecture.where(region: "関東") # => 7 results
|
|
70
72
|
Basho::City.find("131016").name # => "千代田区"
|
|
71
73
|
```
|
|
72
74
|
|
|
73
|
-
##
|
|
75
|
+
## Usage
|
|
74
76
|
|
|
75
|
-
### Prefecture
|
|
77
|
+
### Prefecture
|
|
76
78
|
|
|
77
79
|
```ruby
|
|
78
|
-
Basho::Prefecture.find(13) #
|
|
79
|
-
Basho::Prefecture.find(name: "東京都") #
|
|
80
|
-
Basho::Prefecture.all #
|
|
81
|
-
Basho::Prefecture.where(region: "関東") #
|
|
80
|
+
Basho::Prefecture.find(13) # Find by code
|
|
81
|
+
Basho::Prefecture.find(name: "東京都") # Find by name
|
|
82
|
+
Basho::Prefecture.all # All 47 prefectures
|
|
83
|
+
Basho::Prefecture.where(region: "関東") # Filter by region
|
|
82
84
|
|
|
83
85
|
pref = Basho::Prefecture.find(13)
|
|
84
86
|
pref.code # => 13
|
|
@@ -89,15 +91,15 @@ pref.name_hiragana # => "とうきょうと"
|
|
|
89
91
|
pref.type # => "都"
|
|
90
92
|
pref.region # => Region
|
|
91
93
|
pref.cities # => Array<City>
|
|
92
|
-
pref.capital # => City
|
|
94
|
+
pref.capital # => City (prefectural capital)
|
|
93
95
|
```
|
|
94
96
|
|
|
95
|
-
### City
|
|
97
|
+
### City
|
|
96
98
|
|
|
97
99
|
```ruby
|
|
98
|
-
Basho::City.find("131016") #
|
|
99
|
-
Basho::City.where(prefecture_code: 13) #
|
|
100
|
-
Basho::City.valid_code?("131016") #
|
|
100
|
+
Basho::City.find("131016") # Find by municipality code
|
|
101
|
+
Basho::City.where(prefecture_code: 13) # Filter by prefecture
|
|
102
|
+
Basho::City.valid_code?("131016") # Validate check digit
|
|
101
103
|
|
|
102
104
|
city = Basho::City.find("131016")
|
|
103
105
|
city.code # => "131016"
|
|
@@ -108,11 +110,11 @@ city.capital? # => false
|
|
|
108
110
|
city.prefecture # => Prefecture
|
|
109
111
|
```
|
|
110
112
|
|
|
111
|
-
### PostalCode
|
|
113
|
+
### PostalCode
|
|
112
114
|
|
|
113
115
|
```ruby
|
|
114
|
-
results = Basho::PostalCode.find("154-0011") #
|
|
115
|
-
results = Basho::PostalCode.find("1540011") #
|
|
116
|
+
results = Basho::PostalCode.find("154-0011") # Always returns an Array
|
|
117
|
+
results = Basho::PostalCode.find("1540011") # Hyphenless format also works
|
|
116
118
|
|
|
117
119
|
postal = results.first
|
|
118
120
|
postal.code # => "1540011"
|
|
@@ -124,11 +126,11 @@ postal.town # => "上馬"
|
|
|
124
126
|
postal.prefecture # => Prefecture
|
|
125
127
|
```
|
|
126
128
|
|
|
127
|
-
### Region
|
|
129
|
+
### Region
|
|
128
130
|
|
|
129
131
|
```ruby
|
|
130
|
-
Basho::Region.all # 8
|
|
131
|
-
Basho::Region.find("関東") #
|
|
132
|
+
Basho::Region.all # 8 regions
|
|
133
|
+
Basho::Region.find("関東") # Find by name
|
|
132
134
|
|
|
133
135
|
region = Basho::Region.find("関東")
|
|
134
136
|
region.name # => "関東"
|
|
@@ -137,9 +139,9 @@ region.prefectures # => Array<Prefecture>
|
|
|
137
139
|
region.prefecture_codes # => [8, 9, 10, 11, 12, 13, 14]
|
|
138
140
|
```
|
|
139
141
|
|
|
140
|
-
## ActiveRecord
|
|
142
|
+
## ActiveRecord Integration
|
|
141
143
|
|
|
142
|
-
###
|
|
144
|
+
### Look up prefecture and city from a municipality code
|
|
143
145
|
|
|
144
146
|
```ruby
|
|
145
147
|
class Shop < ApplicationRecord
|
|
@@ -152,7 +154,7 @@ shop.city # => City
|
|
|
152
154
|
shop.full_address # => "東京都千代田区"
|
|
153
155
|
```
|
|
154
156
|
|
|
155
|
-
###
|
|
157
|
+
### Get an address string from a postal code
|
|
156
158
|
|
|
157
159
|
```ruby
|
|
158
160
|
class Shop < ApplicationRecord
|
|
@@ -163,9 +165,9 @@ end
|
|
|
163
165
|
shop.postal_address # => "東京都世田谷区上馬"
|
|
164
166
|
```
|
|
165
167
|
|
|
166
|
-
###
|
|
168
|
+
### Auto-save address columns from a postal code
|
|
167
169
|
|
|
168
|
-
`basho_postal
|
|
170
|
+
When you pass mapping options to `basho_postal`, it registers a `before_save` callback that auto-fills address columns from the postal code.
|
|
169
171
|
|
|
170
172
|
```ruby
|
|
171
173
|
class User < ApplicationRecord
|
|
@@ -177,15 +179,15 @@ class User < ApplicationRecord
|
|
|
177
179
|
end
|
|
178
180
|
```
|
|
179
181
|
|
|
180
|
-
- `postal_code
|
|
181
|
-
-
|
|
182
|
-
-
|
|
182
|
+
- Resolution runs only when `postal_code` changes
|
|
183
|
+
- Partial mappings are supported (e.g. `prefecture:` only)
|
|
184
|
+
- Without options, only the `postal_address` method is defined (backward compatible)
|
|
183
185
|
|
|
184
186
|
## Hotwire Engine
|
|
185
187
|
|
|
186
|
-
Turbo Frame + Stimulus
|
|
188
|
+
A built-in Rails Engine providing postal code auto-fill and prefecture-city cascade select via Turbo Frame + Stimulus. No custom controllers needed.
|
|
187
189
|
|
|
188
|
-
###
|
|
190
|
+
### Setup
|
|
189
191
|
|
|
190
192
|
```ruby
|
|
191
193
|
# config/application.rb
|
|
@@ -197,9 +199,9 @@ require "basho/engine"
|
|
|
197
199
|
mount Basho::Engine, at: "/basho"
|
|
198
200
|
```
|
|
199
201
|
|
|
200
|
-
###
|
|
202
|
+
### Postal Code Auto-fill
|
|
201
203
|
|
|
202
|
-
|
|
204
|
+
Automatically fills in prefecture, city, and town fields when a postal code is entered.
|
|
203
205
|
|
|
204
206
|
```erb
|
|
205
207
|
<%= form_with(model: @shop) do |f| %>
|
|
@@ -223,13 +225,13 @@ mount Basho::Engine, at: "/basho"
|
|
|
223
225
|
<% end %>
|
|
224
226
|
```
|
|
225
227
|
|
|
226
|
-
1.
|
|
227
|
-
2. 300ms
|
|
228
|
-
3. Stimulus
|
|
228
|
+
1. User enters a 7-digit postal code
|
|
229
|
+
2. After a 300ms debounce, a Turbo Frame request is sent to the server
|
|
230
|
+
3. Stimulus auto-fills the prefecture, city, and town fields
|
|
229
231
|
|
|
230
|
-
###
|
|
232
|
+
### Prefecture-City Cascade Select
|
|
231
233
|
|
|
232
|
-
|
|
234
|
+
Selecting a prefecture dynamically loads the corresponding cities via JSON API.
|
|
233
235
|
|
|
234
236
|
```erb
|
|
235
237
|
<%= form_with(model: @shop) do |f| %>
|
|
@@ -239,17 +241,17 @@ mount Basho::Engine, at: "/basho"
|
|
|
239
241
|
|
|
240
242
|
<select data-basho--cascade-select-target="prefecture"
|
|
241
243
|
data-action="change->basho--cascade-select#prefectureChanged">
|
|
242
|
-
<option value=""
|
|
244
|
+
<option value="">Select prefecture</option>
|
|
243
245
|
</select>
|
|
244
246
|
|
|
245
247
|
<select data-basho--cascade-select-target="city">
|
|
246
|
-
<option value=""
|
|
248
|
+
<option value="">Select city</option>
|
|
247
249
|
</select>
|
|
248
250
|
</div>
|
|
249
251
|
<% end %>
|
|
250
252
|
```
|
|
251
253
|
|
|
252
|
-
`basho_cascade_data
|
|
254
|
+
Use the `basho_cascade_data` helper for concise data attributes.
|
|
253
255
|
|
|
254
256
|
```erb
|
|
255
257
|
<div <%= tag.attributes(data: basho_cascade_data) %>>
|
|
@@ -257,13 +259,13 @@ mount Basho::Engine, at: "/basho"
|
|
|
257
259
|
</div>
|
|
258
260
|
```
|
|
259
261
|
|
|
260
|
-
1.
|
|
261
|
-
2.
|
|
262
|
-
3.
|
|
262
|
+
1. On page load, if the prefecture select is empty, all 47 prefectures are fetched from the API
|
|
263
|
+
2. Selecting a prefecture rebuilds the city select from the API
|
|
264
|
+
3. Changing the prefecture resets and re-fetches the city select
|
|
263
265
|
|
|
264
|
-
### JSON API
|
|
266
|
+
### JSON API Endpoints
|
|
265
267
|
|
|
266
|
-
Engine
|
|
268
|
+
Mounting the Engine exposes the following endpoints.
|
|
267
269
|
|
|
268
270
|
```
|
|
269
271
|
GET /basho/prefectures # => [{"code":1,"name":"北海道"}, ...]
|
|
@@ -271,9 +273,9 @@ GET /basho/prefectures/13/cities # => [{"code":"131016","name":"千代田区"},
|
|
|
271
273
|
GET /basho/postal_codes/lookup?code=1540011 # => Turbo Frame HTML
|
|
272
274
|
```
|
|
273
275
|
|
|
274
|
-
## Engine
|
|
276
|
+
## Without the Engine
|
|
275
277
|
|
|
276
|
-
Engine
|
|
278
|
+
You can skip the Engine and build your own endpoints using `PostalCode.find`.
|
|
277
279
|
|
|
278
280
|
```ruby
|
|
279
281
|
# JSON API
|
|
@@ -288,16 +290,16 @@ class PostalCodesController < ApplicationController
|
|
|
288
290
|
end
|
|
289
291
|
```
|
|
290
292
|
|
|
291
|
-
##
|
|
293
|
+
## Data Sources
|
|
292
294
|
|
|
293
|
-
|
|
|
294
|
-
|
|
295
|
-
|
|
|
296
|
-
|
|
|
297
|
-
|
|
|
298
|
-
|
|
|
295
|
+
| Data | Source | Update Frequency |
|
|
296
|
+
|------|--------|-----------------|
|
|
297
|
+
| Prefectures | Ministry of Internal Affairs, JIS X 0401 | Rarely changes |
|
|
298
|
+
| Cities | Ministry of Internal Affairs, Local Government Codes | A few times per year |
|
|
299
|
+
| Postal codes | Japan Post KEN_ALL.csv | Monthly (auto-updated via GitHub Actions) |
|
|
300
|
+
| Regions | 8 regions (hardcoded) | Never changes |
|
|
299
301
|
|
|
300
|
-
##
|
|
302
|
+
## Development
|
|
301
303
|
|
|
302
304
|
```bash
|
|
303
305
|
git clone https://github.com/wagai/basho.git
|
|
@@ -306,6 +308,6 @@ bin/setup
|
|
|
306
308
|
bundle exec rspec
|
|
307
309
|
```
|
|
308
310
|
|
|
309
|
-
##
|
|
311
|
+
## License
|
|
310
312
|
|
|
311
313
|
MIT License
|
data/data/prefectures.json
CHANGED
data/lib/basho/region.rb
CHANGED
|
@@ -16,7 +16,8 @@ module Basho
|
|
|
16
16
|
new(name: "近畿", name_en: "Kinki", prefecture_codes: [24, 25, 26, 27, 28, 29, 30]),
|
|
17
17
|
new(name: "中国", name_en: "Chugoku", prefecture_codes: [31, 32, 33, 34, 35]),
|
|
18
18
|
new(name: "四国", name_en: "Shikoku", prefecture_codes: [36, 37, 38, 39]),
|
|
19
|
-
new(name: "九州", name_en: "Kyushu", prefecture_codes: [40, 41, 42, 43, 44, 45, 46
|
|
19
|
+
new(name: "九州", name_en: "Kyushu", prefecture_codes: [40, 41, 42, 43, 44, 45, 46]),
|
|
20
|
+
new(name: "沖縄", name_en: "Okinawa", prefecture_codes: [47])
|
|
20
21
|
].freeze
|
|
21
22
|
end
|
|
22
23
|
|
data/lib/basho/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: basho
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.1.
|
|
4
|
+
version: 0.1.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Hirotaka Wagai
|
|
@@ -9,7 +9,8 @@ bindir: exe
|
|
|
9
9
|
cert_chain: []
|
|
10
10
|
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
11
|
dependencies: []
|
|
12
|
-
description:
|
|
12
|
+
description: Provides prefectures, cities, postal codes, and regions as bundled JSON.
|
|
13
|
+
Includes ActiveRecord integration.
|
|
13
14
|
email:
|
|
14
15
|
- hirotaka.wagai@gmail.com
|
|
15
16
|
executables: []
|
|
@@ -18,6 +19,7 @@ extra_rdoc_files: []
|
|
|
18
19
|
files:
|
|
19
20
|
- CHANGELOG.md
|
|
20
21
|
- LICENSE.txt
|
|
22
|
+
- README.ja.md
|
|
21
23
|
- README.md
|
|
22
24
|
- Rakefile
|
|
23
25
|
- app/assets/javascripts/controllers/basho/auto_fill_controller.js
|
|
@@ -1060,5 +1062,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
1060
1062
|
requirements: []
|
|
1061
1063
|
rubygems_version: 4.0.4
|
|
1062
1064
|
specification_version: 4
|
|
1063
|
-
summary:
|
|
1065
|
+
summary: Japanese address data (prefectures, cities, postal codes, regions) in a single
|
|
1066
|
+
gem
|
|
1064
1067
|
test_files: []
|