intra-mart Accel Platform 郵便番号検索(日本) 仕様書 第3版 2019-08-01

5. 郵便番号検索の利用方法

5.1. インポートした郵便番号データの検索方法

郵便番号検索を行うには、以下のURLにGETリクエストを送信します。
http://<HOST>:<PORT>/<CONTEXT_PATH>/api/zipcode/search
検索URLへのクエリとして次のパラメータを付与します。
パラメータ名 必須項目 形式 備考
zipcode 数値
検索する郵便番号を3桁から7桁で指定します。
このパラメータとwordのいずれかを指定する必要があります。
word 文字列
検索する住所の一部を指定します。
このパラメータとzipcodeのいずれかを指定する必要があります。
start × 数値
取得開始位置を指定します。
指定されていない場合は検索結果の1件目から返却します。
length × 数値
取得件数を指定します。
指定されていない場合は検索結果を全件返却します。
callback × 文字列
コールバック用の関数の名前を指定します。
このパラメータはクロスドメインの場合に利用します。

リクエストを送信すると以下のようにJSONでエンコードされたレスポンスが返却されます。
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "error": false,
    "total": 53,
    "data": [{
        "city": "港区",
        "cityKana": "ミナトク",
        "jisCode": "13103",
        "officeName": "",
        "officeNameKana": "",
        "oldZipCode": "107  ",
        "prefecture": "東京都",
        "prefectureKana": "トウキョウト",
        "street": "",
        "town": "赤坂",
        "townKana": "アカサカ",
        "zipCode": "1070052"
    }]
}

パラメータに誤りがある場合等、検索時にエラーが発生した場合は以下のようなレスポンスが返却されます。
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "error": true,
    "errorMessage": "郵便番号または住所のいずれかを指定してください。",
    "total": 0,
    "data" : []
}

5.2. 検索ダイアログを使用した検索画面の作成方法

intra-mart Accel Platform 上に画面を作成する場合、クライアントJavaScript APIを使用することで検索ダイアログを利用できます。
検索ダイアログの使用方法は以下の通りです。
  1. 外部JSファイル「im_zipcode/csjs/im_zipcode.js」を読み込む。
    <imart type="head"> 内に、スクリプトタグを実装し、外部JSファイルを読み込みます。

    <script type="text/javascript" src="im_zipcode/csjs/im_zipcode.js"></script>

  2. クライアントJavaScript API 「imuiZipcodeDialog」を呼び出す。
    任意のオペレーションでダイアログを呼び出すスクリプトを実装します。
    $('#button').click(function() {
        $('#dialog').imuiZipcodeDialog();
    });
  3. ダイアログで選択された住所を受け取った際の動作を実装します。
    function callback(e, data) {
        $('#zip-code').val(data.zipCode);
        var address = data.prefecture + data.city + data.town;
        $('#address').val(address);
    };
imuiZipcodeDialog の詳しい利用方法は クライアントサイド JavaScript を参照してください。

5.2.1. サンプルプログラム

検索ダイアログを利用して郵便番号を取得するサンプルは以下のとおりです。
<imart type="head">
    <title>郵便番号検索サンプル</title>
    <script type="text/javascript" src="im_zipcode/csjs/im_zipcode.js"></script>
    <script type="text/javascript">
    $(function() {
        $('#search-button').click(function() {
            // ダイアログを呼び出します。
            $('#zipcode-dialog').imuiZipcodeDialog();
        });
    });
    function callback(e, data) {
        // ここに検索結果を受け取った際の動作を実装します。
        $('#zip-code').val(data.zipCode);
        $('#address').val(data.prefecture + data.city + data.town);
        
        // ダイアログを自動で閉じる場合は、 close を実行します。
        $(this).imuiZipcodeDialog('close');
    }
    </script>
</imart>
<div class="imui-form-container">
    <input type="text" id="zip-code"/>
    <input type="text" id="address"/><br/>
    <input type="button" id="search-button" value="検索" class="imui-small-button">
</div>
<div id="zipcode-dialog"></div>

5.3. 住所の郵便番号データインポートのクレンジング処理拡張方法

郵便番号データをインポートする際に、任意の加工を行いたい場合には、データクレンジング処理を拡張できます。
拡張方法は以下のとおりです。
  1. サービス構成ファイルを作成し、拡張クラスが有効になるようにします。
    サービス構成ファイルは以下のファイルを作成し、拡張クラスのクラス名をフルパッケージで指定します。

    META-INF/services/jp.co.intra_mart.foundation.zip_code.io.cleanser.ZipCodeDataCleanser

  2. 実測クラスを作成します。
    データクレンジングの実装クラスは以下のインタフェースの実装クラスとして作成します。

    jp.co.intra_mart.foundation.zip_code.io.cleanser.ZipCodeDataCleanser

  3. 作成したクラスの isSupport メソッドにこの実装クラスが有効になる条件を実装します。
  4. 作成したクラスの cleansing メソッドに任意のデータ加工処理を実装します。

実装例については、サンプルプログラムを参照してください。

5.3.1. サンプルプログラム

クレンジング処理のサンプルプログラムは以下の通りです。
  • サービス構成ファイル 「 META-INF/services/jp.co.intra_mart.foundation.zip_code.io.cleanser.ZipCodeDataCleanser

    sample.SampleZipCodeCleansing
    
  • クレンジング処理実装 「 sample.SampleZipCodeCleansing.java

    package sample;
    
    import jp.co.intra_mart.foundation.zip_code.io.data.ZipCodeData;
    import jp.co.intra_mart.foundation.zip_code.io.cleanser.ZipCodeDataCleanser;
    
    /**
     * 事業所の個別郵便番号データのクレンジング処理サンプルです。
     * @author INTRAMART
     * @version 8.0.0
     */
    public class SampleZipCodeCleansing implements ZipCodeDataCleanser {
    
        /**
         * クレンジングパターンに「sample」が指定された場合に、このクレンジング処理が有効になります。
         * @see jp.co.intra_mart.system.zip_code.io.cleanser.ZipCodeDataCleanser#isSupport(java.lang.String)
         */
        @Override
        public boolean isSupport(String cleansingType) {
            return cleansingType.equals("sample");
        }
    
        @Override
        public ZipCodeData[] cleansing(ZipCodeData info) {
            // TODO ここにデータの加工処理を実装します。
            // 複数のデータに分割して登録を行う場合はZipCodeDataオブジェクトを複数件返却します。
            // 受け渡されたデータを登録しない場合は null を返却します。
            return new ZipCodeData[] { info };
        }
    
    }
    

5.4. 事業所の個別郵便番号データインポートのクレンジング処理拡張方法

郵便番号データをインポートする際に、任意の加工を行いたい場合には、データクレンジング処理を拡張できます。
拡張方法は以下のとおりです。
  1. サービス構成ファイルを作成し、拡張クラスが有効になるようにします。
    サービス構成ファイルは以下のファイルを作成し、拡張クラスのクラス名をフルパッケージで指定します。

    META-INF/services/jp.co.intra_mart.foundation.zip_code.io.cleanser.OfficeZipCodeDataCleanser

  2. 実測クラスを作成します。
    データクレンジングの実装クラスは以下のインタフェースの実装クラスとして作成します。

    jp.co.intra_mart.foundation.zip_code.io.cleanser.OfficeZipCodeDataCleanser

  3. 作成したクラスの isSupport メソッドにこの実装クラスが有効になる条件を実装します。
  4. 作成したクラスの cleansing メソッドに任意のデータ加工処理を実装します。

実装例については、サンプルプログラムを参照してください。

5.4.1. サンプルプログラム

クレンジング処理のサンプルプログラムは以下の通りです。
  • サービス構成ファイル 「 META-INF/services/jp.co.intra_mart.foundation.zip_code.io.cleanser.OfficeZipCodeDataCleanser

    sample.SampleOfficeZipCodeCleansing
    
  • クレンジング処理実装 「 sample.SampleOfficeZipCodeCleansing.java

    package sample;
    
    import jp.co.intra_mart.foundation.zip_code.io.data.OfficeZipCodeData;
    import jp.co.intra_mart.foundation.zip_code.io.cleanser.OfficeZipCodeDataCleanser;
    
    /**
     * 事業所の個別郵便番号データのクレンジング処理サンプルです。
     * @author INTRAMART
     * @version 8.0.0
     */
    public class SampleOfficeZipCodeCleansing implements OfficeZipCodeDataCleanser {
    
        /**
         * クレンジングパターンに「sample」が指定された場合に、このクレンジング処理が有効になります。
         * @see jp.co.intra_mart.system.zip_code.io.cleanser.OfficeZipCodeDataCleanser#isSupport(java.lang.String)
         */
        @Override
        public boolean isSupport(String cleansingType) {
            return cleansingType.equals("sample");
        }
    
        @Override
        public OfficeZipCodeData[] cleansing(OfficeZipCodeData info) {
            // TODO ここにデータの加工処理を実装します。
            // 複数のデータに分割して登録を行う場合はOfficeZipCodeDataオブジェクトを複数件返却します。
            // 受け渡されたデータを登録しない場合は null を返却します。
            return new OfficeZipCodeData[] { info };
        }
    
    }