第19回　使ってみよう！ Bing API──jQuery編（1）

はじめに

これまでの連載では地図サービスのBing Maps関連のAPI/SDKを紹介してきましたが、今回はWebサイトの検索を可能にするBing APIを使ってみましょう。連載では網羅的にAPIを紹介するのではなく、JavaScriptのライブラリーのjQueryを使用して、APIの利用サンプルを紹介します。なお、jQueryについての説明は行いません。

Bing APIを利用すると、検索サービスのBingと同質の検索結果を得ることができます。ただし、Bingは日々新たな機能が追加され、多様なサービスと連携しているため、APIの利用だけでは同等のものは作成できません。また、APIのアップデートは残念ながら長い間更新されていません。そのため、現在のBingサービスと機能が一致していない部分もあります。一方、リクエスト数に上限がない[1]など特長がありますので、アプリケーション開発にうまく活用してみてください。

今回の内容は、「⁠使ってみよう！ Windows Live SDK/API」の第25回で紹介しているLive Search API 2.0とも関連しています。Live Search APIは、Bingがリリースされる前に提供されていたAPIで、その内容は現在のBing APIとほぼ変わりありません。現在でも参考になると思いますので、より詳しく知りたい方は、こちらの記事とMSDN Libraryを参照してください。

Bing API

Bing APIでは、JSONとXML形式、およびSOAPでの3種類の呼び出し方法が用意されています。今回はJavaScriptから利用が便利なJSON形式のデータを使用します。

APIによる情報の取得は、Webサイトの検索結果だけでなく、

モバイル向けのWebサイトの検索
画像の検索
動画の検索

なども可能です。

また、検索結果を改善や効果的にするために

キーワードの修正候補や
関連キーワード

の取得もできます。

これら以外にも、ニュースやインスタントアンサーと呼ばれる百科事典などからの情報の検索、位置情報から電話帳検索、機械翻訳といった機能もBing APIで利用できます。ただし、日本・日本語では利用できなかったり、最新のBingサービスとAPIで提供されている機能に差異があったりします。

Application IDの作成

Bing APIを利用するにあたり、Application ID（AppID）を作成する必要があります。AppIDはAPI呼出し時に使用します。あらかじめ作成しておきましょう。これまでの連載で使用してきたBing Maps Keyとは異なりますので注意してください。

AppID作成は、Bing Developer Center（図1）にアクセスし、APIを利用するアプリケーションを登録することで行います。

必要な項目を入力し、利用規約を確認後、［⁠Agree］ボタンをクリックし、AppIDを得られます。IDは16進数の文字列です。

Webサイトの検索

それでは、実際にAPIを呼び出してみましょう。APIの利用は非常に簡単です。JSON形式で検索結果を得る場合、次のようなURLにアクセスするだけです。

http://api.bing.net/json.aspx?
  AppId=AppId&
  Version=2.2&
  Market=ja-JP&
  Query=Windows&
  Sources=Web&
  Web.Count=2&
  Web.Offset=0

各パラメーターは次の通りです。

名前	説明
AppID	AppID（必須）
Version	APIのバージョン（現在は2.2）
Market	言語・地域の指定（en-USなど）
Query	検索クエリー（必須）
Sources	検索対象（必須） Web, Image, Video, RelatedSearch, Spellなど
Web.Count	取得する件数（Webの場合、最大50）
Web.Offset	取得する位置（10の場合、結果の11番目から取得。最大1000）

このほかにもパラメーターはいくつか用意されていますが、とりあえず今はこれだけでよいでしょう。

URLにアクセスすると次のようなJSON形式の結果が得られます。簡単ですね。内容は直感でわかるのではないかと思います。ちなみにURL内のjson.aspxをxml.aspxに変更するとXML形式で結果が得られます。

{
    "SearchResponse": {
        "Query": {
            "SearchTerms": "windows"
        }, 
        "Version": "2.2", 
        "Web": {
            "Offset": 0, 
            "Results": [
                {
                    "CacheUrl": "http://cc.bingj.com/cache.aspx?q=windows&d=1&mkt=ja-JP&w=1", 
                    "Description": "Windows 製品とテクノロジの公式ホーム ページです。 (略)", 
                    "DisplayUrl": "www.microsoft.com/japan/windows/default.mspx", 
                    "Title": "Microsoft Windows ホーム ページ", 
                    "Url": "http://www.microsoft.com/japan/windows/default.mspx"
                }, 
                {
                    "CacheUrl": "http://cc.bingj.com/cache.aspx?q=windows&d=5044954658701345&mkt=ja-JP&w=69e7b6a,49d6665a", 
                    "DateTime": "2011-03-05T08:36:00Z", 
                    "Description": "Windows 製品公式ホーム ページです。 (略)", 
                    "DisplayUrl": "www.microsoft.com/japan/windows/default.asp", 
                    "Title": "Windows ホーム: Windows 製品情報、機能比較 ...", 
                    "Url": "http://www.microsoft.com/japan/windows/default.aspx"
                }
            ], 
            "Total": 414000000
        }
    }
}

SourcesにWebを指定した場合、SearchResponse.Web.Results配列から各Webサイトの情報が得られます。

パラメーターに誤りなどがあり、エラーが発生した場合は、次のような結果を得ます。

{
    "SearchResponse": {
        "Errors": [
            {
                "Code": 1002, 
                "HelpUrl": "http://msdn.microsoft.com/en-us/library/dd251042.aspx", 
                "Message": "Parameter has invalid value.", 
                "Parameter": "SearchRequest.Web.Count", 
                "Value": "100"
            }
        ], 
        "Query": {
            "SearchTerms": "windows"
        }, 
        "Version": "2.2"
    }
}

コードの記述

次は、jQueryを使用してAPIを呼び出すようにしてみましょう。ここではHTML・CSS・JavaScriptを記述するファイルをそれぞれ用意してWebアプリケーションを作成します。最初に次のファイルを用意してください。

HTMLファイル

<!DOCTYPE html>
<html lang="ja">
    <head>
        <meta charset="utf-8" />
        <title>Bing API Sample</title>
        <link rel="stylesheet" href="default.css" type="text/css" />
        <!-- jQuery ライブラリーの参照 -->
        <script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-1.5.1.js" type="text/javascript"></script>
        <!-- Bing API を利用する JavaScript ファイルの参照 -->
        <script src="./web.js" type="text/javascript" charset="utf-8"></script>
    </head>
    <body>
        <!-- 検索ボックス -->
        <div id="box"><input type="text" id="query" /><input type="submit" id="search" value="" /></div>
        <div style="clear: left;">
            <!-- ここに検索の件数を表示する -->
            <div id="summary"></div>
            <!-- ここに検索結果のWebサイト情報を表示する -->
            <ul id="list"></ul>
        </div>
    </body>
</html>

CSSファイル（default.css）

body, input {
    font-family: Meiryo;
}            
#box {
    border: 1px solid #acbabd;
    float: left;
    height: 24px;
    padding: 2px;
}
#query {
    border-width: 0;
    float: left;
    font-size: medium;
    outline-style: none;
    width: 175px;
    height: 22px;
}
#search {
    background-image: url("http://www.bing.com/siteowner/s/siteowner/Spyglass_24x24.gif");
    border-width: 0;
    cursor: pointer;
    float: left;
    height: 24px;
    width: 24px;
}
#summary {
    padding-top: 1em;
    color: Gray;
}
#list {
    padding: 1em;
}
li {
    padding-bottom: 0.5em;
}
.desc {
    font-size: small;
}
.dispUrl {
    font-size: small;
    color: Green;
}
.crawlDate {
    font-size: small;
    color: Gray;
}
.cache {
    font-size: small;
}

JavaScriptファイル（web.js）

$(function () {

    // AppId
    var appId = "AppID";

    // 特殊文字を置換する関数
    var esc = function (str) {
        if (!str) {
            return "";   
        } else {
            return str.replace(/&/g, "&amp;").replace(/\</g, "&lt;").replace(/\>/g, "&gt;");
        }
    }

    // (ここにコードを追記します)

});

コード中のAppIDは、取得した実際のAppIDの値に置き換えてください。以上で準備ができました。

Bing APIの呼び出し

JavaScriptファイルにコードを追記していきましょう。検索ボックスのボタンをクリックしたときのAPIを呼び出す処理を追加します。コードは次のようになります。

$("#search").click(function() {
    var q = $("#query").val();
    if (!q) {
        // クエリーの入力がない場合は Bing へ移動
        location.href = "http://www.bing.com/"
        return;   
    }
    
    // Bing API の非同期呼び出し
    $.ajax({
        type: "GET",
        url: "http://api.bing.net/json.aspx",
        dataType: "jsonp",
        jsonp: "JsonCallback",
        data: { // Bing API のパラメーター
            AppId: appId,
            Version: "2.2",
            Market: "ja-JP",
            Query: q,
            Sources: "Web",
            "Web.Count": 10,
            "Web.Offset": 0,
            JsonType: "callback" // ← JSONP 形式の結果を指定
        },
        success: function (data) {
            // 非同期呼出しが成功した場合
            searchCallback(data);
        },
        error: function (jqXHR, textStatus, errorThrown) {
            // 非同期呼出しに失敗した場合
            alert(errorThrown);
        }
    });
    
});

ここでのポイントは、先ほど示したBing APIを呼び出すURLのパラメーターではJSON形式のデータが返ってきますが、より簡単にJavaScriptから利用するため、コールバック関数を用いるJSONPと呼ばれる方法を使用していることです。上記コードではURLに次のふたつのパラメーターを追加した呼出しを行っています。

名前	説明
JsonType	レスポンスの種類以下の3種類から指定 raw：JSON形式（規定値） function：関数呼び出しの記述を付加 callback：コールバック関数呼び出しの記述を付加
JsonCallback	JsonTypeがcallbackの場合、コールバック関数名を指定

JsonTypeパラメーターにcallbackを指定した場合、APIの戻り値は次のようにJavaScriptのコードが付加されています。userCallbackは、JsonCallbackパラメーターに指定した名前です。

if(typeof userCallback == 'function') 
        userCallback({"SearchResponse":{/*(省略)*/}});

レスポンスの表示

最後に、APIの呼び出しに成功時の処理を行っているsearchCallback関数を追記しましょう。先ほどのAPI呼出しのコードより前に追記してください。

var searchCallback = function (response) {
    // 結果がエラーの場合
    if (response && 
        response.SearchResponse && 
        response.SearchResponse.Errors) {

        $.each(response.SearchResponse.Errors, function () {
            alert("Code: " + this.Code + "\n" +
                  "Message: " + this.Message + "\n" +
                  "Parameter: " + this.Parameter + "\n" +
                  "Value: " + this.Value);
        });
        return false;
    }

    var list = $("#list");        
    list.empty();

    var summary = $("#summary");
    summary.empty();

    if (response &&
        response.SearchResponse &&
        response.SearchResponse.Web &&
        response.SearchResponse.Web.Results) {
    
        // 結果の一覧表示
        $.each(response.SearchResponse.Web.Results, function () {
            list.append('<li><a href="' + this.Url + '">' + esc(this.Title) + '</a><br />' +
                        '<span class="desc">' + esc(this.Description) + '</span><br />' + 
                        '<span class="dispUrl">' + esc(this.DisplayUrl) + '</span> ' + 
                        '<span class="crawlDate">' + ((this.DateTime) ? new Date(this.DateTime) : "") + '</span> ' +
                        '<span class="cache"><a href="' + this.CacheUrl + '">キャッシュ</a></span>' + '</li>');
        });

        // 件数の表示
        var offset = response.SearchResponse.Web.Offset;
        summary.html((offset + 1) + "-" + (offset + response.SearchResponse.Web.Results.length) + " 件 " +
                    "(" +  response.SearchResponse.Web.Total + "件中) の検索結果");
        
    } else {
        list.append("<li>No results</li>");
    }

}

パラメーター不正などのBing APIのエラーの場合は、その内容を表示し、正しく検索結果が得られている場合は、検索件数および、各Webサイトの情報を一覧表示するよう処理しています。

以上の実行結果は図2のようになります。正しく動作したでしょうか。

Webサイトの検索に限っては、結果の順番を入れ替えての表示を許されています。Webサイトの結果に含まれている更新日時（またはクロールした日時）順で表示などを行うアプリケーションも作成できます。取得した結果はすべて表示するなど制限もありますので注意してください。

今回はここまでです。導入部分しか紹介できていませんので、次回もBing APIと、最新の情報があればそれも含めて、お届けする予定です。