郵便番号・デジタルアドレスAPIを使ってみた

郵便番号・デジタルアドレスAPIとは

2025年5月26日に、日本郵便から公開されたAPIです

従来はKEN_ALL.csvというファイルをよしなにparseしたり、非公式のAPIを使っていた方が多いはずです
公式にAPIが無料提供されたことにより、システムに組み込みやすくなりました

個人利用は想定されていない

よくある質問より

Q. 郵便番号・デジタルアドレス for Bizは個人でも利用できますか
A. 郵便番号・デジタルアドレス for Bizは、法人・個人事業主のお客さまの利用を想定したサービスです。

とあります
新規登録時も、法人 or 個人事業主としての組織登録が求められるのでご注意ください

アカウント登録

郵便番号・デジタルアドレス for Bizから登録します
ゆうIDが必要かつ、前述の通り法人 or 個人事業主としての組織登録が求められます

テスト用APIでの実行

テスト用APIでも本番APIでも、
トークン取得→searchcode or addresszip
という手順になります

トークンの取得

管理画面に入ったら、「テスト用API認証情報」を選びます

クライアントIDとクライアントシークレット情報を元に、まずはトークンを取得します

curl -X POST https://{DEV_URL}/api/v1/j/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"{CLIENT_ID}","secret_key":"{CLIENT_SECRET}"}'

DEV_URL: リファレンスのテスト環境URL（以下スクショ参照）を入力
CLIENT_ID, CLIENT_SECRET:「テスト用API認証情報」最上部の情報をコピペ

成功すると、以下の通りtokenのレスポンスが返ってきます

{"token":"{TOKEN}","token_type":"jwt","expires_in":600,"scope":"J1"}

郵便番号・デジタルアドレスの検索（searchcode）

早速、APIを使って「郵便番号・デジタルアドレス→住所」の検索をしてみましょう

注意点は2つあり、まずテストAPIは以下のパラメータしか受け付けられないこと

テスト用APIではテスト用のデジタルアドレス3種と東京都千代田区に対して郵便番号、事業所個別郵便番号の検索が可能。

そして、郵便番号・デジタルアドレスともに 「ハイフンを入れてはダメ」 なこと
ハイフンを入れると「デジアドの形式が正しくありません」というエラーになります

先ほど取得したトークンをリクエストに含め、SEARCH_CODEにはサンプル3種類のうちどれかを入れます
例えば以下の通り

curl -X GET https://{DEV_URL}/api/v1/searchcode/QN6GQX1 \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json"

繰り返しますが、 「ハイフンを入れてはダメ」 です

成功すると、以下のようなレスポンスが返ってきます

{"page":1,"limit":1000,"count":1,"searchtype":"dgacode","addresses":[{"dgacode":"QN6GQX1","zip_code":"812-0012","pref_code":"40","pref_name":"福岡県","pref_kana":null,"pref_roma":null,"city_code":"40132","city_name":"福岡市博多区","city_kana":null,"city_roma":null,"town_name":"博多駅中央街","town_kana":null,"town_roma":null,"biz_name":null,"biz_kana":null,"biz_roma":null,"block_name":"９−１","other_name":"部屋番号：サンプル３","address":"福岡県福岡市博多区博多駅中央街９−１部屋番号：サンプル３","longitude":null,"latitude":null}]}

住所→郵便番号・デジタルアドレスの検索（addresszip）

次は逆に、住所→郵便番号・デジタルアドレスの検索をします

注意点は以下

テスト用APIでは東京都千代田区に対してのみ検索が可能

curl -X POST {DEV_URL}/api/v1/addresszip \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"pref_name":"東京都","city_name":"千代田区"}'

成功すると、以下のようなレスポンスが返ってきます

{"level":2,"page":1,"limit":1000,"count":485,"addresses":[{"zip_code":"1000000","pref_code":"13","pref_name":"東京都","pref_kana":"トウキョウト","pref_roma":"TOKYO","city_code":"13101","city_name":"千代田区","city_kana":"チヨダク","city_roma":"CHIYODA-KU","town_name":"わからない・記載がない場合","town_kana":"ワカラナイ・キサイガナイバアイ","town_roma":"WAKARANAI/KISAIGANAIBAAI"},{"zip_code":"1020072","pref_code":"13","pref_name":"東京都","pref_kana":"トウキョウト","pref_roma":"TOKYO","city_code":"13101","city_name":"千代田区","city_kana":"チヨダク","city_roma":"CHIYODA-KU","town_name":"飯田橋","town_kana":"イイダバシ","town_roma":"IIDABASHI"},
...

本番APIの実行

システムリスト→新規登録から進みます
固定IPとURLが必要な点、そしてclient_secretは登録時しか出ないことにご注意ください

トークン取得→searchcode or addresszipという手順は変わりません
テスト環境と違い、あらゆる郵便番号や住所が検索できるようになっていることが確認できます

終わりに

日本郵便が無料で提供しているため信頼性が高く、今後利用が広がっていくように思います

本記事では紹介していませんが、住所検索もカナやローマ字、フリーワード等たくさん検索方法が指定できます
いろいろ試してみると良さそうです