マイブックマーク全文検索API

(はてな)

【まいぶっくまーくぜんぶんけんさく】

このページは古い情報を掲載しています

このページの情報は更新されていません。新しい情報は「マイブックマーク全文検索API - Hatena Developer Center」に移転しました。

本ドキュメントに関する注意事項

本ドキュメントははてなブックマークにおけるAPI実装を解説するものです。主にはてなスタッフがその作成と更新を行っています。

変更履歴

2009年07月21日リリース
2009年07月21日 JSONP仕様変更
2009年08月07日ステータスコード仕様変更
2009年08月27日ソート機能追加

マイブックマーク全文検索APIとは

任意のクエリーを送信すると、対象のユーザーがブックマークしたエントリーに対して全文検索した結果を返すAPIです。全文検索の対象は、ブックマークされたエントリーのタイトル、本文、URL、コメント(タグを含む)です。この機能ははてなブックマークプラスをご利用時に限りお使いいただけます。

WSSE認証クッキー認証

全文検索APIの認証にはWSSE認証および、Cookie認証が利用されます。マイブックマーク全文検索APIの利用にはいずれかの認証が必須です。WSSE認証の詳細に関しては、はてなフォトライフAtomAPIのWSSEの項 (http://d.hatena.ne.jp/keyword/%a4%cf%a4%c6%a4%ca%a5%d5%a5%a9%a5%c8%a5%e9%a5%a4%a5%d5AtomAPI?kid=88110#wsse) を参照してください。
Cookie認証は通常のはてなブックマークでの認証を利用するもので、はてなブックマークにログインした状態で、はてなブックマーク全文検索APIにアクセスした場合利用されます。ブラウザによる直接のアクセスの他、 Greasemonkey などのユーザースクリプトからのアクセス時に利用できます。

API仕様の解説

http://b.hatena.ne.jp/ユーザーid/search/json
に対し以下のクエリーパラメータを GET リクエストで送信することにより、JSON 形式でデータを取得することができます。

q: 検索したい文字列 (utf8エンコードされた文字列)
of: 検索結果のオフセット ( 省略した場合 0 )
limit: 検索結果の上限 ( 省略した場合 20, 最大 100 )
sort: 検索結果のソート種類 ( date(日付順),users(ユーザー数順),scores(スコア順)，省略した場合 date)

例:) http://b.hatena.ne.jp/r_kurain/search/json?q=hatena&sort=users
また
http://b.hatena.ne.jp/ユーザーid/search/json
に対し、以下のクエリーパラメータを GET リクエストで送信することで、JSONP によるコールバック関数で囲まれたJSONデータを取得することができます。

q: 検索したい文字列 (utf8エンコードされた文字列)
of: 検索結果のオフセット(省略した場合0)
limit: 検索結果の上限(省略した場合20, 最大100)
sort: 検索結果のソート種類 ( date(日付順),users(ユーザー数順),scores(スコア順)，省略した場合 date)
callback: コールバック関数名。コールバック関数名は /^\$?[a-zA-Z0-9\[\]\.\_]+$/ (perl) の正規表現に一致する関数名でなくてはなりません。

例:) http://b.hatena.ne.jp/r_kurain/search/json?q=hatena&callback=funcname
ただし callback を指定し JSONP でデータを取得するリクエストを行った場合は、非公開に設定されたブックマークを取得することができません。

ステータスコード

リクエストに対して次のようなステータスコードを返します

200: リクエストに対して正しく応答している場合。検索結果が0件の時も200を返します。
400: コールバック関数名が不正な値だった場合。コールバック関数名を見直してください。
504: サーバ内部の検索処理がタイムアウトした場合。少し時間をおいてから再度お試しください。

JSON データの構造

JSON データの構造は以下のようになっています。またJSON データはutf-8でエンコードされた文字列です。

bookmarks

検索に結果に含まれるブックマークの配列 bookmarks の配列の構造は以下のようになっております。

entry

ブックマークしているエントリーのデータ

title: タイトル
count: ブックマークしている合計ユーザ数
url: ブックマークされているURL
eid: エントリーID
snippet: エントリー本文からの抜粋

timestamp

ブックマークした時刻をエポック秒で表した数。 new Date(timestamp * 1000) で JavaScript の Date オブジェクトになります

comment

ブックマークコメント

is_private

非公開のブックマークのフラグ。ブックマークが個別に非公開に設定されている場合1をとります

meta

検索結果についての付加情報

total

検索結果に含まれるエントリーの総数

query

リクエストされた検索クエリーについてのデータ

original: リクエストされたクエリーがそのまま格納された文字列
queries: リクエストされたクエリーを分割した結果を格納した配列。(クエリーに空白が含まれる場合、空白で分割されAND検索されます)

status

ステータスコード。正常時は200、不正なリクエストを受けるなど正常に結果を返せなかった場合403

elapsed

検索を行うのに必要とした時間。単位は秒

サンプルプログラム

任意のユーザーのブックマークに対して全文検索を行うperlのサンプルスクリプトは以下のようになります。ここではWSSE認証に、CPANモジュールの LWP::Authen::Wsse を利用しています。LWP::Authen::Wsse を利用しない場合の実装方法については、はてなフォトライフAtomAPIのWSSEの項 (http://d.hatena.ne.jp/keyword/%a4%cf%a4%c6%a4%ca%a5%d5%a5%a9%a5%c8%a5%e9%a5%a4%a5%d5AtomAPI?kid=88110#wsse) を参照してください。

use strict;
use warnings;

use LWP::UserAgent;
use JSON::XS;

my $query = 'QUERY';

my $username = 'YOUR_USER_NAME';
my $password = 'YOUR_PASS_WORD';

my $ua = LWP::UserAgent->new;
$ua->credentials( 'b.hatena.ne.jp:80', '', $username, $password );

my $res = $ua->get("http://b.hatena.ne.jp/$username/search/json?q=$query");
die $res->status_line if $res->is_error;

my $json = decode_json $res->content;
for my $bookmark ( @{ $json->{bookmarks} } ) {
    print $bookmark->{entry}->{title} . "\n";
    print $bookmark->{entry}->{url}  . "\n\n";
}