郵便番号検索API

このAPIは、郵便事業株式会社様（旧日本郵政公社）が公開している郵便番号のデータを取得する機能を提供します。

郵便番号から住所、住所から郵便番号の取得が可能です。

お知らせ

【重要】郵便番号検索APIサービスの終了について

リクエストの構築

リクエストは、「REST」を用いて行います。

URLの構築は、リクエストURLにリクエストパラメータを「引数=値」という形式で指定します。複数のリクエストパラメータを指定する場合は、「&」を用いてつなげます。

例：
http://api.postalcode.jp/v1/zipsearch?zipcode=33200&callback=callback

リクエストURL

http://api.postalcode.jp/v1/zipsearch?

リクエストパラメータ

パラメータ値説明
zipcode（またはwordのいずれか必須） string（半角3文字以上必要） 郵便番号を指定する。ハイフンの有無は問いません。前方一致で検索する。
word（またはzipcodeのいずれか必須） string 住所の一部を漢字、ひらがな、カタカナで指定する。
format json(デフォルト)
xml
PHP		 出力するフォーマットを指定する。
callback string JSONP形式で出力する場合のコールバック関数名。[a-zA-Z0-9_]が使用できる。
ie UTF-8
Shift_JIS
EUC-JP
ISO-2022-JP		 入力する文字の文字コード。指定がない場合は、入力された文字を自動判別する。
oe UTF-8(デフォルト)
Shift_JIS
EUC-JP
ISO-2022-JP		 出力時の文字コード。

リクエストパラメータの「zipcode（郵便番号）」か「word（検索キーワード）」は、どちらか一方が必須となります。両方が指定された場合は、「zipcode」で検索されます。

サンプルリクエスト

郵便番号332を検索して、JSONP形式でデータを受け取る場合
http://api.postalcode.jp/v1/zipsearch?zipcode=332&callback=callback

「川口市」を検索して、XML形式でデータを受け取る場合
http://api.postalcode.jp/v1/zipsearch?word=%E5%B7%9D%E5%8F%A3%E5%B8%82&format=xml

レスポンスフィールド

フィールド説明
address 住所の郵便番号の情報です。zipcode, prefecture, city, town, prefecture_yomi, city_yomi, town_yomiが設定されます。
office 事業所の個別郵便番号の情報です。zipcode, prefecture, city, town, street, office_name, office_name_yomiが設定されます。
zipcode 郵便番号が、「9999999」の形式で設定されます。
prefecture 都道府県名が設定されます。
city 市区町村名が設定されます。
town 町域名が設定されます。
office_name 大口事業所等名が設定されます。
street 大口事業所等名の小字名、丁目、番地等が設定されます。
prefecture_yomi 都道府県名のよみ（カタカナ）が設定されます。
city_yomi 市区町村名のよみ（カタカナ）が設定されます。
town_yomi 町域名のよみ（カタカナ）が設定されます。
office_name_yomi 大口事業所等名のよみ（カタカナ）が設定されます。

レスポンスヘッダー

HTTPヘッダーとは別にエラーが発生した場合に特別なレスポンスヘッダーを付与しています。

形式は以下の形式になります。
X-GT-Error: エラーコード

エラーコード説明
WS00001
WS00002		 パラメータ不足。
WS00003
WS00004		 内部エラー。

サンプルレスポンス

以下は、zipcode=33200 のクエリー結果をJSONP形式で取得したときの結果です。
⇒[サンプルレスポンス]

callback( { "zipcode": {"a1" :{ "zipcode":"3320000","prefecture":"埼玉県","city":"川口市","town":"以下に掲載がない場合","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"イカニケイサイガナイバアイ" }
,"a2" :{ "zipcode":"3320031","prefecture":"埼玉県","city":"川口市","town":"青木","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"アオキ" }
,"a3" :{ "zipcode":"3320001","prefecture":"埼玉県","city":"川口市","town":"朝日","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"アサヒ" }
,"a4" :{ "zipcode":"3320005","prefecture":"埼玉県","city":"川口市","town":"新井町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"アライチョウ" }
,"a5" :{ "zipcode":"3320029","prefecture":"埼玉県","city":"川口市","town":"荒川町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"アラカワチョウ" }
,"a6" :{ "zipcode":"3320023","prefecture":"埼玉県","city":"川口市","town":"飯塚","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"イイヅカ" }
,"a7" :{ "zipcode":"3320024","prefecture":"埼玉県","city":"川口市","town":"飯原町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"イイハラチョウ" }
,"a8" :{ "zipcode":"3320014","prefecture":"埼玉県","city":"川口市","town":"金山町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"カナヤマチョウ" }
,"a9" :{ "zipcode":"3320015","prefecture":"埼玉県","city":"川口市","town":"川口","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"カワグチ" }
,"a10" :{ "zipcode":"3320007","prefecture":"埼玉県","city":"川口市","town":"河原町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"カワハラチョウ" }
,"a11" :{ "zipcode":"3320016","prefecture":"埼玉県","city":"川口市","town":"幸町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"サイワイチョウ" }
,"a12" :{ "zipcode":"3320017","prefecture":"埼玉県","city":"川口市","town":"栄町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"サカエチョウ" }
,"a13" :{ "zipcode":"3320006","prefecture":"埼玉県","city":"川口市","town":"末広","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"スエヒロ" }
,"a14" :{ "zipcode":"3320032","prefecture":"埼玉県","city":"川口市","town":"中青木","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ナカアオキ" }
,"a15" :{ "zipcode":"3320022","prefecture":"埼玉県","city":"川口市","town":"仲町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ナカチョウ" }
,"a16" :{ "zipcode":"3320034","prefecture":"埼玉県","city":"川口市","town":"並木","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ナミキ" }
,"a17" :{ "zipcode":"3320033","prefecture":"埼玉県","city":"川口市","town":"並木元町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ナミキモトマチ" }
,"a18" :{ "zipcode":"3320035","prefecture":"埼玉県","city":"川口市","town":"西青木","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ニシアオキ" }
,"a19" :{ "zipcode":"3320021","prefecture":"埼玉県","city":"川口市","town":"西川口","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ニシカワグチ" }
,"a20" :{ "zipcode":"3320025","prefecture":"埼玉県","city":"川口市","town":"原町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ハラマチ" }
,"a21" :{ "zipcode":"3320003","prefecture":"埼玉県","city":"川口市","town":"東領家","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ヒガシリョウケ" }
,"a22" :{ "zipcode":"3320013","prefecture":"埼玉県","city":"川口市","town":"舟戸町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"フナトチョウ" }
,"a23" :{ "zipcode":"3320012","prefecture":"埼玉県","city":"川口市","town":"本町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ホンチョウ" }
,"a24" :{ "zipcode":"3320027","prefecture":"埼玉県","city":"川口市","town":"緑町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ミドリチョウ" }
,"a25" :{ "zipcode":"3320026","prefecture":"埼玉県","city":"川口市","town":"南町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ミナミチョウ" }
,"a26" :{ "zipcode":"3320028","prefecture":"埼玉県","city":"川口市","town":"宮町","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ミヤチョウ" }
,"a27" :{ "zipcode":"3320011","prefecture":"埼玉県","city":"川口市","town":"元郷","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"モトゴウ" }
,"a28" :{ "zipcode":"3320002","prefecture":"埼玉県","city":"川口市","town":"弥平","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"ヤヘイ" }
,"a29" :{ "zipcode":"3320004","prefecture":"埼玉県","city":"川口市","town":"領家","prefecture_yomi":"サイタマケン","city_yomi":"カワグチシ","town_yomi":"リョウケ" }
}, "office":{} } );

サンプルアプリケーション

以下は、郵便番号から住所の入力を支援するサンプルです。

郵便番号  
住所

HTMLのソース

<table class="input">
 <tr>
  <th>郵便番号</th>
  <td><input type="text" id="zipcode" style="width:7em;" maxlength="8" /> <input type="button" onclick="zipsearch();return false;" value="住所検索" /></td>
 </tr>
 <tr>
  <th>住所</th>
  <td><input type="text" id="address" style="width:20em;" maxlength="100" /></td>
 </tr>
</table>

<script language="javascript" type="text/javascript">
<!--

function zipsearch()
{
  var zipcode = document.getElementById( 'zipcode' ).value;
  window.open( 'sample_pop.html?zipcode='+encodeURIComponent( zipcode ) , 'address_search', "width=800,height=500,location=no,menubar=no,toolbar=no,resizable=yes,scrollbars=yes" );
}

function set_address( obj )
{
  var target = document.getElementById( 'address' );
  
  if( obj.zipcode.match( /[0-9]{5}00$/ ) )
  {
    target.value = obj.prefecture + obj.city;
  }
  else
  {
    target.value = obj.prefecture + obj.city + obj.town;
    if( obj.street ) target.value += obj.street ;
  }

  document.getElementById( 'zipcode' ).value = obj.zipcode.substr(0, 3) + '-' + obj.zipcode.substr(3);
}
 
//-->
</script>

ポップアップした画面のHTMLのソース

<html>
<head>
<title>住所検索</title>
</head>

<body bgcolor="#ffffff" style="text-align:left;background-color:#ffffff;">
<p style="text-align:center;">
郵便番号を3桁以上入力して検索ボタンを押してください。
</p>

<p>
<table width="100%">
 <tr><td align="center">
  <table>
   <tr>
    <td style="white-space:nowrap;">郵便番号</td>
    <td><input type="text" name="zipcode" id="zipcode" value="" /></td>
    <td><input type="button" name="search" value="検索" onclick="search(); return false;" /></td>
   </tr>
  </table>
 </td></tr>
</table> 
</p>

<div id="codes"></div>

<script language="javascript" type="text/javascript">
<!--

var zip_data = null;

function search()
{
  var zipcode = document.getElementById( 'zipcode' ).value;
  
  if( ! check_zipcode( zipcode ) )
   return false;
  var target = document.createElement('script');
  target.charset = 'utf-8';
  target.src = 'http://api.postalcode.jp/v1/zipsearch?zipcode='+encodeURIComponent( zipcode )+'&callback=callback1';

  document.body.appendChild(target);
}

function callback1( data )
{
  zip_data = data;
  var html = '<table style="width:100%" class="dataview">';
  html += '<col style="width:1em;">';
  for (var i in zip_data.zipcode )
  {
    html += '<tr><td><input type="button" name="" value="利用する" onclick="used( \''+ i +'\' );return false;" /></td><td style="white-space:nowrap">' + data.zipcode[i].zipcode.substr(0,3) + '-' + data.zipcode[i].zipcode.substr(3) +'</td><td style="white-space:nowrap">' + data.zipcode[i].prefecture + '</td><td style="white-space:nowrap">' + data.zipcode[i].city  + '</td><td style="white-space: nowrap;text-align:left;">' +  data.zipcode[i].town  + "</td><td> </td></tr>\r\n";
  }
  for (var i in zip_data.office )
  {
    html += '<tr><td><input type="button" name="" value="利用する" onclick="used( \''+ i +'\' );return false;" /></td><td style="white-space:nowrap">' + data.office[i].zipcode.substr(0,3) + '-' + data.office[i].zipcode.substr(3) +'</td><td colspan="3" style="white-space:nowrap">' + data.office[i].office_name + '</td><td style="white-space:nowrap">' + data.office[i].prefecture + data.office[i].city + data.office[i].town + data.office[i].street + "</td></tr>\r\n";
  }
  html += "</table>\r\n";

  document.getElementById( 'codes' ).innerHTML = html;
}

function used( i )
{
  if( ! zip_data ) return false;

  if( window.opener )
  {
    if( zip_data.zipcode[i] )
    {
      window.opener.set_address( zip_data.zipcode[i] );
    }
    else if( zip_data.office[i] )
    {
      window.opener.set_address( zip_data.office[i] );
    }
  }
  

  window.close();
}

function check_zipcode( zipcode )
{
  if( ! zipcode ) return false;
  if( 0 == zipcode.length ) return false;
  
  if( ! zipcode.match( /^[0-9]{3}[-]?[0-9]{0,4}$/ ) )
  {
    return false;
  }
  
  return true;
}

function init_page()
{
  window.focus();
  
  var arg = location.search.substr(1).split( "&" );
  
  for( i = 0 ; i < arg.length ; i ++ )
  {
    if( arg[i].substr( 0, 8 ) == 'zipcode=' )
    {
      var values = arg[i].split("=");
  document.getElementById( 'zipcode' ).value = values[1];
  break;
    }
  }
  
  search();
}

window.onload = init_page;

//-->
</script>

</body>
</html>

データの更新頻度

1日1回データの更新があるかどうか郵便事業株式会社様（旧日本郵政公社）のHPをチェックして更新されていた場合、データベースの更新を行っています。

ご利用にあたって

本サービスの利用にあたっては、クレジット表示および利用規約に従うものとします。