郵便番号-住所検索API

郵便番号-住所対応表は、日本郵便サイトで配布されているKEN_ALL.CSVのデータを解析して生成しています。毎月の1日の深夜に対応表を生成しなおしますので、比較的新しいデータで検索が可能です。

---

リクエストURI

GET https://api.zipaddress.net/

上記URIに以下のパラメータを付加してリクエストを送信して下さい。

パラメータ

パラメータ名	概要	必須/任意	取りうる値と形式	初期値
zipcode	検索したい郵便番号	必須	xxx-xxxx（ハイフン付き） またはxxxxxxx（ハイフン無し7桁）の形式	-
lang	日本語またはローマ字指定	任意	ja または rome	ja
callback	JSONPリクエストのコールバック関数 このパラメータを付加したリクエストは、 自動的にJSONPリクエストと判別されます。	任意	JavaScriptの関数名として有効な文字列	-

※リクエスト/レスポンス共に文字コードはUTF-8です。

HTTPリクエスト

通常のHTTPリクエスト（リクエストに"callback"パラメータを含めない）に対しては、JSONデータをそのまま返却します。

リクエスト：

https://api.zipaddress.net/?zipcode=453-0809

レスポンス：

HTTP/1.1 200 OK
...
Conent-Type: application/json; charset=UTF-8
...

{"code":200,"data":{"pref":"\u611b\u77e5\u770c","address":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a","city":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a","town":"\u4e0a\u7c73\u91ce\u753a","fullAddress":"\u611b\u77e5\u770c\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a"}}
            

---

JSONPリクエスト

"callback"パラメータを含めたリクエストの場合、JavaScriptの実行形式でレスポンスが返却されます。

リクエスト：

https://api.zipaddress.net/?zipcode=453-0809&callback=sample

レスポンス：

HTTP/1.1 200 OK
...
Content-Type: application/javascript; charset=UTF-8
...

sample({"pref":"\u611b\u77e5\u770c","address":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a","city":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a","town":"\u4e0a\u7c73\u91ce\u753a","fullAddress":"\u611b\u77e5\u770c\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a"}, false);
            

※レスポンスはUnicode形式にエンコードされています。

HTTPリクエスト

プロパティ名	概要	データ形式	備考
code	ステータスコード	"200"などの数値文字列	-
data	実際の返却データ	Object	pref: 都道府県の文字列 city: 市区町村の文字列 town: 町域名の文字列 address: 市区町村の文字列（cityとtownを結合したもの） fullAddress: 都道府県+市区町村+町域名の結合文字列
message	リクエスト失敗時のメッセージ	文字列	codeプロパティが"200"以外の場合にのみセットされます

APIはリクエストに対して全て200を返却するので、住所が見つかった、もしくはエラーなどの判定は、レスポンスのcodeプロパティにより判定してください。

---

JSONPリクエスト

callbackパラメータを実行する形式で返却されます。callback関数は以下の様な引数を2つ渡す形式で実行されます：

callback(object response, boolean err);

それぞれの引数は、以下のようなデータを取ります。

引数	データ
response	住所データのオブジェクト（HTTPリクエストの場合のdataプロパティの値と同じ）。 住所が見つからない、またはエラーの場合はcode,messageをプロパティに持つオブジェクト
err	エラーが発生したかどうか。住所が見つかった（成功した）場合はfalse、住所が見つからなかった、またはエラーの場合はtrue

コールバック関数のハンドリングについてはSDKの項も参考にしてください。

APIリクエストサンプル

郵便番号453-0809に該当する住所を検索し、JSONフォーマットでレスポンスを受け取ります。

リクエスト

https://api.zipaddress.net/?zipcode=4530809

レスポンス

{
  "code":200,
  "data":{
    "pref":"\u611b\u77e5\u770c",
    "address":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a",
    "city":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a",
    "town":"\u4e0a\u7c73\u91ce\u753a",
    "fullAddress":"\u611b\u77e5\u770c\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a"
  }
}
            

---

JSONPリクエストサンプル

郵便番号453-0809に該当する住所を検索し、JSONデータを引数にコールバック関数sampleを実行します。

リクエスト

https://api.zipaddress.net/?zipcode=4530809&callback=sample

レスポンス

sample({
  "pref":"\u611b\u77e5\u770c",
  "address":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a",
  "city":"\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a",
  "town":"\u4e0a\u7c73\u91ce\u753a",
  "fullAddress":"\u611b\u77e5\u770c\u540d\u53e4\u5c4b\u5e02\u4e2d\u6751\u533a\u4e0a\u7c73\u91ce\u753a"
}, false);
            

コールバック関数sample

window.sample = function(obj, err) {
  if ( err ) {
    return alert(obj.message); // エラー表示
  }
  
  // 住所表示処理
  document.querySelector('[name=pref]').value    = obj.pref;
  document.querySelector('[name=address]').value = obj.address;
};
            

SDKの読み込み

以下のURIからJavaScriptファイルを読み込みます。

https://api.zipaddress.net/sdk/zipaddr.min.js

SDKが使用する名前空間

SDKが読み込まれると、「window.ZA」というモジュールが作られます。名前空間の衝突に注意してください。

SDKを使ったJSONPリクエスト

郵便番号送信のシンプルなリクエストと、要素を指定するお任せなリクエストと2パターンが利用できます。

シンプルなリクエスト（コールバック処理を自分でやりたい方向け）

引数に郵便番号とコールバック関数を渡すだけの簡単なリクエストです。その代わり、エラー処理や取得した住所データのセットは自分でやらないといけません。
郵便番号の呼び出しにフックして、何か処理を挟みたい時にはこちらの方法をオススメします。

サンプルコード

// jQueryなら$とかやってください
document.addEventListener('DOMContentLoaded', function() {
  
  // 検索ボタンなど
  var btn = document.getElementById('zipaddr');
  // 郵便番号データ
  var zipcode = document.getElementById('zipcode');

  // クリックイベントでリクエスト
  btn.addEventListener('click', function() {
    // リクエスト
    ZA.request(zipcode.value, function(data, err) {
      // エラーがあったか見つからない
      if ( err ) {
        return alert(data.message);
      }

      // データセット
      document.getElementById('address').value = data.fullAddress;
    });
  });
}, false);
            

ZA.request()がSDKリクエストを行う部分です。ページ内に複数検索ブロックがあっても動作します。詳しくはSDKリファレンスを参照して下さい。

お任せリクエスト（自動的にセットまでしたい方向け）

AjaxZip2みたいに最初にセットする要素などのパラメータをセットしてイベント監視するタイプです。こちらも複数ブロックに対しても動作可能です。

お任せリクエストの場合、city及びtownの値は使用できません。

サンプルコード

// jQueryなら$とかやってください
document.addEventListener('DOMContentLoaded', function() {
  
  // 検索ボタンなど
  var btn = document.getElementById('zipaddr');

  // リクエストハンドル生成
  var handle = ZA.register({
                 zip1    : ZA.node('zip1'),
                 zip2    : ZA.node('zip2'),
                 pref    : ZA.node('pref'),
                 address : ZA.node('address')
              });
  // イベント監視
  handle.event(btn, 'click');

}, false);
            

ZA.register()でアプリケーションセットを生成します。引数はハッシュのみ受け付けます。パラメータの種類はSDKリファレンスを参照して下さい。

リファレンス

ZAモジュールについてのメソッドとパラメータ詳細です。

---

HTMLElement/null ZA.node(string id/name)

  引数の文字列をid、またはnameとして持つ要素を取得します。優先順位はid→nameです。見つかった場合は要素を、見つからなければnullが戻ります。

---

object ZipAddr ZA.register(object params)

  引数に渡したパラメータに従ったZipAddrインスタンスを生成します。引数によって挙動を変更することができます。

パラメータ名	概要	設定可能な値	デフォルト値
zipMode	郵便番号の取得モード	separate（3桁-4桁分離型）またはcombi（一体型）	separate
addrMode	取得した住所のセットモード	separate（都道府県-住所分離型）またはcombi（一体型）	separate
zip1	郵便番号上3桁入力要素	HTMLElementまたはnull ※zipModeがseparateの場合は必須	null
zip2	郵便番号下4桁入力要素	HTMLElementまたはnull ※zipModeがseparateの場合は必須	null
zip	郵便番号全桁入力要素	HTMLElementまたはnull ※zipModeがcombiの場合は必須	null
pref	都道府県入力要素	HTMLElementまたはnull ※addrModeがseparateの場合は必須	null
address	住所入力要素	HTMLElementまたはnull ※addrModeがseparateの場合は必須	null
lang	日本語/ローマ字	jaまたはrome	ja

指定したモードによって、要素の検証が行われます。zipModeまたはaddrModeに対応したパラメータがnullの場合は例外が投げられます。

また、生成されたインスタンスに対して、event()メソッドで検索のトリガーを指定します。

  ZipAddr.event(HTMLElement element, string eventType)

    第一引数にトリガーとなる要素、第二引数に起動イベント名を指定します。

---

void ZA.request(string zipCode, function callback[, string lang])

  zipCodeを元に住所を検索し、callbackが実行されます。langには日本語/ローマ字を指定できます。

<php

$handle = curl_init("https://api.zipaddress.net?zipcode=900-0012");
curl_setopt($handle, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1);
curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($handle);
curl_close($handle);

echo $result;