2019/4/21追記
zipcode_jpに機能追加したため、この記事の内容は古くなりました。
現在のzipcode_jpについては zipcode_jp でいい感じの住所入力フォームが作れるようになりました の記事を参照ください。
概要
プロダクトごとに分散してしまいがちな、郵便番号データベースの保守を楽にする仕組みを作ったので紹介します。
郵便番号検索にまつわる問題点
フォームの住所入力をサポートするために、郵便番号から住所を補完するコードを書くことがあると思います。
私も何度かこの処理を実装したことがあるのですが、そのたびに郵便番号から該当する住所を返すAPIを自前で実装しました。
ただ、プロダクト横断の仕組みとしてAPIを実装しなかったので、プロダクトごとにAPIの実装、ken-all.csv から住所データをDBにインポートするということを繰り返してきました。
このアプローチには保守の面で問題もあります。郵便番号データは郵便局が公開している郵便番号データ、いわゆるken-all.csvが元データになりますが、ken-all.csvからDBへのデータのインポートには手間がかかります。
データの更新に手間をかけないために、一般に公開されている郵便番号検索APIを利用する方法もあります。ただ、外部APIに依存してしまうことにはリスクも存在します。
- APIが提供されなくなる可能性
- APIの利用制限に引っかかって利用できなくなる可能性
- APIサーバが障害のために停止してしまう可能性
プロダクションコードだと、これらのリスクは導入への障壁になるでしょう。
これらの問題を解決するために、
- 再利用可能で
- 外部サービスに依存しない
郵便番号検索のAPIを作りました。APIは公開しているので、どなたでも自分のサーバで利用していただけます。
プロジェクトページ
デモ
https://jsfiddle.net/kmdsbng/f18t60yj/12/
このページで、実際にGithub Pageで公開されている郵便番号検索APIを使った住所検索の挙動を確認できます。
機能
このAPIは、郵便番号をキーにして、郵便番号に一致する住所を返す機能のみ提供しています。
(2020/3追記: 現在は以下の機能も提供しています。
- 都道府県一覧取得機能
- 都道府県ごとの市区郡取得機能
- 市区郡ごとの町村取得機能
- 町村ごとの郵便番号取得機能 )
仕組み
APIと書きましたが、住所データのJSONファイルを docs/zip_code ディレクトリ以下に配置しているだけで、バックエンドアプリケーションは存在しません。
例えば 0010010 という郵便番号の住所データは、 https://kmdsbng.github.io/zipcode_jp/zip_code/001/0010010.json に格納されています。
該当する郵便番号が存在しなければ、404が帰ってくるので、郵便番号が存在しないことがわかります。
フロントエンドJavaScriptからアクセスするときにはSame origin policy制約を回避するため、APIサーバにアクセス用のJavaScriptファイル(/api.js)を置いています。
このファイルを script タグで読み込み、住所検索関数を呼び出すことで、フロントエンドJSから住所検索を行えます。詳しくはデモページのコードをご参照ください。
JSONファイルを郵便番号のファイル名に格納しているだけなので、JavaScript以外からも利用可能です。
サーバサイドのプログラムが無いため、処理が高速で設置も簡単というメリットがあります。
利用方法
zipcode_jp を cloneしたり、forkしたりして、docsディレクトリ以下を公開してください。
zipcode_jpの Github page でも公開しているので、テスト用途やサンプルに使うなら、これを使ってもらうのがもっとも簡単です。実際デモページでは、zipcode_jpの Github pageからデータを読み込んでいます。
JavaScriptからのアクセス方法は、デモページのコードを参照してください。
保守
zipcode_jpの住所データは、zipcloud様が提供している x-ken-all.csv を元に作っています。
x-ken-all.csvが更新されると、CircleCIで自動検知して zipcode_jp のデータも自動で更新されるようにしています。
なので、clone/forkした住所データを更新するときは、単にリポジトリを git pull すれば、最新の住所データを利用できます。
まとめ
zipcode_jpは、郵便番号検索にまつわるいろいろな問題を解決します。
- フロントエンドJavaScriptからもバックエンドアプリケーションからもスクリプトからも利用可能です。郵便番号をキーにしたJSONファイルのURLにアクセスすることで、住所検索します。
- 郵便番号データベースの保守コストを、ほぼゼロにします。
- 導入が簡単です。
- 自社サーバで運用可能です。
ぜひご利用ください。