API 1.11からAPI 3.0への検索メソッドの変更点

API 1.11から API 3.0への検索メソッドの変更点について説明します。

API3.0を利用したサンプル

次のサンプルは、API3.0を利用したサンプルとして、住所をフリーワードで検索するフォームを作成します。
住所フリーワード検索は、検索条件として任意の文字列を指定し、一致する住所を返却する検索です。

解説

API 1.11から API 3.0への変更手順は以下の通りです。
※本項では検索機能のみを解説します。地図表示やマーカー重畳については、該当ページを参照してください。

検索を実行するには

API 1.11
1.検索クラス及び検索条件クラスのインスタンスを生成する
2.検索条件を指定する
3.検索終了後に実施する関数をイベントリスナ登録する
4.検索を実施する

API 3.0
1.検索クラスの第一引数に利用検索API名を指定する
2.検索クラスの第二引数に検索条件を指定する
3.検索クラスの第三引数に検索終了後に実行するコールバックメソッドを指定する
4.検索を実施する

住所フリーワード検索に利用するクラス

API 1.11では複数のクラスを使いますが、API 3.0ではZDC.SearchクラスでWebAPIを取り扱うことになります。
API 1.11検索クラス役割と置き換えられるのは以下の通りです。

説明	1.11	3.0
WebAPI名を指定	ZdcSearchAddressクラス	第一引数apiname
検索条件を指定	ZdcSearchAddressOptionsクラス	第二引数params
検索結果を取得する	ZdcSearchAddressResultクラス	第三引数func
検索結果データを扱う	ZdcSearchAddressItemクラス	JSON形式

/* 3.0での検索名指定方法 */
var apiname = 'address/word';
ZDC.Search.getByZmaps(apiname,params,func)

検索条件を指定するには

API 1.11ではZdcSearchAddressOptionsのプロパティに付加しますが、 API 3.0では第2引数paramsに指定します。

/* API 1.11での指定方法 */
ZdcSearchAddressOptions.startPos = 0;

/* API 3.0での指定方法 */
params = {
      word: word,
      datum: 'TOKYO',
      limit: '0,10',
      addrcode: '',
      llunit: 'dec',
      ambiguoussearch: 'F'
};
ZDC.Search.getByZmaps(apiname, params);

検索結果を判定するには

API 1.11では'end'イベントが発生していましたが、
API 3.0では戻り値の第一引数にステータスオブジェクトが、第二引数には検索実行結果オブジェクトが入ります。

例では、ステータスオブジェクトを取得してhttpステータス、実行結果オブジェクトを取得して判別しています。

/* API 1.11での判定方法 */
function execResult(result) {
    if(result.status == '1') { // 検索成否はresult.statusに格納される
        msg =('パラメータエラーが発生しました');
        alert(msg);
        ・・・
    } else if(result.status == '0') {
        msg = '検索に成功しました';
        alert(msg);
        showResult(result); // 検索に成功した場合のみ、表示する
    }
}

/* API 3.0での判定方法 */
var determine = function(status, res) {
      if (status.code === 200 && res.status.code === '0000') {　// httpステータスとAPIレスポンスで判定
            markerDisp(res);
      } else {
            alert(status.text);
      }
};
ZDC.Search.getByZmaps(apiname, params, determine);

検索結果からデータを取り出すには

API 1.11 ZdcSearchAddressResultオブジェクトのitemsプロパティ配列の各要素のプロパティにアクセスして取得していました。

API 3.0 戻り値の第二引数(検索実行結果オブジェクト)にアクセスして取得します。

/* API 3.0での取り出し方法 */
var items = res.item;
...
var itemlatlon = new ZDC.LatLon(items[i].point.lat, items[i].point.lon);

本項ではフリーワードでの住所検索を取り扱いましたが、その他機能のクラス名についても変わっています。

対応表はAPI(1_3系)機能比較表（excel）をご参照ください。

ソースコード

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<script src="//test.api.its-mo.com/v3/loader?key=JSZddc5111626c8|Zo4wz&api=zdcmap.js,control.js,search.js&enc=UTF8" type="text/javascript"></script>
<style type="text/css">
</style>
<script type="text/javascript">
    var map, msg, arrmrk = [];

    function loadMap(){
        var latlon  = new ZDC.LatLon(35.6778614, 139.7703167);
        map = new ZDC.Map(document.getElementById('ZMap'),{
            zoom: 9,
            mapType: ZDC.MAPTYPE_HIGHRES_LV18
        });
        msg = new ZDC.MsgInfo(latlon, {offset: ZDC.Pixel(0, -18)});
        map.addWidget(msg);
        map.addWidget(new ZDC.ScaleBar());
        map.addWidget(new ZDC.Control());
    }

    function searchClick(){
        var word = document.getElementById('word').value;
        if (word == ''){
            alert('住所を入力してください');
            return;
        } else {
            exec(word);
        }
    }

    function exec(word){
        var apiname = 'address/word';
        var params = {
            word: word,
            datum: 'TOKYO',
            limit: '0,10',
            addrcode: '',
            llunit: 'dec',
            ambiguoussearch: 'F'
        }
        var determine = function(status, res) {
            if (status.code === 200 && res.status.code === '0000') {
                markerDisp(res);
            } else {
                alert(status.text);
            }
        }
        ZDC.Search.getByZmaps(apiname, params, determine);
    }



    function markerDisp(res) {
        if (res.item.length === 0) {
            alert('検索結果が0件です。');
        }
        var items = res.item;
        var latlons = [];
        for (var i=0, j=items.length; i<j; i++) {

            var itemlatlon = new ZDC.LatLon(items[i].point.lat, items[i].point.lon);

            latlons.push(itemlatlon);

            var mrk = new ZDC.Marker(itemlatlon);
            map.addWidget(mrk);
            arrmrk.push(mrk);
            ZDC.bind(mrk, ZDC.MARKER_CLICK, items[i], markerClick);
        }
        var adjust = map.getAdjustZoom(latlons);
        map.moveLatLon(adjust.latlon);
        map.setZoom(adjust.zoom);
    }

    function markerClick() {
        var labelhtml;
        labelhtml = '<div><font size = "-1"><div><b>' + this.text + '</b></div>';
        labelhtml += '<table><tr><td>' + this.kana +
                     ' ' +
                     '</td></tr><tr><td>\u3012' + this.zipcode + '</td></tr></table></font></div>';

        msg.setHtml(labelhtml);
        msg.moveLatLon(new ZDC.LatLon(this.point.lat, this.point.lon));
        msg.open();
    }

    function markerDelete(){
        while(arrmrk.length > 0){
            map.removeWidget(arrmrk.shift());
        }
        msg.close();
    }

</script>
</head>

<body onload="loadMap();">
    <div id="ZMap" style="border:1px solid #777777; width:93%; height:500px; top:50px; left:20px; position:absolute;"></div>
    <div id="IBox" style="top:10px; left:20px; position:absolute;">
        <input type="text" value="東京都千代田区丸の内" id="word">
        <input type="button" value="検索実行" onclick="searchClick();">
        <input type="button" value="結果削除" onclick="markerDelete();">
    </div>
</body>
</html>