住所補完JavaScriptリファレンス

PostcodeJP APIの住所補完JavaScriptを使用すれば、たった数行のJavaScriptコードを追加するだけでWebサイトの住所入力フォームに住所自動補完機能を追加できます。

実装の概要

住所補完JavaScriptをWebサイトへ導入するには、次の３つのステップを実施します。

STEP1 住所入力フィールドの用意

郵便番号    <input type="text" id="sample1_zip">
住所      <input type="text" id="sample1_addr">

Webページに住所入力フィールドを用意します。それぞれのフィールドにはWebページ上で一意となる任意のidを付与します。

STEP2 住所補完JavaScriptコードの適用

<script type="text/javascript" src="https://postcode-jp.com/js/postcodejp.js" charset="utf-8">
<script type="text/javascript">
var initPostcodeJp = function() {
    var autoComplement = new postcodejp.address.AutoComplementService('__apikey__');
    autoComplement.setZipTextbox('sample1_zip');
    autoComplement.add(new postcodejp.address.StateTownStreetTextbox('sample1_addr'));
    autoComplement.observe();
};
if(window.addEventListener){
  window.addEventListener('load', initPostcodeJp)
}else{
  window.attachEvent('onload', initPostcodeJp)
}
</script>

<!-- * "__apikey__" にはAPIキーを設定します。 -->

JavaScriptコードを記述します。 PostcodeJP API Webサイトの "JAVASCRIPTを試す"から "Edit in JSFiddle"リンクをたどることでコードを編集して試すこともできます。

STEP3 動作確認

住所補完JavaScriptを組み込んだWebページをインターネットブラウザで表示し、郵便番号を入力して住所が補完されるかテストします。

それでは、実装方法を詳しく見ていきましょう。

はじめに

住所補完JavaScriptは、Webページに住所補完機能を組み込むことを可能にするJavaScriptライブラリです。住所補完JavaScriptを利用したJavaScriptコードをHTMLに埋め込むだけで、郵便番号からの住所検索および住所の自動入力を実現できます。

<html lang="ja">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>

    <!-- 住所補完JavaScriptライブラリの読み込み -->
    <script type="text/javascript" src="https://postcode-jp.com/js/postcodejp.js" charset="utf-8"> </script>

    <script type="text/javascript">


    function initPostcodeJp() {

      // APIキーを指定して住所補完サービスを作成
      var postcodeJp = new postcodejp.address.AutoComplementService('__apikey__');

      // 郵便番号テキストボックスを指定
      postcodeJp.setZipTextbox('input_zip')

      // 住所補完フィールドを追加
      postcodeJp.add(new postcodejp.address.StateTownTextbox('input_state_town'));
      postcodeJp.add(new postcodejp.address.StreetTextbox('input_street'));

      // 郵便番号テキストボックスの監視を開始
      postcodeJp.observe();

    }
    if(window.addEventListener){
      window.addEventListener('load', initPostcodeJp)
    }else{
      window.attachEvent('onload', initPostcodeJp)
    }

    </script>
  </head>
  <body>

    <span style="font-weight: bold; ">郵便番号</span>
    <input type="text" size="12" id="input_zip" />

    <span style="font-weight: bold; ">住所１</span>
    <input type="text" size="32" id="input_state_town" />

    <span style="font-weight: bold; ">住所２</span>
    <input type="text" size="32" id="input_street" />

  </body>
</html>

住所補完を適用する基本的な流れは以下のようになります。

住所補完APIのロード
住所補完サービスオブジェクトの作成
サービスオブジェクトへ郵便番号テキストボックスを設定
サービスオブジェクトへ住所補完対象フィールドを追加
郵便番号テキストボックスの監視を開始

初めて住所補完APIを利用する場合、APIの理解を深める最短の方法は、シンプルで完全なコードをインスペクションすることです。例には、HTMLコードを含めた完全なコードが示されています。

住所補完JavaScriptの使い方

住所補完JavaScriptのロード

<script type="text/javascript" src="https://postcode-jp.com/js/postcodejp.js" charset="utf-8"></script>

外部JavaScriptファイルを読み込みます。 postcodejp.jsはバージョアップすることがあります。コピーを配置するのではなく、以下のようにPostcodeJP APIがホストしているJavaScriptファイルを直接読み込んでください。

APIキー取得とサービスオブジェクトの作成

住所補完JavaScriptのメインオブジェクトは、postcodejp.address.AutoComplementServiceのインスタンスです。コンストラクタにAPIキーを渡して、サービスオブジェクトを作成します。

サービスオブジェクトの作成とAPIキー設定

// AutoComplementServiceのコンストラクタにAPIキーを設定します。
var postcodeJp = 
  new postcodejp.address.AutoComplementService('ここにAPIキーを設定');

サービスオブジェクトには住所補完を適用する入力フィールドを追加したり、住所補完動作のオプションを設定できます。

APIキー

PostcodeJP APIは、APIキーを使用して住所補完リクエストを認証します。

APIキーの取得

以下の手順でAPIキーを取得します。

ダッシュボードに移動します。(アカウントをお持ちでない場合はアカウントを作成してください。)
ダッシュボードの「APIキーを作成」ボタンをクリックします。
作成されたAPIキーに制限を設定します。(APIキーの盗用、不正使用を防ぐため、HTTPリファラーやIPアドレスでAPIキーを保護します。)

APIキーを設定する

postcodejp.address.AutoComplementServiceのコンストラクタにAPIキーを設定します。

郵便番号テキストボックスを設定

setZipTextbox()メソッドに郵便番号テキストボックスのidまたはDOM要素を渡して、郵便番号テキストボックスを設定します。

後で説明するobserve()メソッドの呼出し後、郵便番号テキストボックスに郵便番号が入力されると住所検索がリクエストされます。

postcodeJp.setZipTextbox('sample1_zip');

var zipElement = document.getElementById('sample1_zip');
postcodeJp.setZipTextbox(zipElement);

住所補完対象フィールドの追加

サービスオブジェクトのadd()メソッドを使って、住所を自動入力するフィールドを追加します。
住所補完JavaScriptには、補完動作がカスタマイズされた住所補完対象フィールドオブジェクトが予め用意されています。

フィールドオブジェクトは、コンストラクタに入力フィールドのidまたはDOM要素を渡して作成します。
住所検索リクエストの結果は、サービスオブジェクトに追加された住所補完対象フィールドに基づき自動補完されます。

postcodeJp.add(new postcodejp.address.StateTownTextbox('sample1_address'));
postcodeJp.add(new postcodejp.address.StreetTextbox('sample1_address2'));

postcodejp.address.StateTextbox

都道府県テキストボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールドに都道府県が自動入力されます。

postcodejp.address.StateTownTextbox

都道府県市区町村テキストボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールドに都道府県+市区町村が自動入力されます。

postcodejp.address.TownTextbox

市区町村テキストボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールドに市区町村が自動入力されます。

postcodejp.address.StreetTextbox

町域テキストボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールドに町域が自動入力されます。

postcodejp.address.TownStreetTextbox

市区町村町域テキストボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールドに市区町村+町域が自動入力されます。

postcodejp.address.JigyosyoTextbox

事業所名テキストボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールドに事業所名が自動入力されます。

postcodejp.address.StateTownStreetTextbox

都道府県市区町村町域テキストボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールドに都道府県+市区町村+町域が自動入力されます。

postcodejp.address.StateSelectbox

postcodeJp.add(new postcodejp.address.StateSelectbox('stateSelectBox').byText());

都道府県セレクトボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールド(セレクトボックス)から、都道府県コードと一致するoptionタグのvalue値を探し、そのoptionが自動選択されます。
byText()を呼び出すことで、都道府県名と一致するoptionタグのtext値を探し、そのoptionが自動選択されます。

postcodejp.address.TownSelectbox

市区町村セレクトボックスを表すフィールドオブジェクトです。
サービスオブジェクトへ追加すると、コンストラクタで渡された入力フィールド(セレクトボックス)から、市区町村名コードと一致するoptionタグのvalue値を探し、そのoptionが自動選択されます。 byText()を呼び出すことで、市区町村名と一致するoptionタグのtext値を探し、そのoptionが自動選択されます。

postcodeJp.add(new postcodejp.address.TownSelectbox('townSelectBox').byText());

監視の開始

postcodeJp.observe();

サービスオブジェクトの作成と住所補完のための設定が完了したら、observe()メソッドを実行して、郵便番号テキストボックスの監視を開始します。

observe()メソッドの実行後、郵便番号テキストボックスに郵便番号が入力されるとPostcode APIが実行されされます。取得した住所情報はサービスオブジェクトに追加した住所補完対象フィールドに自動補完されます。

オプション

検索ボタンで補完する

郵便番号入力による自動補完を行わずに、検索ボタンをクリックすることで住所を補完するには、setAutoComplement()メソッドで自動補完を無効にし、setComplementButton()メソッドで検索ボタンを設定します。

// 自動補完を無効にする。
postcodeJp.setAutoComplement(false);

// 検索ボタンのidまたはエレメントを設定する
postcodeJp.setComplementButton('searchBtn');

postcodeJp.observe();

一般郵便番号と大口事業所郵便番号の有効無効

デフォルトでは、一般郵便番号の住所と大口事業所個別番号の住所ともに検索対象となります。
検索対象から大口事業所個別番号の住所を除外するには、enableOfficeAddress(false)を使用します。
検索対象から一般郵便番号の住所を除外するには、enableGeneralAddress(false)を使用します。

// 検索対象から大口事業所個別番号の住所を除外する
postcodeJp.enableOfficeAddress(false);

// 検索対象から一般郵便番号の住所を除外する
postcodeJp.enableGeneralAddress(false);

postcodeJp.observe();

フィールド設定後のコールバック

各フィールドの値が設定されたタイミングで実行されるコールバック関数を追加することができます。
setAdditionalFieldCallback()メソッドの引数にコールバック関数を渡します。

// elm: 値が設定されたDomエレメント  data: 住所データ
postcodeJp.setAdditionalFieldCallback(function(elm, data){
  if(console)console.log(elm);
});

postcodeJp.observe();

全てのフィールド設定後のコールバック

全てのフィールドの値が設定された後に一度だけ実行されるコールバック関数を追加することができます。 setAdditionalCallback()メソッドの引数にコールバック関数を渡します。

// data: 住所データ
postcodeJp.setAdditionalCallback(function(data){
  if(console)console.log(data);
});

postcodeJp.observe();

住所が存在しない場合のコールバック

入力された郵便番号に該当する住所が存在しない場合に実行されるコールバック関数を追加することができます。
setAdditionalCallback()メソッドの引数にコールバック関数を渡します。

// data: 住所データ
postcodeJp.setNotFoundCallback(function(){
  if(console)console.log('住所なし');
});

postcodeJp.observe();

住所が存在しない場合に住所フィールドをクリアする

入力された郵便番号に該当する住所が存在しない場合に住所フィールドを自動でクリアすることができます。
住所が存在しない場合に住所フィールドをクリアするには、setClearAddressIfNotFound(true)を使用します。
デフォルトでは、住所フィールドはクリアされません。

// 住所が存在しない場合に住所フィールドをクリアする
postcodeJp.setClearAddressIfNotFound(true);

postcodeJp.observe();

コンソールへの情報出力

setDumpResponse()メソッドの引数にtrueを渡すことで、パラメータとレスポンスがconsoleへ出力されます。

postcodeJp.setDumpResponse(true);