郵便番号検索APIでZoho CRMに住所を自動入力｜日本郵便の公式APIとZipCloudを比較

株式会社etika（エティカ）CRMサポートセンターです。

郵便番号からの住所の自動入力とは、郵便番号の7桁を入れると、郵便番号検索APIが返す都道府県・市区町村・町名が自動で入る仕組みです。Zoho CRMの標準機能にはないため、外部の郵便番号検索APIを呼ぶ仕組みを自分で作ります。

この記事では、九州の小売店のZoho CRM構築で作った仕組みをもとに、使えるAPI2つの比較と、実装の手順、途中で当たったZoho側の制約をまとめます。

郵便番号検索APIはどれを使う？日本郵便の公式APIとZipCloudの違い

郵便番号から住所を引くAPIとして、今回は次の2つを比べました。利用条件は、2026年10月7日に各社の公式ページで確かめた範囲だけを書いています。

	日本郵便「郵便番号・デジタルアドレスAPI」	ZipCloud（郵便番号検索API）
提供元	日本郵便株式会社	株式会社アイビス
料金	無料（公式ガイドに「ご利用は無料です」と記載）	公式ページに料金の記載は見当たらない
登録	必要。ゆうIDの登録 → 「郵便番号・デジタルアドレス for Biz」の事業者アカウントと組織の登録 → システムの登録と規約への同意	不要。APIキーもなく、URLに郵便番号を付けて呼ぶ
認証	OAuth 2.0 / OpenID Connect（クライアントIDとシークレットキーでトークンを取る）	なし
データの更新	毎月末に更新される郵便番号データCSVを元にしている（公式FAQ）	取り込んだデータの日付を公式ページに掲示（確認時点で「2026年9月30日更新分」）。更新の間隔の明記は見当たらない
回数の制限	あり。具体的な数値は案内されていない（公式FAQ）	規約に「アクセス回数、アクセス時間の制限など」を設けることがあると記載
停止・保証	公式の事業者向けサービス	規約に「事前通知なしで、本APIの全部または一部を停止または中断することができる」「一切の保証をしない」と記載
その他	第三者への提供は、特別な契約条件に同意した場合を除き制限	―

仕様と規約の原文は、日本郵便の郵便番号・デジタルアドレスAPIの利用ガイドと、ZipCloudのAPIリファレンスで確かめられます。

ZipCloudは、すぐに使える手軽さが強みです。一方で、規約上は予告なく止まることがありえます。日本郵便のAPIは公式のサービスで無料ですが、登録の手続きと、認証の仕組みが要ります。

なお、どちらも元になるのは日本郵便の郵便番号データです。日本郵便のAPIも「毎月末に更新されるCSV」を元にしているため、データの新しさで大きな差はないと考えています。差が出るのは、提供の安定性と始めるまでの手間です。

当社の進め方：ZipCloudで先に動かし、日本郵便へ差し替える

今回は、次の二段構えにしました。

日本郵便のAPIの登録を、お客様の事業者名義で先に始めてもらう
登録が終わるまでの間は、ZipCloudで自動入力を動かす
登録が済んで認証の情報を受け取ったら、APIの呼び先だけを差し替える

ZipCloudが途中で止まっても、保存済みの住所は壊れません。自動入力が働かず、手入力に戻るだけです。この点をお客様に説明したうえで、許容してもらいました。

差し替えを楽にするため、外部のAPIとの接点を1か所に集める作りにしました。呼び出し側には、APIによらず同じ形で結果を返します。

{"status": "ok", "candidates": [{"prefecture": "東京都", "city": "千代田区", "town": "千代田"}]}

status は4種類です。

ok：1件以上見つかった
notfound：通信は成功したが、該当なし
invalid：郵便番号が7桁でない
error：通信や読み取りに失敗した

ZipCloudは、存在しない郵便番号でもHTTPの応答は200のままで、結果が null になります（2026年9月に当社で確認）。通信の失敗と区別するために、notfound を分けています。

住所は何欄に分けるべき？実装の前に決める住所の持ち方

住所を郵便番号と住所の二欄にまとめる持ち方と、郵便番号から建物名まで五欄に分ける持ち方を比べ、市区町村で絞り込めるかが分かれ目であることを示した図

APIを選ぶより先に決めておくべきなのが、CRMで住所をどう持つかです。

	2欄にまとめる	5欄に分ける
欄	郵便番号＋住所（1行）	郵便番号／都道府県／市区町村／町名・番地／建物名
入力の手間	少ない	欄は増えるが、自動入力があれば手間はあまり変わらない
地域での絞り込み	郵便番号の前方一致で行う（例：「100で始まる」）	市区町村の単位で絞り込める

判断の分かれ目は「市区町村ごとに顧客を抜き出す場面があるか」です。郵便番号の頭3桁でもかなり絞れますが、区ごとにDMを送るなら分けたほうが確実です。

今回は、旧システムから移すデータが4つに分かれていたため、それに合わせて5欄に分けました。持ち方はデータ移行の前に決めてください。 移行した後に変えると、全件を入れ直すことになります。自動入力の作りも、どちらの持ち方かで変わります。移行前に項目の対応を確かめる方法は「Zoho CRMへのデータ移行で漏れを防ぐ」で紹介しています。

Zoho側で当たった制約（2026年9月時点）

実装の途中で、Zoho側の制約にいくつか当たりました。いずれも当社が2026年9月に確認した時点のものです。

1. 新しい複合の住所項目は、クライアントスクリプトで扱えなかった

この組織の連絡先の住所は、国・都道府県・市区町村・郵便番号などが1つの枠にまとまった、新しい形式の「住所」項目でした。Zohoの公式のお知らせでは、この項目へのクライアントスクリプトの対応は「進行中」とされていました。実機でも、住所の欄を変えても onChange が発火せず、値を読んでも空が返りました。

そこで、住所は自前のカスタム項目5つ（郵便番号・都道府県・市区町村・町名番地・建物名）に持ち替え、標準の住所項目はレイアウトから外しました。代わりに、標準の住所項目が持つ地図の機能は使えなくなります。

2. 外部のドメインは「信頼するドメイン」への登録が要る

クライアントスクリプトからZipCloudを呼ぶと、最初は「信頼されていないドメイン」というエラーで止まりました。設定 → 開発者スペース → 信頼するドメイン に zipcloud.ibsnet.co.jp を登録すると通りました。ウィジェット（別の枠で動く画面）では、この制限はかかりませんでした。

3. 詳細画面では、スクリプトから値を入れられない

Zohoの公式FAQには、詳細画面の項目ではクライアントスクリプトによる値の書き込み（setValue()）に対応していないと書かれています。そのままでは、詳細画面で郵便番号だけを直したとき、住所が古いまま残ります。

そこで、詳細画面を開いたときに郵便番号の欄だけ編集できないようにするスクリプトを入れました。郵便番号を変えたいときは「編集」から入ってもらい、そこで自動入力を働かせます。番地や建物名は、詳細画面でも直せるままにしています。

// 連絡先・詳細ページ・onLoad
var field = ZDK.Page.getField("Postal_Code");
if (field) {
  field.setReadOnly(true);
}

クライアントスクリプトの実装

連絡先の作成・編集・複製の3つのページに、同じスクリプトを登録します。クライアントスクリプトで項目を自動入力する別の例は「Zoho CRMで氏名を姓・名から自動入力する構成案」にまとめています。郵便番号の項目の onChange で動かします。項目のAPI名は一般的な名前に置き換えています。

var FIELDS = {
  zip: "Postal_Code",
  state: "Prefecture",
  city: "Municipality",
  street: "Street_Address"
};

function digitsOf(value) {
  return String(value || "").replace(/[^0-9]/g, "");
}

// 応答は文字列で返ることがあるため、文字列ならJSONとして読む
function bodyOf(response) {
  var value = response;
  if (value && typeof value === "object" && value.data !== undefined) {
    value = value.data;
  }
  if (typeof value === "string") {
    try { value = JSON.parse(value); } catch (e) { return null; }
  }
  return value;
}

// すべての候補で同じ値なら、その値を返す。割れていたら空
function commonValue(candidates, key) {
  var first = candidates[0][key] || "";
  for (var i = 1; i < candidates.length; i++) {
    if ((candidates[i][key] || "") !== first) return "";
  }
  return first;
}

function apply(candidates) {
  ZDK.Page.getField(FIELDS.state).setValue(commonValue(candidates, "prefecture"));
  ZDK.Page.getField(FIELDS.city).setValue(commonValue(candidates, "city"));
  // 町名・番地は利用者が番地を書き足す欄なので、空のときだけ入れる
  var street = ZDK.Page.getField(FIELDS.street);
  var town = commonValue(candidates, "town");
  if (!String(street.getValue() || "").trim() && town) {
    street.setValue(town);
  }
  if (candidates.length > 1) {
    ZDK.Client.showAlert("この郵便番号には複数の住所があります。市区町村・町名は手入力してください。");
  }
}

var digits = digitsOf(ZDK.Page.getField(FIELDS.zip).getValue());
if (digits.length === 7) {
  // 保存の形を「100-0001」にそろえる
  ZDK.Page.getField(FIELDS.zip).setValue(digits.slice(0, 3) + "-" + digits.slice(3));

  Promise.resolve(zrc.get("https://zipcloud.ibsnet.co.jp/api/search?zipcode=" + digits))
    .then(function (response) {
      var body = bodyOf(response);
      var rows = (body && body.results) || [];
      if (!rows.length) {
        ZDK.Client.showAlert("該当する住所が見つかりませんでした。住所は手入力してください。");
        return;
      }
      apply(rows.map(function (r) {
        return { prefecture: r.address1, city: r.address2, town: r.address3 };
      }));
    })
    .catch(function () {
      ZDK.Client.showAlert("住所を取得できませんでした。住所は手入力してください。");
    });
}

実装で気を付けた点です。

応答の形を確かめる：クライアントスクリプトで使える zrc（Zohoのリクエスト用の仕組み）は、当社の確認では応答の本体を文字列で返しました。そのまま results を読むと「該当なし」になるため、文字列ならJSONとして読み直します。
非同期の処理を待つ：fetch などの応答は後から届きます。結果が返ってから項目に入れます。
番地を消さない：都道府県と市区町村は毎回上書きします。町名・番地の欄は、空のときだけ入れます。上書きすると、書き足した番地が町名だけに戻ってしまいます。
複数の候補を黙って選ばない：1つの郵便番号に複数の住所が返ることがあります。当社の確認では、498-0000 は愛知県と三重県の2件、別の郵便番号では同じ県内の2つの市町が返りました。先頭を黙って採ると、市区町村を取り違えます。すべての候補で共通の値だけを入れ、残りは手入力を促します。
都道府県は選択肢と表記をそろえる：都道府県を選択リストにする場合は、APIが返す「東京都」「大阪府」といった表記と、選択肢の値をそろえておきます。

ログは console.log ではなく log() で出すと、クライアントスクリプトのログ画面で確かめられました。

日本郵便のAPIはクライアントスクリプトから直接呼べる？差し替えの注意

日本郵便のAPIは、クライアントIDとシークレットキーでトークンを取って呼びます。シークレットは、画面で動くスクリプトに書いてはいけません。シークレットを画面側に置けないため、ブラウザから直接呼ぶ設計にはできません。なお当社は、この記事の時点で日本郵便の登録待ちのため、認証を付けた実際の呼び出しはまだ行っていません。

そのため差し替えのときは、次のどちらかの形になります。

サーバー側で動くDeluge関数から、Zohoの「接続（Connection）」に預けた認証の情報を使って呼び、クライアントスクリプトはその関数を呼ぶ
クライアントスクリプトから接続を指定して呼ぶ（当社が2026年9月に確かめた時点では、クライアントスクリプトに接続を呼ぶための入口〈ZDK.Apps.CRM.Connections〉は見当たりませんでした。zrc で接続を指定できるとされていますが、書き方と動作は未確認です）

接続を確実に使えるのはサーバー側のDeluge関数（とウィジェット）です。クライアントスクリプトから使う形は、確かめてから選んでください。

当社はDeluge関数の受け皿も先に作りましたが、途中でいくつかの点に当たりました。

関数をクライアントスクリプトから呼ぶには、関数の設定で REST API（OAuth2.0）を画面からオンにする必要がありました。APIからは変えられませんでした
関数のAPI名は、作るときに大文字を混ぜても、すべて小文字で登録されました
Delugeで空の文字列に replaceAll を使うと、実行時エラーで止まりました。受け取った値をログに出し、空かどうかを先に見てから加工します
クライアントスクリプトから関数を呼んだとき、引数が関数に届かない事象がありました（当社では未解決）

このため、現時点ではZipCloudを直接呼ぶ形で動かしています。日本郵便へ移るときの経路は、登録が済んで認証の情報を受け取ってから、実機で確かめる予定です。

まとめ：作る前のチェックリスト

住所を2欄にまとめるか、5欄に分けるかを、データ移行の前に決める
日本郵便のAPIを使うなら、事業者名義での登録を早めに始める
待つ間はZipCloudで動かす。止まったら手入力に戻ることを合意しておく
外部のAPIとの接点を1か所に集め、結果の形をそろえる
標準の住所項目がクライアントスクリプトで扱えるかを、実機で先に確かめる
信頼するドメインの登録と、詳細画面での郵便番号の編集禁止を入れる
番地を消さない・複数の候補を黙って選ばない作りにする

Zohoの関数をAPIから呼ぶ準備は、Zoho APIのセルフクライアント設定もあわせてご覧ください。標準機能にない入力補助をどこまで作り込むかの考え方は「Zoho CRMのカスタマイズで何が変わる？」で扱っています。

入力補助の作り込みのご相談は、Zoho CRMカスタマイズ・設定代行サービスでお受けしています。

TL;DR（この記事の要点）

郵便番号検索APIは、登録不要ですぐ使えるZipCloudと、事業者登録が必要な日本郵便の公式API（郵便番号・デジタルアドレスAPI）の2つが候補
ZipCloudの規約には、予告なく停止・中断できること、一切の保証をしないことが書かれている。止まっても手入力に戻るだけの作りにしておく
日本郵便のAPIは無料だがOAuth 2.0の認証が要る。秘密の情報を画面側のスクリプトに置けないため、作りが変わる前提で設計する
当社が確認した時点では、Zohoの新しい複合の住所項目はクライアントスクリプトに対応しておらず、住所は自前のカスタム項目に持ち替えた
番地は自動では入らない。町名・番地の欄は空のときだけ入れ、1つの郵便番号に複数の住所がある場合は共通の部分だけ入れる

よくある質問

郵便番号から住所を入れると、お客様の情報が外部に送られますか？

外部のAPIに送るのは郵便番号の7桁だけです。氏名や電話番号は送りません。ZipCloudも日本郵便のAPIも、HTTPSで通信します。

ZipCloudが止まったら、CRMのデータはどうなりますか？

保存済みの住所データには影響しません。自動入力が働かなくなり、住所を手で入れる形に戻るだけです。当社の実装では、取得に失敗したら「住所は手入力してください」と表示し、項目には何も入れないようにしています。

番地まで自動で入りますか？

入りません。郵便番号から分かるのは、都道府県・市区町村・町域（町名）までです。番地や建物名は手で入力してもらいます。そのため、番地を書き足した後に郵便番号を入れ直しても、番地が消えない作りにしておく必要があります。

日本郵便のAPIは、Zohoのクライアントスクリプトから直接呼べますか？

日本郵便のAPIはクライアントIDとシークレットキーが要るため、画面側のスクリプトには置けません。当社は登録待ちで、認証を付けた実際の呼び出しはまだしていませんが、設計上は、Zohoの接続やサーバー側の関数を経由する形を想定しています。

郵便番号検索APIは、ZipCloudと日本郵便のどちらを選べばよいですか？

すぐに動かしたいなら登録不要のZipCloud、長く安定して使いたいなら日本郵便の郵便番号・デジタルアドレスAPIが向いています。ZipCloudは規約上、予告なく止まることがあります。当社は日本郵便の登録を進める間だけZipCloudで動かし、後から呼び先を差し替えられる形にしました。

郵便番号検索APIはどれを使う？日本郵便の公式APIとZipCloudの違い

当社の進め方：ZipCloudで先に動かし、日本郵便へ差し替える

住所は何欄に分けるべき？実装の前に決める住所の持ち方

Zoho側で当たった制約（2026年9月時点）

1. 新しい複合の住所項目は、クライアントスクリプトで扱えなかった

2. 外部のドメインは「信頼するドメイン」への登録が要る

3. 詳細画面では、スクリプトから値を入れられない

クライアントスクリプトの実装

日本郵便のAPIはクライアントスクリプトから直接呼べる？差し替えの注意

まとめ：作る前のチェックリスト

よくある質問

関連記事

Zoho CRMのクライアントスクリプトで氏名を姓・名から自動入力｜画面以外はDelugeで補う構成

Zoho CRMのカスタマイズで何が変わる？知らないと損をするカスタム機能

Zoho APIをスクリプトから叩く最短ルート｜Self Client / Client Credentials設定

関数・ワークフローの不具合や改修をご相談ください。

関数・ワークフローの不具合や改修を
ご相談ください。