郵便番号・デジタルアドレスAPIの使い方｜日本郵便公式APIのver2.0・登録手順・実装例

「デジタルアドレス api」「日本郵便 api」で探しているのは、日本郵便が2025年5月26日に公開した公式の郵便番号・デジタルアドレスAPIでしょう。郵便番号や7桁のデジタルアドレスを渡すと住所が返る無料のAPIで、2026年3月19日にver2.0へ切り替わり、法人の電話番号や法人番号まで返せるようになりました。この記事では、for Bizへの登録から、トークン取得と住所検索の実装、テスト用APIに実際にリクエストして確かめた入力ルールとエラー、ZipCloudなど他の郵便番号APIとの選び方までを順に説明します。

まとめ：郵便番号・デジタルアドレスAPIの要点

• 公式APIのスコープはtoken・searchcode（郵便番号・デジタルアドレス→住所）・addresszip（住所→郵便番号）の3つ。利用料は無料。
• 2026年3月19日以降に始めるならver2.0一択。ver1.0の組織・システム・クライアントIDは引き継げず、新サイトで登録し直して呼び出し先も変える。ver1.0は時期未定で終了予定。
• ver2.0ではビジネスデジタルアドレスから社名・電話番号・法人番号・企業URLが返る。2026年7月30日からは建物の入口の緯度経度も返る。
• 使えるのは法人か個人事業主。登録したシステムの固定IPから呼ぶ仕様で、CORS許可ヘッダーも返らないため、ブラウザから直接は呼べない。
• 認証はOAuth 2.0のclient_credentialsに近いが、secret_keyという独自の項目名とX-Forwarded-Forヘッダーを使う。汎用OAuthライブラリはそのままでは通らない。
• 郵便番号から住所を引くだけならZipCloudで足りる。デジタルアドレスを受け付けたい、法人情報まで引きたい、公式データであることを説明したい場合に公式APIを選ぶ。

デジタルアドレスとは｜7桁の英数字で住所を表す日本郵便の仕組み

デジタルアドレスは、住所全文を7桁の英数字で表すコードです。APIのsearchcodeは郵便番号とデジタルアドレスを同じ入口で受けるため、まずコードの種類を押さえておくと実装で迷いません。2026年10月時点でコードは2種類あります。

個人向けデジタルアドレス：ゆうIDに紐づき、引越し後も同じコード

個人向けのデジタルアドレスは、ゆうIDに登録した住所に対して発行されます。コードは住所ではなくゆうIDに紐づくため、引越しの際にゆうIDの住所を変えれば、同じコードのまま新しい住所が返ります。日本郵便の2026年3月19日のプレスリリースは、コードに地理的な場所や同居者の情報を含めず、コードから名前を特定することも、名前や住所からコードを検索することもできない設計だと説明しています。取得も利用も無料で、郵便局アプリかデジタルアドレスWeb版にゆうIDでログインして発行します。

事業者から見た利点は、顧客の住所の代わりにコードを保存しておけば、転居後の住所を引き直せることです。逆に、コードを保存していない顧客の住所は追えません。

ビジネスデジタルアドレス：社名・電話番号・法人番号まで返る法人版

2026年3月19日に始まったビジネスデジタルアドレスは、法人・個人事業主向けのコードです。住所に加えて、社名、社名カナ、電話番号、会社ホームページのURL、法人番号を7桁にまとめて登録でき、登記上の本店に限らずオフィスや店舗の所在地も登録できます。フリープランではランダムな7桁のコードを1つ無料で取得できます。

2026年7月30日からは、ビジネスデジタルアドレスごとに建物の入口の緯度経度を1つ登録でき、APIの返却値にも含まれるようになりました。ジオテクノロジーズの発表によると、登録にはMapFan APIの地図を使い、緯度経度は小数点以下6桁まで保存されます。地図サービスの住所検索では建物の中央にピンが立つため、搬入口や通用口を配送先に伝えたい倉庫・工場で効く機能です。

使える場所：郵便局アプリと楽天市場など／Amazonは対応一覧に無い

デジタルアドレスの公式サイトが「使える場所やサービス」に載せているのは、郵便局アプリのゆうパック送り状作成、郵便局のネットショップ、楽天市場（2026年4月28日掲載）、GMOクラウドEC、FormBridgeなどです。Amazonはこの一覧に載っていません。Amazonのアカウント設定にある「デジタル購入用の住所」は名前が似ていますが、日本郵便のデジタルアドレスとは別の、Amazon側の住所設定です。用途はAmazonの公式ヘルプで確認してください。

紙の送り状に7桁だけを書いても配達はされません。デジタルアドレスは、対応したシステムの住所入力を短くする仕組みであって、住所そのものの代わりにはならない点を、自社の入力画面でも案内しておくと問い合わせが減ります。

郵便番号・デジタルアドレスAPIでできること｜3つのスコープと返却項目

for Bizの公式ページが挙げるスコープはsearchcode・addresszip・tokenの3つだけです。住所データは郵便番号データ（CSV）を元に日本郵便が更新するため、利用者側でマスタを入れ替える作業は要りません。

searchcode：郵便番号・デジタルアドレスから住所を取得

searchcodeは、郵便番号・事業所個別郵便番号・デジタルアドレス・ビジネスデジタルアドレスを同じパスで受け、該当する住所を配列で返します。郵便番号は3桁以上なら前方一致で候補を返すので、入力途中の補完にも使えます。住所は漢字・カナ・ローマ字で返り、事業所個別郵便番号だけは漢字・カナのみです。

テスト用APIで確かめた返却項目は次のとおりです。ver2.0の/api/v2/searchcode/は、ver1.0の項目に法人情報の5項目とusageを足した形で返りました。

個人向けデジタルアドレスを引いた結果では、番地がblock_name、部屋番号がother_nameに入り、カナとローマ字はnullでした。郵便番号で引いた結果は逆にaddressがnullで、町域までしか返りません。画面に出す住所を組み立てるときは、addressがあればそれを使い、無ければ都道府県から町域をつなぐ分岐が要ります。

addresszip：住所から郵便番号を検索

addresszipは、pref_name・city_name・town_nameまたはfreewordをPOSTで送り、候補の郵便番号を返します。テスト用APIで都道府県と市区町村だけを送ると、レスポンスにlevelという項目が付き、町域ごとの候補が並びました。番地まで含む住所文字列を1つ渡したときの絞り込み精度は公開ページに説明が無く、Zennの検証記事では、霞が関の住所を渡すと千代田区の郵便番号が並んで返ったと報告されています。住所を項目別に渡す方法とfreewordで渡す方法を、本番の検索対象で比べてから組み込みます。

このAPIで取れないもの：お届け日数・送料・追跡番号

「日本郵便 api」「お届け日数 api」で調べてこのAPIに行き着く人もいますが、スコープは上の3つだけで、お届け日数・送料・荷物の追跡は返りません。お届け日数は日本郵便サイトの検索ページで調べる仕組みです。同じ日本郵便の名前が付いたAPIには、通販物流の倉庫管理システム向けのWMSのWeb API連携もありますが、こちらは入荷・出荷・在庫のデータ連携用で、住所検索とは別のサービス・別の仕様です。

ver1.0とver2.0の違い｜2026年3月19日の移行で変わった点

2026年3月19日、日本郵便はfor Bizのサイトごと新しくし、APIをver2.0に上げました。日本郵便のQ&Aと移行資料（PDF）から、違いを整理します。

ver1.0利用者の移行手順と旧サイトの制限

ver1.0で登録済みのシステムは、そのまま動きます。住所だけ取れればよいなら急いで対応する必要はありません。ただし旧サイトでは、システムの新規登録、固定IPアドレスの編集、組織へのユーザー追加ができなくなりました。出口のIPが変わるサーバー移行を予定しているなら、ver1.0のままでは登録IPを直せないので、その前にver2.0へ移ります。

移行は差し替えではなく作り直しです。新サイトで組織を登録し直し、システムを登録し、新しいクライアントIDとシークレットを受け取り、呼び出し先のURLを変えます。旧サイトの組織・ユーザーリスト・システムリスト・クライアントIDはどれも引き継げません。ゆうIDだけは新旧で同じものが使え、旧サイトは組織を削除しない限り新サイトと併存します。

本番ホストapi.da.pf.japanpost.jpにダミーの認証情報を送ったところ、/api/v1/j/tokenは400、/api/v2/j/tokenは401で「クライアントIDまたはシークレットキーが違います」を返し、/api/v3/は404でした（2026年10月15日）。同じ失敗でも版によってステータスコードが違うので、移行時はエラー処理の分岐も見直します。正式な呼び出し先はログイン後のAPIリファレンスで確認してください。

利用開始の手順｜ゆうID登録からシステム登録まで

公式APIは、アカウントを作ってAPIキーを1本受け取る形ではありません。組織を登録し、呼び出すシステムを登録して、システムごとに認証情報を受け取ります。

1. ゆうIDを登録する：担当者ごとに登録するか、個人のゆうIDを使う。ゆうIDはfor Bizへのログイン認証にだけ使われる。
2. for Bizでビジネスアカウントと組織を登録する：提供開始時のプレスリリースのとおり、法人か個人事業主として組織情報を入れる。1法人につき組織は1つで、部署ごとには分けられない。
3. APIの利用規約に同意し、システムを登録する：システム名と固定IPアドレスを登録すると、クライアントIDとシークレットが発行される。
4. テスト用APIで動作を確かめてから本番へ切り替える：テスト用の認証情報とAPIリファレンス、利用ガイドライン、リリースノートはログイン後に見られる。

注意したいのは第三者提供の扱いです。公式ページは、このAPIを第三者企業へ提供することを利用規約で禁じています。APIを組み込んだCRMを顧客に提供し、顧客がそのままAPIを使う形のSaaSは、システム登録の際に「API組込みシステムの第三者提供特約」への同意が必要です。受託開発で顧客の社内システムに組み込む場合も、規約上どちらの事業者が利用者になるかを契約前に決めておきます。

APIの実装例｜トークン取得と住所検索

流れは、トークンを取得し、そのトークンを付けてsearchcodeを呼ぶ、の2段です。トークンの扱いはBearer Token（ベアラートークン）とは？読み方・Authorization: Bearerの書き方とJWTとの違いと同じで、Authorization: Bearerヘッダーに載せます。以下のコードは、テスト用APIで動くことを確かめたうえで、本番のホスト名に置き換えたものです。

curlによるトークン取得

curl -X POST "https://api.da.pf.japanpost.jp/api/v2/j/token" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 203.0.113.10" \
  -d '{"grant_type":"client_credentials","client_id":"YOUR_CLIENT_ID","secret_key":"YOUR_SECRET_KEY"}'

# テスト用APIでのレスポンス（tokenは省略）
# {"token":"eyJhbGci...","token_type":"jwt","expires_in":600,"scope":"J1"}

X-Forwarded-Forには、システムに登録した出口の固定IPを入れます。テスト用APIではexpires_inが600秒でした。

Pythonによる郵便番号・デジタルアドレスからの住所取得

トークンを期限の60秒前まで使い回し、入力をAPIが受け付ける形に揃えてからsearchcodeを呼ぶ例です。実行前にpython -m pip install requestsで依存ライブラリを導入し、環境変数JP_DA_CLIENT_ID・JP_DA_SECRET_KEY・JP_DA_EGRESS_IPを設定します。認証情報はコードに書かず環境変数から読みます。

import os
import re
import time
import requests

BASE = os.environ.get("JP_DA_BASE", "https://api.da.pf.japanpost.jp")
API = os.environ.get("JP_DA_VERSION", "v2")  # ver2.0で登録したシステムは v2
EGRESS_IP = os.environ["JP_DA_EGRESS_IP"]    # システムに登録した固定IP

_cache = {"token": None, "exp": 0}


def get_token():
    # expires_in（秒）の60秒前までは同じトークンを使い回す
    if _cache["token"] and time.time() < _cache["exp"] - 60:
        return _cache["token"]
    res = requests.post(
        f"{BASE}/api/{API}/j/token",
        json={
            "grant_type": "client_credentials",
            "client_id": os.environ["JP_DA_CLIENT_ID"],
            "secret_key": os.environ["JP_DA_SECRET_KEY"],
        },
        headers={"X-Forwarded-For": EGRESS_IP},
        timeout=10,
    )
    res.raise_for_status()
    body = res.json()
    _cache["token"] = body["token"]
    _cache["exp"] = time.time() + body["expires_in"]
    return _cache["token"]


def normalize(code):
    # ハイフン・全角数字・小文字を吸収してから渡す（APIはどれも400で返す）
    code = code.strip().replace("-", "").replace("－", "").upper()
    code = code.translate(str.maketrans("０１２３４５６７８９", "0123456789"))
    if not re.fullmatch(r"[0-9]{3,7}|[0-9A-Z]{7}", code):
        raise ValueError(f"郵便番号（3〜7桁）かデジタルアドレス（7桁）ではありません: {code}")
    return code


def search(code, limit=10):
    res = requests.get(
        f"{BASE}/api/{API}/searchcode/{normalize(code)}",
        params={"limit": limit},
        headers={
            "Authorization": f"Bearer {get_token()}",
            "X-Forwarded-For": EGRESS_IP,
        },
        timeout=10,
    )
    if res.status_code == 404:
        return []  # 該当なしは404で返る
    res.raise_for_status()
    return res.json()["addresses"]


if __name__ == "__main__":
    for a in search("100"):
        print(a["zip_code"], a["pref_name"] + a["city_name"] + a["town_name"], a["town_roma"])

テスト用APIに向けて実行すると、100の前方一致で1000011 東京都千代田区内幸町 UCHISAIWAICHOと1000004 東京都千代田区大手町 OTEMACHIの2件が返りました。テスト用APIは収録データが数件しかないため、件数は本番と一致しません。

テスト用APIで確かめた入力ルールとエラー

公開ページには入力ルールが書かれていないため、2026年10月15日にテスト用APIへ実際にリクエストして結果を記録しました。フォームの入力値をそのまま渡すと、次のどれかで400になります。

limitを省くと1000件が既定で、1001以上は400です。件数を超えたpageを指定すると、エラーではなく空の配列が200で返ります。limit超過のメッセージが「デジタルアドレスの形式」になるなど、文言は原因と一致しないことがあるため、ログにはerror_code（例：400-1029-0001）を残して切り分けます。

過去の解説記事ではzip_codeが100-0005とハイフン付きで載っていますが、今回の実測ではハイフン無しの1000005で返りました。返却形式が変わっても壊れないよう、受け取った側でもハイフンを除いてから保存します。

汎用OAuthライブラリとの互換性を確認する独自仕様

認証はOAuth 2.0のclient_credentialsに似ていますが、OpenID Connectの仕様策定に携わった崎村夏彦氏がテスト用APIを検証した記事で指摘しているとおり、標準と違う点があります。

• シークレットの項目名がsecret_key：標準のclient_secretではない。テスト用APIにclient_secretで送ると400で弾かれた。
• X-Forwarded-Forヘッダーを要求する：本来はプロキシが付けるヘッダーを、クライアントが自分で付ける。
• 返却項目がtoken：標準のaccess_tokenではない。テスト用APIはフォーム形式の本文も受け付けたが、レスポンスの項目名は同じだった。
• token_typeがjwt：標準のBearerではない。ただし送るときはAuthorization: Bearerで通る。

Spring SecurityやAuthlibのclient_credentials実装は標準の項目名で送るため、設定を変えないままではトークン取得の段階で失敗します。トークン取得だけは上の例のように自前のHTTPリクエストで書くのが早道です。標準のclient_credentialsフローとの違いを確かめたい場合はOAuth 2.0とは？仕組み・認可フローと認証との違い、OAuth 2.1の変更点をわかりやすく解説で流れを見比べてください。

ブラウザから直接呼べない理由とサーバー経由の構成

このAPIをフロントエンドのfetchから呼ぶ構成は取れません。理由は2つあります。システムには固定IPを登録して呼ぶ仕様のため、利用者ごとに違うブラウザのIPからは通りません。加えて、本番ホストにOriginを付けてOPTIONSとGETを送ったところ、Access-Control-Allow-Originヘッダーは返りませんでした（2026年10月15日）。ブラウザはこのレスポンスを読めません。仕組みはCORSとは？仕組み・プリフライト・サーバー設定例・エラー解決を実装目線で解説のとおりです。

フォームの住所補完に使うなら、自社のサーバーに/address?code=…のような中継APIを置き、そこから公式APIを呼びます。secret_keyとトークンは中継側だけが持ちます。AWSのようにサーバーの出口IPが台数とともに増える環境では、NATゲートウェイで出口を固定IPにまとめ、そのIPを登録します。構築の手順はNAT Gatewayの構築手順とリージョナル移行：AZ設計とポート枯渇の実装対処にまとめています。

中継APIの設計では、公式APIのエラーをそのまま返さず、入力誤り（400）と該当なし（404）と障害（それ以外）をフロントで出し分けられる形に変換しておくと、入力画面の文言を作りやすくなります。既存の基幹システムやECへの組み込みを外部に任せる場合は、API開発・システム連携の支援も行っています。

ZipCloud・PostcodeJP・ケンオールとの料金・機能比較

「日本郵便 api」の検索結果には、公式APIのほかに郵便番号APIが並びます。料金と、ブラウザから直接呼べるかで分けると選びやすくなります。

ZipCloudは日本郵便の郵便番号データを検索するRESTのAPIで、JSONPのコールバックに対応しているため、登録なしでブラウザから呼べます。PostcodeJPは住所の候補検索に対応し、住所検索APIにはプラン別のリクエスト上限があります。自由形式住所を解析するAddress ParserはPreview提供です。ケンオールは定額制で、リクエスト数が増えても料金は変わらず、番地入りの住所文字列から郵便番号を引く逆引き検索を持っています。郵便番号系のAPIはフリープランに含まれず、登録から30日間の試用期間の後はスタンダード以上の契約が要ります。

公式APIの採用条件と他サービスが適する用途

公式APIを選ぶべきなのは、入力欄でデジタルアドレスを受け付けたい場合と、取引先の法人番号や電話番号をビジネスデジタルアドレスから引きたい場合です。比較表のZipCloud・PostcodeJP・ケンオールは、この2つの用途には対応していません。公式データであることを監査や社内説明で求められる業務システムでも、公式APIを選ぶ理由になります。

逆に、会員登録フォームで郵便番号から町域まで補完したいだけなら、公式APIは選ばない方が早く終わります。法人・個人事業主に該当しない個人は登録できず、利用資格がある場合もサーバーの中継とIPの固定が必要になるためです。ZipCloudならフロントのコードだけで動きます。番地まで入った住所文字列から郵便番号を引くなら、addresszipとケンオールの逆引き検索、PostcodeJPの住所解析を同じ住所データで比較して選びます。

よくある質問

郵便番号・デジタルアドレスAPIは無料ですか？

無料です。for Bizへの組織登録とシステム登録が必要ですが、利用料はかかりません。ただし一定時間内のリクエスト数には上限（レートリミット）が設けられています。具体的な数値は公開ページに無いため、ログイン後に参照できるAPIリファレンスや利用ガイドラインで確認してください。

個人でもAPIを使えますか？

個人事業主なら利用できます。for Bizでは法人か個人事業主として組織を登録する必要があります。ログインには個人のゆうIDを使えますが、法人・個人事業主に該当しない個人は組織を登録できません。趣味の開発なら、ZipCloudなど登録の要らないAPIを使います。

デジタルアドレスはAmazonで使えますか？

2026年10月時点で、Amazonはデジタルアドレス公式サイトの対応サービス一覧に載っていません。Amazonの「デジタル購入用の住所」はAmazon側の住所設定で、日本郵便のデジタルアドレスとは別物です。対応一覧には、郵便局アプリのゆうパック送り状作成、郵便局のネットショップ、楽天市場などが載っています。

ブラウザのJavaScriptから直接呼べますか？

呼べません。システムに登録した固定IPから呼ぶ仕様で、本番ホストはCORSを許可するヘッダーも返しません。自社のサーバーに中継APIを置き、そこから呼び出します。

ver1.0のまま使い続けても問題ありませんか？

当面は動きます。ver1.0で登録したシステムは2026年3月19日以降も使えます。ただし固定IPの編集やシステムの追加ができず、ビジネスデジタルアドレスの法人情報も返らず、ver1.0自体も時期未定で終了する予定です。サーバー移行や機能追加の予定があるなら、その前にver2.0で登録し直します。

関連記事

• OAuth 2.0とは？仕組み・認可フローと認証との違い、OAuth 2.1の変更点をわかりやすく解説
• Bearer Token（ベアラートークン）とは？読み方・Authorization: Bearerの書き方とJWTとの違い
• CORSとは？仕組み・プリフライト・サーバー設定例・エラー解決を実装目線で解説
• NAT Gatewayの構築手順とリージョナル移行：AZ設計とポート枯渇の実装対処
• Google API設計ガイドとは？AIPの規約とapi-linterでの準拠チェック手順【2026年10月】