郵便局公式APIで郵便番号→住所の自動入力をkintoneに実装する

日本郵便が2025年5月に公開した公式API「郵便番号・デジタルアドレスAPI」の利用方法の解説です。
kintoneで郵便番号から住所を自動入力する仕組みを、アカウント登録からサンプルコードまで解説します。

📅 2025年6月🏷 kintone / 外部API / JavaScript⏱ 読了約15分

郵便局APIの特徴と利点
郵便局APIのアカウント作成方法
テスト用API認証情報と検索可能な郵便番号
本番用API認証情報とシステムリストの登録
APIの制限事項（CORS制限・レートリミット等）
テスト環境で動かすサンプルコード
サンプルコードを本番用APIに切り替える際の注意点
まとめ

01 郵便局APIの特徴と利点

　「郵便番号・デジタルアドレスAPI」は、日本郵便株式会社が2025年5月26日から提供を開始した公式APIです。従来、郵便番号から住所を取得するにはKEN_ALL.csvを独自にパースするか、非公式APIに依存するしかありませんでしたが、公式APIの登場により開発者の負担が大幅に軽減されました。

🏛️日本郵便公式・無料

日本郵便が直接提供する無料サービス。信頼性が高く、継続的なデータ更新が保証されています。

🔄常に最新データ

郵便番号データと常時連携しており、CSVの手動取得・更新作業が一切不要になります。

📍デジタルアドレス対応

7桁英数字の「デジタルアドレス」からも住所を取得可能。郵便番号とデジタルアドレスを1つのAPIで統合検索できます。

🏢法人情報の返却（新機能）

2026年3月以降は電話番号・法人番号など、ビジネス情報も返却。法人向け機能が充実しています。

🌐漢字・カナ・ローマ字

都道府県・市区町村・町域を漢字表記・カタカナ・ローマ字の3形式で取得可能です。

🔐OAuth 2.0認証

業界標準のOAuth 2.0 Client Credentials Flowを採用。HTTPS（TLS 1.2以上）で通信を暗号化します。

ℹ️法人・個人事業主向けサービスです

郵便番号・デジタルアドレス for Bizは、法人または個人事業主を対象としたサービスです。登録時に組織情報（法人名・個人事業主名など）の入力が必要になります。

02　郵便局APIのアカウント作成方法

APIを利用するには「郵便番号・デジタルアドレス for Biz」へのアカウント登録が必要です。
登録には「ゆうID」が必要になるため、まず「ゆうID」を取得してください。

ゆうIDを登録・取得する
日本郵便の共通認証サービス「ゆうID」を取得します。すでにお持ちの場合はスキップしてください。 1つの「ゆうID」につき1つのビジネスアカウントを登録できます。
郵便番号・デジタルアドレス for Biz にアクセスする
「郵便番号・デジタルアドレス for Biz」にアクセスし、「ゆうID」でサインインします。
組織情報を登録する
利用規約を確認・同意後、ユーザー名と組織情報（法人名 / 個人事業主名）を登録します。 1つの法人につき1つの組織を登録できます。
登録完了・ダッシュボードへ
登録が完了するとダッシュボードが表示されます。テスト用API認証情報はすぐに使用可能です。
本番APIは別途システムリストの登録（Section 4参照）が必要です。

⚠️ゆうIDは個人単位での取得が推奨されています

「ゆうID」はユーザー認証にのみ使用されます。法人の担当者ごとに「ゆうID」を用意するか、既存の個人「ゆうID」を使用してください。法人アカウントで「ゆうID」を取得する必要はありません。

03 テスト用API認証情報と検索可能な郵便番号

アカウント登録直後からテスト用APIが利用可能です。管理画面の「テスト用API認証情報」メニューからクライアントIDとシークレットキーを確認してください。テスト用と本番用でAPIのベースURLが異なる点に注意してください。

項目	テスト環境
ベースURL	`https://stub-qz73x.da.pf.japanpost.jp`
トークン取得	`POST /api/v1/j/token`
住所検索	`GET /api/v1/searchcode/{郵便番号}`
クライアントID	管理画面「テスト用API認証情報」→「システム情報」で確認
シークレットキー	同上

テスト環境では検索できる郵便番号が5種類に限定されています。すべて東京都千代田区の住所データです。これ以外の郵便番号は404エラーが返ります。

#	郵便番号（ハイフンなし）	都道府県	市区町村	町域
サンプル1	1020072	東京都	千代田区	飯田橋
サンプル2	1020082	東京都	千代田区	一番町
サンプル3	1010032	東京都	千代田区	岩本町
サンプル4	1010047	東京都	千代田区	内幸町
サンプル5	1010047	東京都	千代田区	大手町

⚠️　郵便番号はハイフンなしで送信してください

リクエストパラメーターの郵便番号は「1020072」のようにハイフンなしの7桁数字で指定します。「102-0072」のようにハイフンを含めると「デジタルアドレスの形式が正しくありません」エラーになります。 kintoneフィールドにハイフン付きで保存されている場合は、.replace(/-/g, '')で除去してから送信してください。

なお、テスト環境ではデジタルアドレス（7桁英数字）でも3種のサンプルが用意されています。郵便番号検索（searchcode）エンドポイントはデジタルアドレスも共用で受け付けます。

04 本番用API認証情報とシステムリストの登録

本番APIを利用するには、管理画面の「システムリスト」に利用するシステムを登録し、本番用のクライアントIDとシークレットキーを発行する必要があります。

システムリストを開く
管理画面の「サービス」→「郵便番号・デジタルアドレスAPI」→「システムリスト」に移動します。
「新規登録」から情報を入力する
システム名・固定IPアドレス・利用用途URLなど、本番環境の情報を入力して登録します。
シークレットキーを必ず控える
登録直後に表示されるシークレットキーはこのとき以外には確認できません。必ずこの画面でコピーして安全な場所に保管してください。
本番URLでAPIを呼び出す
本番のベースURLは管理画面またはAPIリファレンスで確認してください。テスト環境のURLのまま本番クレデンシャルを使っても動作しません。

🔑 シークレットキーは登録時のみ表示されます

本番環境のシークレットキーは、システム登録完了時の画面にしか表示されません。画面を閉じると二度と確認できないため、必ずその場でコピーして安全に保管してください。紛失した場合はシステムを再登録する必要があります。

📋 第三者へのAPI提供には特約への同意が必要

本APIを自社以外の第三者に提供する場合（例：kintoneプラグインとして販売・配布）は、システム登録時に「API組込みシステムの第三者提供特約」への同意が必要です。

05 APIの制限事項（CORS制限・レートリミット等）

kintoneカスタマイズJSでこのAPIを利用する際に必ず把握しておくべき制限事項を整理します。

🚫 CORS制限：ブラウザからの直接呼び出し不可 日本郵便APIはブラウザからのクロスオリジンリクエストを禁止しています。 kintoneのカスタマイズJSからfetch()で直接APIを叩くとCORSエラーになります。 kintoneプラグインのkintone.plugin.app.proxy()を使えばサーバーサイド経由で呼び出せるため、これがkintone連携における最もシンプルな回避策です。プラグイン化しない場合はNode.jsやPHPなど別途プロキシサーバーが必要です。
📍 本番環境：固定IPアドレスが必須 本番APIへのアクセスは、事前にシステムリストに登録した固定IPアドレスからのみ許可されます。動的IPや範囲指定（0.0.0.0/0）は使用できません。プロキシサーバーを用意する場合はそのサーバーに固定IPを割り当てる必要があります（例：GCPの静的IP）。最大10個まで登録可能です。なおIPv6は現時点で対応していません。
⏱ アクセストークンの有効期限：600秒 トークンは取得から600秒（10分）で失効します。有効期限切れのトークンでAPIを叩くと 401エラーが返ります。トークンをキャッシュして有効期限内は再利用し、失効直前（例：30秒前）に再取得する設計を推奨します。
📊 レートリミット 一定時間あたりのリクエスト数に制限があります（詳細は管理画面で確認）。大量レコードを一括処理する場合は1件ごとに0.5〜1秒の間隔を空けることを推奨します。
🧪 テスト環境：検索できる郵便番号は5種類のみ テスト環境（stub-qz73x.da.pf.japanpost.jp）では、東京都千代田区の5つの郵便番号と3つのデジタルアドレスサンプルしか検索できません。それ以外のコードは404が返ります。
➖ 郵便番号はハイフンなし7桁で指定 リクエストURLのパスパラメーターに郵便番号を含める際、ハイフンを含めてはいけません。ハイフンがあるとデジタルアドレスと誤認識され、形式エラーが返ります。

✅ kintoneプラグイン化でCORS・クレデンシャル管理を一挙解決

kintone.plugin.app.proxy()を使うと、kintoneのサーバーが仲介してAPIを呼び出してくれます。これによりCORS問題が解消され、さらにクレデンシャル（ClientID・SecretKey）を kintoneのプラグイン設定として安全に保管できます。ブラウザのJSにクレデンシャルを直書きする必要がありません。

06　テスト環境で動かすサンプルコード

テスト用API認証情報を使って、kintoneのカスタマイズJSから住所を取得するサンプルです。 APIエントリ情報を冒頭で宣言し、トークン取得→住所検索の結果をコンソールに出力します。このコードはkintoneアプリの「JavaScriptでカスタマイズ」にそのまま貼り付けて動作確認できます。

⚠️ このサンプルはテスト環境専用です

テスト用ベースURL・クライアントID・シークレットキーが固定値でコードに含まれています。本番環境では絶対にこの形式を使用しないでください（クレデンシャルがブラウザに露出します）。本番利用はSection 7の注意点に従い、kintoneプラグインのkintone.plugin.app.proxy()経由で実装してください。

kintone カスタマイズJSJavaScript

/**
 * 郵便局デジタルアドレスAPI × kintone
 * テスト環境動作確認用サンプル（CORS対応版）
 */
{
  'use strict';

  // ============================================================
  // ★ API エントリ情報（テスト環境）
  // ============================================================
  const TEST_BASE_URL = 'https://stub-qz73x.da.pf.japanpost.jp';
  const TOKEN_ENDPOINT = `${TEST_BASE_URL}/api/v2/j/token`;
  const SEARCH_ENDPOINT = `${TEST_BASE_URL}/api/v2/searchcode/`;

  // テスト用認証情報（管理画面「テスト用API認証情報」→「システム情報」で確認）
  const CLIENT_ID  = 'YOUR_TEST_CLIENT_ID';   // ← 管理画面から取得した値に変更
  const SECRET_KEY = 'YOUR_TEST_SECRET_KEY';  // ← 管理画面から取得した値に変更

  // テスト用に検索できる郵便番号5種（いずれか1つを指定）
  const TEST_POSTAL_CODE = '1020072';  // ← テスト用郵便番号（ハイフンなし7桁）

  // ============================================================
  // Step 1: アクセストークンを取得する
  // ============================================================
  const getAccessToken = () => {
    const headers = { 'Content-Type': 'application/json' };
    const body = {
      grant_type: 'client_credentials',
      client_id:  CLIENT_ID,
      secret_key: SECRET_KEY
    };

    // kintone.proxy(url, method, headers, data) は Promise を返します
    return kintone.proxy(TOKEN_ENDPOINT, 'POST', headers, body)
      .then(([bodyString, status]) => {
        if (status !== 200) {
          throw new Error(`トークン取得失敗: HTTP ${status}\n${bodyString}`);
        }
        
        // 戻り値のbodyStringは文字列なのでJSONパースが必要
        const data = JSON.parse(bodyString);
        console.log('[郵便局API] トークン取得成功:', data);
        return data.token;
      });
  };

  // ============================================================
  // Step 2: 郵便番号から住所を検索する
  // ============================================================
  const searchAddress = (token, postalCode) => {
    let code = postalCode.replace(/[^0-9]/g, '');
    const url = `${SEARCH_ENDPOINT}${code}`;
    const headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type':  'application/json'
    };

    // GET通信の場合でも、第4引数（data）には空のオブジェクト {} を渡す必要があります
    return kintone.proxy(url, 'GET', headers, {})
      .then(([bodyString, status]) => {
        if (status === 404) throw new Error('該当する住所が見つかりません');
        if (status !== 200) throw new Error(`住所検索失敗: HTTP ${status}\n${bodyString}`);
        
        const data = JSON.parse(bodyString);
        console.log('[郵便局API] 住所検索成功:', data);
        return data;
      });
  };

  // ============================================================
  // kintone イベント：レコード作成画面を開いたときに実行
  // ============================================================
  kintone.events.on('app.record.create.show', (event) => {
    console.log('[郵便局API] テスト開始 - 郵便番号:', TEST_POSTAL_CODE);

    getAccessToken()
      .then((token) => searchAddress(token, TEST_POSTAL_CODE))
      .then((result) => {
        console.log('[郵便局API] 取得件数:', result.count);
        result.addresses.forEach((addr, i) => {
          console.log(
            `[郵便局API] 住所[${i}]:`,
            `${addr.pref_name}${addr.city_name}${addr.town_name}`
          );
        });
      })
      .catch((err) => {
        console.error('[郵便局API] エラー:', err.message);
      });

    return event;
  });
}

レコード作成画面を開くとブラウザのコンソールに以下のような出力が確認できます。

コンソール出力例（郵便番号: 1020072）JSON

// Step1: トークン取得成功
[郵便局API] トークン取得成功: {
  token: "eyJ...",
  token_type: "jwt",
  expires_in: 600,
  scope: "J1"
}

// Step2: 住所検索成功
[郵便局API] 住所検索成功: {
  count: 1,
  page: 1,
  limit: 1000,
  searchtype: "zipcode",
  addresses: [{
    zip_code:  "102-0072",
    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",
    biz_name:  null,
    block_name: null,
    dgacode:   null,
    longitude: null,
    latitude:  null
  }]
}

[郵便局API] 取得件数: 1
[郵便局API] 住所[0]: 東京都千代田区飯田橋

07 サンプルコードを本番用APIに切り替える際の注意点

テスト環境で動作確認が取れたら、本番環境への切り替えを行います。単純にURLとクレデンシャル（認証情報）を差し替えるだけでは不十分で、設計上の変更が必要です。

クレデンシャル（認証情報）をカスタマイズJSに直書きしない。
本番のClientID・SecretKeyをkintoneカスタマイズJSに記述すると、kintoneにアクセスできる全ユーザーがブラウザの開発者ツールから参照できてしまいます。必ずkintone.plugin.app.proxy()経由か独自プロキシサーバー経由で呼び出してください。
ベースURLをテスト環境から本番環境に変更する。
テスト環境のＵＲＬと本番環境のURLは別物です。本番URLは管理画面またはAPIリファレンスで確認し、環境変数やプラグイン設定で切り替えられる設計にしておくと安全です。
接続元サーバーの固定IPをシステムリストに登録する
本番APIはIPアドレス制限があります。kintone.plugin.app.proxy()経由の場合はサイボウズのIPアドレスを、独自プロキシ経由の場合はそのサーバーの固定IPを事前に登録してください。サイボウズのIPアドレスレンジは公式ドキュメントを確認してください。
トークンキャッシュを必ず実装する。
テスト時は都度トークンを取得しても問題ありませんが、本番では同一セッション中に何度もトークン取得のリクエストを送るとレートリミットに影響します。有効期限（600秒）を考慮したキャッシュ機構を組み込んでください。
エラーハンドリングを本番品質に整える。
本番では401（トークン失効）・404（郵便番号なし）・429（レートリミット）など様々なエラーが起き得ます。ユーザーにわかりやすいエラーメッセージを表示し、401の場合はトークンを再取得してリトライする設計を推奨します。
郵便番号のハイフン除去処理を忘れない。 kintoneの郵便番号フィールドにはハイフン付き（102-0072）で保存されているケースがほとんどです。 APIへ送信する前に.replace(/[^0-9]/g, '')でハイフンを除去してください。
本番APIでは全郵便番号を検索できるが、テスト時との挙動差異に注意する。
特に複数件ヒットする郵便番号（同一コードに複数の町域が対応するケース）や、大字・小字を含む複雑な住所のテストを本番データで追加実施することを推奨します。

🔌 kintoneプラグインとして実装するのがベストプラクティス

本番利用においては、kintoneプラグインとして実装し、kintone.plugin.app.proxy()でAPI呼び出しを行うのが推奨です。クレデンシャルをkintoneプラグイン設定として暗号化保存でき、CORS問題も自動的に解消されます。また、フィールドマッピングをGUI設定にすることでエンジニア以外でも運用できます。

まとめ

日本郵便の公式「郵便番号・デジタルアドレスAPI」は、無料・高信頼・最新データという三拍子が揃ったシステム開発者にとって非常に使いやすいAPIです。kintoneとの組み合わせでは CORS制限という壁がありますが、プラグインのkintone.proxy()を活用すれば比較的シンプルに解決できます。

📌 この記事のポイント

日本郵便公式APIで、無料・常時最新・OAuth 2.0認証の安心設計
登録には「ゆうID」と組織情報（法人/個人事業主）が必要
テスト環境は検索できる郵便番号が5種（千代田区のみ）に限定される
本番環境は固定IPアドレスのシステム登録が必須。シークレットキーは登録時のみ表示
ブラウザからの直接呼び出しはCORSでブロックされる。プロキシかkintoneプラグインのproxy()を使う
郵便番号はハイフンなし7桁で送信。有効期限600秒のトークンはキャッシュして再利用する
本番移行時はクレデンシャルをJSに直書きせず、プラグイン設定として保管する

日本郵便「郵便番号・デジタルアドレスAPI」実装ガイド

※ 本記事の情報は2025年6月時点のものです。
　最新情報は郵便番号・デジタルアドレス for Biz 公式ドキュメントをご確認ください。

🔨 自分でカスタマイズしてみたい方へ

以下のNote記事で本記事のカスタマイズ事例を紹介しています。
記事内で紹介しているカスタマイズコードは、無料で利用できるので是非挑戦してみて下さい。

「note:アプリ活用研究会（キン活）」は、当サイトのメンバーが執筆しています。

法人名から法人番号・インボイス番号を自動検索するカスタマイズ｜アプリ活用研究会（キン活）

今回は、業務システムでニーズの高い「国税庁法人番号システムWeb-API」とkintoneを連携させ、会社名を入力するだけで法人番号やインボイス登録番号、住所情報を自動的に取得・表示するJavaScriptカスタマイズの手法について解説します。１．カスタマイズの目的企業間取引（BtoB）を行うシステムの顧客マスターデータに「正しい法人番号」や「インボイス登録番号」を登録することは、現在の税務・会計管理において必須要件となっています。しかし、これらの情報を手動で検索して…

🧩 プラグインのご紹介

当社が開発した「法人番号検索プラグイン」をご紹介します。
60日間の試用版をダウンロードすることもできますので、ぜひお試しください。

法人番号検索プラグイン｜API連携で法人情報を自動取得する

国税庁の法人番号検索WEB-APIと連携して、法人情報を自動取得するプラグインです。試用版のお申込みこのプラグインで解決できる課題kintoneで取引先や顧客情報を登録するとき、こんな面倒を感じたことはありませんか？会社名・住所・法人番号をいちいち手で調べて入力している入力ミスや表記ゆれが起きて、後でデータの整理が大変インボイス登録番号を確認するたびに国税庁のサイトを開いている法人番号検索プラグインを使えば、これらの問題がまとめて解決します。kintoneのレコード入力画面で…

🌸 アプリテンプレートの販売

本記事でご紹介しているアプリテンプレートを、下記の料金プランで販売しています。
導入をご希望の方は、各プランの「お申込み／お問い合わせ」ボタンからお問い合わせください。
※国税庁APIのアプリケーションIDは、自社で申請して準備して頂く必要があります。

■ 料金プラン

◆単品販売（買取型）は、導入サポート付きの価格です。
　単品動作タイプは60,000円、２アプリ連携タイプは100,000円、3つ以上連携タイプは150,000円です。
◆簡易サポート契約では、当サイトのアプリテンプレートとプラグインを合計6種類までご利用できます。
◆会員サポート契約では、ご利用範囲「無制限」で運用ヘルプデスク対応までフルサービスでご提供します。

項目	単品販売	簡易サポート	会員サポート
料金体系	60,000円 (税抜)	120,000円 (税抜)	360,000円 (税抜)
契約期間	なし	毎年更新	6か月更新
導入サポート	✔	✔	✔
メールサポート	×	✔	✔
チャットサポート	×	✔	✔
バージョンアップ対応	×	✔	✔
運用ヘルプデスク対応	×	×	✔
商品のご利用範囲	本商品のみ	6種類までご利用可能ユーザー数10名まで	無制限ユーザー数30名まで
お問い合わせ／お申し込み	購入する	お申込み	お問い合わせ

🏫 kintone人材育成研修

この様なカスタマイズを自分で出来る様になりたい方は、当サイトの「Kintome人材育成」上級コースの受講をご検討して下さい。当サイトのTIPSで紹介しているカスタマイズ例のテンプレートを使えば、簡単に実装出来ます！
上級コースの受講者には、特典で当サイトのカスタマイズテンプレート（3種類まで）と３か月のサポート契約を無償でご提供しています。

研修目的を「カスタマイズテンプレートのアプリ導入」とする研修メニューもご提案可能です。

📣カスタマイズ・導入支援いたします！

本記事の様な「kintoneアプリのカスタマイズ」をご希望の企業様へ
kintoneを便利に活用できるカスタマイズと運用支援は、ぜひ当社にご相談ください！

お問い合わせはこちらからどうぞ！

#kintone #Javascript #API連携 #郵便局 #郵便番号・デジタルアドレスAPI

Tips

01 郵便局APIの特徴と利点

🏛️日本郵便公式・無料

🔄常に最新データ

📍デジタルアドレス対応

🏢法人情報の返却（新機能）

🌐漢字・カナ・ローマ字

🔐OAuth 2.0認証

ℹ️法人・個人事業主向けサービスです

02　郵便局APIのアカウント作成方法

⚠️ゆうIDは個人単位での取得が推奨されています

03 テスト用API認証情報と検索可能な郵便番号

⚠️　郵便番号はハイフンなしで送信してください

04 本番用API認証情報とシステムリストの登録

🔑 シークレットキーは登録時のみ表示されます

📋 第三者へのAPI提供には特約への同意が必要

05 APIの制限事項（CORS制限・レートリミット等）

✅ kintoneプラグイン化でCORS・クレデンシャル管理を一挙解決

06　テスト環境で動かすサンプルコード

⚠️ このサンプルはテスト環境専用です

kintone カスタマイズJSJavaScript

07 サンプルコードを本番用APIに切り替える際の注意点

🔌 kintoneプラグインとして実装するのがベストプラクティス

まとめ

📌 この記事のポイント

🔨 自分でカスタマイズしてみたい方へ

🧩 プラグインのご紹介

🌸 アプリテンプレートの販売

🏫 kintone人材育成研修

📣カスタマイズ・導入支援いたします！

事例紹介

Tips

お気軽にご相談ください。

Tips

01 郵便局APIの特徴と利点

🏛️日本郵便公式・無料

🔄常に最新データ

📍デジタルアドレス対応

🏢法人情報の返却（新機能）

🌐漢字・カナ・ローマ字

🔐OAuth 2.0認証

ℹ️法人・個人事業主向けサービスです

02 郵便局APIのアカウント作成方法

⚠️ゆうIDは個人単位での取得が推奨されています

03 テスト用API認証情報と検索可能な郵便番号

⚠️ 郵便番号はハイフンなしで送信してください

04 本番用API認証情報とシステムリストの登録

🔑 シークレットキーは登録時のみ表示されます

📋 第三者へのAPI提供には特約への同意が必要

05 APIの制限事項（CORS制限・レートリミット等）

✅ kintoneプラグイン化でCORS・クレデンシャル管理を一挙解決

06 テスト環境で動かすサンプルコード

⚠️ このサンプルはテスト環境専用です

kintone カスタマイズJSJavaScript

07 サンプルコードを本番用APIに切り替える際の注意点

🔌 kintoneプラグインとして実装するのがベストプラクティス

まとめ

📌 この記事のポイント

🔨 自分でカスタマイズしてみたい方へ

🧩 プラグインのご紹介

🌸 アプリテンプレートの販売

🏫 kintone人材育成研修

📣カスタマイズ・導入支援いたします！

事例紹介

Tips

お気軽にご相談ください。

02　郵便局APIのアカウント作成方法

⚠️　郵便番号はハイフンなしで送信してください

06　テスト環境で動かすサンプルコード