💌

無料で商用にも使える日本の郵便番号APIをリリースしました

2024/05/28に公開

jp-postal-code-api

https://github.com/ttskch/jp-postal-code-api

日本の郵便番号から住所のデータを取得できるWeb APIです。

GitHub Pagesを使用して静的なJSONファイルとして配信している ため、可用性が高いのが特徴です。また、オープンソースなのでクライアントワークでも安心してご使用いただけます。もしリポジトリの永続性やGitHub Pagesの利用制限が心配な場合は、ご自由にフォークしてご利用ください。

日本郵便によって公開されているデータを元に住所データのJSONファイルを生成して配信しています。JSONファイルには日本語表記・カナ表記・英語表記の住所データが含まれています。ただし、以下の注意事項があります。

大口事業所個別番号の住所データは以下のように出力されます（元データの内容がそうであるため）
- カナ表記は事業所名についてのみ出力されます
- 事業所名のカナ表記は促音・拗音が大書きで出力されます
- 英語表記は出力されません
直近1年程度以内に市町村変更があった住所については、英語表記は出力されません（元データが年1回程度しか更新されないため）

なお、配信データはGitHub Actionsを使用して毎日最新の内容に更新しています。

このプロジェクトの実装はmadefor/postal-code-api にインスピレーションを受けています。長期間メンテナンスが行われていない同プロジェクトに代わるものとして、モダンPHPで再実装しました。オリジナルのソースコードに最大の敬意を表します。

使い方

https://jp-postal-code-api.ttskch.com/api/v1/{郵便番号}.json

というエンドポイントにGETリクエストを送ると、住所のデータがJSON形式で取得できます。

例えば、郵便番号が100-0014 の住所（東京都千代田区永田町）を取得したい場合は、エンドポイントのURLとレスポンスの内容は以下のようになります。

https://jp-postal-code-api.ttskch.com/api/v1/1000014.json

{"postalCode":"1000014","addresses":[{"prefectureCode":"13","ja":{"prefecture":"東京都","address1":"千代田区","address2":"永田町","address3":"","address4":""},"kana":{"prefecture":"トウキョウト","address1":"チヨダク","address2":"ナガタチョウ","address3":"","address4":""},"en":{"prefecture":"Tokyo","address1":"Chiyoda-ku","address2":"Nagatacho ","address3":"","address4":""}}]}

1つの郵便番号に複数の住所がある場合は、レスポンスの内容は以下のようになります。

https://jp-postal-code-api.ttskch.com/api/v1/6180000.json

{"postalCode":"6180000","addresses":[{"prefectureCode":"26","ja":{"prefecture":"京都府","address1":"乙訓郡大山崎町","address2":"","address3":"","address4":""},"kana":{"prefecture":"キョウトフ","address1":"オトクニグンオオヤマザキチョウ","address2":"","address3":"","address4":""},"en":{"prefecture":"Kyoto","address1":"Oyamazaki-cho, Otokuni-gun","address2":"","address3":"","address4":""}},{"prefectureCode":"27","ja":{"prefecture":"大阪府","address1":"三島郡島本町","address2":"","address3":"","address4":""},"kana":{"prefecture":"オオサカフ","address1":"ミシマグンシマモトチョウ","address2":"","address3":"","address4":""},"en":{"prefecture":"Osaka","address1":"Shimamoto-cho, Mishima-gun","address2":"","address3":"","address4":""}}]}

大口事業所個別番号では英語表記の住所は空になります。

https://jp-postal-code-api.ttskch.com/api/v1/1008111.json

{"postalCode":"1008111","addresses":[{"prefectureCode":"13","ja":{"prefecture":"東京都","address1":"千代田区","address2":"千代田","address3":"１−１","address4":"宮内庁"},"kana":{"prefecture":"","address1":"","address2":"","address3":"","address4":"クナイチヨウ"},"en":{"prefecture":"","address1":"","address2":"","address3":"","address4":""}}]}

2024年1月1日に市町村変更があった住所を取得すると、2024年5月現在では英語表記は出力されません。元データが更新されると、このWeb APIの配信データも最大1日の誤差で自動的に更新されます。

https://jp-postal-code-api.ttskch.com/api/v1/4328003.json

{"postalCode":"4328003","addresses":[{"prefectureCode":"22","ja":{"prefecture":"静岡県","address1":"浜松市中央区","address2":"和地山","address3":"","address4":""},"kana":{"prefecture":"シズオカケン","address1":"ハママツシチュウオウク","address2":"ワジヤマ","address3":"","address4":""},"en":{"prefecture":"","address1":"","address2":"","address3":"","address4":""}}]}

配信データの生成・自動更新の仕組み

配信データの生成

日本郵便のWebサイトから住所の郵便番号、住所の郵便番号（ローマ字）、事業所の個別郵便番号のデータをダウンロード
ダウンロードしたZipファイルからCSVファイルを取得
CSVファイルをパースし、配信データとしてのJSONファイル群を/docs/api/v1/ 配下に生成
- その際、「住所の郵便番号」と「住所の郵便番号（ローマ字）」のデータを、日本語表記の住所が一致している場合にのみマージ

という処理をPHPで行っています。

symfony/console でCLIコマンドとして実装してあり、プロジェクトルートディレクトリでbin/console build というコマンドを実行することで一連の処理を開始することができます。

GitHub Pagesの自動更新

https://github.com/ttskch/jp-postal-code-api/blob/2bd2eb4ca4af1fced4f113c7782d0aff703ad209/.github/workflows/cron.yaml#L8-L58

上記のように、GitHub ActionsのScheduled Workflowを使って毎日午前0時頃に自動的に/docs/api/v1/ の内容を最新化しています。

ただし、GitHub Actionsのドキュメントにあるとおり、60日間リポジトリにアクティビティがなかった場合、Scheduled Workflowは自動的に無効化されてしまうため、

毎日のWorkflowの実行時に、mainブランチの最後のコミットの日時と現在日時を比較
59日以上経過していたら、mainブランチに空のコミットをpushする

という方法でWorkflowの自動的な無効化を回避しています（ごめんなさい）。

https://github.com/ttskch/jp-postal-code-api/blob/2bd2eb4ca4af1fced4f113c7782d0aff703ad209/.github/workflows/cron.yaml#L60-L90

Workflowの有効化はAPI経由でも行えるので、自動的に無効になったらAPI経由で再度有効化する、みたいな対応も考えられましたが、GitHub Actionsだけで完結できたほうが嬉しいのでこのような方法をとりました。

GitHub Pagesの利用制限について

2024年5月現在、GitHub Pagesで公開したサイトには月当たり100GBの帯域制限があります。このWeb APIの配信データの容量は平均およそ400バイトなので、毎秒104リクエスト程度のペースが1ヶ月間継続すると制限の対象となる可能性があります。

もしこの制限が心配な場合は、本リポジトリをフォークしてご自身のGitHubアカウントでホストしてご利用ください。その場合、エンドポイントのURLは

https://{あなたのGitHubユーザー名}.github.io/jp-postal-code-api/api/v1/{郵便番号}.json

のようになります。

ただし、それでも悪意ある攻撃者によって大量のリクエストが行われると利用制限の対象になる可能性があります。どうしても心配な場合は、フォークしたリポジトリをCloudflare Pages などの多機能なホスティングサービスやその他PaaSなどに接続して、BASIC認証などをかけた状態でWeb APIをホストするといった運用を検討してください。

おわりに

今までmadefor/postal-code-api をありがたく使わせていただいていたのですが、配信データの自動更新が3年以上止まったままになってしまっており、2024/01/01にあった浜松市の市町村変更が取り込まれていなかったために直近のクライアントワークで問題が発生してしまいました。

初めはビルド周りを修正してPull Requestを送ろうと思ったのですが、既存のPull Requestが放置されていたり、実質的に開発が停止してしまっているようにお見受けしたため、むしろ自分がメンテしやすい技術スタックで作り直して長期的にホストし続けるほうが全体の幸福度が高いかなと思い、あえて再実装することにしました。

郵便番号を入力したら自動で住所が補完されるフォームの実装とかで気軽に使っていただけたら嬉しいです。

https://github.com/ttskch/jp-postal-code-api

IssueやPull Requestはいつでも大歓迎です。あと、これは大事なことですが、リポジトリにStarを付けていただけると私のモチベーションが上がります ので、よろしければ是非お願いします😋

GitHubで編集を提案