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

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

本ドキュメントははてなブックマークにおけるマイブックマークの全文を検索するAPI実装を解説するものです。

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

任意のクエリーを送信すると、対象のユーザーがブックマークしたエントリーに対して全文検索した結果を返すAPIです。全文検索の対象は、ブックマークされたエントリーのタイトル、本文、URL、コメント(タグを含む)です。

WSSE認証 クッキー認証​

全文検索APIの認証にはOAuth認証、WSSE認証、およびCookie認証が利用されます。マイブックマーク全文検索APIの利用にはいずれかの認証が必須です。OAuth認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。WSSE認証の詳細に関しては、はてなサービスにおけるWSSE認証を参照してください。

Cookie認証 は通常のはてなブックマークでの認証を利用するもので、はてなブックマークにログインした状態で、はてなブックマーク全文検索APIにアクセスした場合利用されます。ブラウザによる直接のアクセスの他、 Greasemonkey などのユーザースクリプトからのアクセス時に利用できます。

API仕様の解説​

https://b.hatena.ne.jp/my/search/json

に対し以下のクエリーパラメータを GET リクエストで送信することにより、JSON 形式でデータを取得することができます。

q​

検索したい文字列 (utf8エンコードされた文字列)

of​

検索結果のオフセット ( 省略した場合 0 )

limit​

検索結果の上限 ( 省略した場合 20, 最大 100 )

例:) https://b.hatena.ne.jp/my/search/json?q=hatena&limit=10

ステータスコード​

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

200​

リクエストに対して正しく応答している場合。検索結果が0件の時も200を返します。

400​

コールバック関数名が不正な値だった場合。コールバック関数名を見直してください。

403​

OAuth認証またはWSSE認証を利用していて、権限が足りていない場合。もしくは認証されているユーザーとは異なるユーザーの情報をリクエストした場合。

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の項を参照してください。

use strict;
use warnings;

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

my $query = 'QUERY';

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

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

my $res = $ua->get("https://b.hatena.ne.jp/my/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";
}

注意事項​

非同期にインデクスを作成しているため、ブックマーク全文検索の結果に最新のブックマークが反映されないことがあります。ご了承ください。

参考​

はてなサービスにおけるWSSE認証

変更履歴​

• 2019年09月04日 エンドポイントを https://b.hatena.ne.jp/my/search/json に統一し、ユーザーIDを不要とした
• 2019年08月29日 エンドポイントをHTTPSに対応
• 2018年06月12日 JSONP のサポートを終了. callback, sort パラメータのサポートを終了
• 2013年12月03日 Cookie認証の際はJSONPのcallbackパラメータを併用不可とする仕様変更
• 2013年10月03日 はてなアカウントのパスワードを利用したWSSE認証が非推奨になったのに伴いサンプルコードを修正
• 2009年08月27日 ソート機能追加
• 2009年08月07日 ステータスコード仕様変更
• 2009年07月21日 JSONP仕様変更
• 2009年07月21日 リリース