無料で商用にも使える日本の郵便番号APIをリリースしました
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の自動更新
上記のように、GitHub ActionsのScheduled Workflowを使って 毎日午前0時頃に自動的に /docs/api/v1/ の内容を最新化しています。
ただし、GitHub Actionsのドキュメントにあるとおり、60日間リポジトリにアクティビティがなかった場合、Scheduled Workflowは自動的に無効化されてしまうため、
- 毎日のWorkflowの実行時に、mainブランチの最後のコミットの日時と現在日時を比較
- 59日以上経過していたら、mainブランチに空のコミットをpushする
という方法でWorkflowの自動的な無効化を回避しています（ごめんなさい）。
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を付けていただけると私のモチベーションが上がります ので、よろしければ是非お願いします😋
Discussion
ライセンスは問題ないですか？
（すでに別の方がご回答くださっていましたが）郵便番号データ、郵便番号データ（ローマ字）、大口事業所個別番号データ いずれも日本郵便は著作権を主張していないため問題ない認識です。
とあるので大丈夫そうな気もしますが。別の箇所ならすみません。
郵便番号データの説明
よかったです！！❤️
代わりにお答えいただきありがとうございました！上記コメント のとおり問題ない認識です。
ありがたいです！
1点気づいたのですが、現在のURLは/v1/が必要かと思いますので、zenn記事内のURLを修正した方がよいかもしれません。（現在404になっています）
ご指摘ありがとうございます。実装を変更してから記事を修正するまで少し時間差ができてしまいました🙏
毎日０時に更新とありますが、その場合正確なデータをAPIが提供できない場合があります。
同様のWebサービスの運営経験からすると、日本郵便の元データは誤り表記が日々修正されたりするのでこれについては問題ありませんが、翌月から変更となる予定の郵便番号、住所も日々更新されます。
正確に実施するには変更予定の郵便番号や住所を事前に把握してそれ以外を日々差分更新するとよいです。
ご指摘ありがとうございます！そうなんですね・・・勉強になります。
ただ、申し訳ありませんが今のところは日本郵便の配布データを正として、それ以上のきめ細やかな対応まではしない運用方針です🙏
いつかリソースに余裕ができたら対応できるとより良いとは思いますので、GitHubリポジトリにいただいたIssue は将来の検討のために残させていただければと思います。