Help us understand the problem. What is going on with this article?

郵便番号から住所を検索するAPIを作りました

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は公開しているので、どなたでも自分のサーバで利用していただけます。

プロジェクトページ

zipcode_jp

デモ

https://jsfiddle.net/kmdsbng/jxratmsL/2/
このページで、実際にGithub Pageで公開されている郵便番号検索APIを使った住所検索の挙動を確認できます。

機能

このAPIは、郵便番号をキーにして、郵便番号に一致する住所を返す機能のみサポートしています。

仕組み

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 のデータも自動で更新されるようにしています。

https://circleci.com/gh/kmdsbng/zipcode_jp

なので、clone/forkした住所データを更新するときは、単にリポジトリを git pull すれば、最新の住所データを利用できます。

まとめ

zipcode_jpは、郵便番号検索にまつわるいろいろな問題を解決します。

  • フロントエンドJavaScriptからもバックエンドアプリケーションからもスクリプトからも利用可能です。郵便番号をキーにしたJSONファイルのURLにアクセスすることで、住所検索します。
  • 郵便番号データベースの保守コストを、ほぼゼロにします。
  • 導入が簡単です。
  • 自社サーバで運用可能です。

ぜひご利用ください。

Why do not you register as a user and use Qiita more conveniently?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away