本ドキュメントははてなブックマークにおける件数取得のAPI実装を解説するものです。
GET リクエストでのシンプルな件数取得 API です。
http://api.b.st-hatena.com/entry.count?url=http%3A%2F%2Fwww.hatena.ne.jp%2F
のように http://api.b.st-hatena.com/entry.count の API エンドポイントにクエリパラメータ url を付与し GET リクエストを送ることで、簡単にカウント数を取得することができます。
また、callback クエリパラメータを付与することで、JSONP でカウント件数を取得することも可能です。
http://api.b.st-hatena.com/entry.count?url=http%3A%2F%2Fwww.hatena.ne.jp%2F&callback=MyCallbackFunction
なお、API のエンドポイントのドメインは api.b.st-hatena.com となっていますが、現時点(2009年08月11日)では b.hatena.ne.jp ドメインでもアクセス可能ですが、将来的にはこの GET リクエストのAPIではb.hatena.ne.jp ドメインでは使えなくなる可能性がありますので、api.b.st-hatena.com をご利用ください。
GET リクエストでのシンプルな件数取得 API の、複数 URL 対応版です。
http://api.b.st-hatena.com/entry.counts?url=http%3A%2F%2Fwww.hatena.ne.jp%2F&url=http%3A%2F%2Fb.hatena.ne.jp%2F
のように http://api.b.st-hatena.com/entry.counts の API エンドポイントにクエリパラメータ url を複数付与し GET リクエストを送ることで、複数の URL に対するブックマーク数を一度に取得できます。応答は URL をキー、ブックマーク数を値とした JSON 形式となります。
{"http://www.hatena.ne.jp/":5790,"http://b.hatena.ne.jp/":6793}
一度に指定できる url の数は 50 までです。これを越えると 414 Request-URI Too Large が返却されます。
1 URL に対する API の場合と同様に、callback パラメータを指定することで、JSONP も利用できます。
http://api.b.st-hatena.com/entry.counts?url=http%3A%2F%2Fwww.hatena.ne.jp%2F&url=http%3A%2F%2Fb.hatena.ne.jp%2F&callback=MyCallbackFunction
任意のURLのリストを送信すると、はてなブックマークでの被ブックマーク件数を取得することができるAPIです。APIはXML-RPC APIを用いて実装を行っており、結果は URL と被ブックマーク件数のペアの構造体として返却されます。
メソッド名および指定可能な各属性は、以下の通りです。
- uri
- http://b.hatena.ne.jp/xmlrpc
- methodName
- bookmark.getCount
- parameters
- 件数を取得したいURLを指定(複数指定可能/50件まで)
このAPIを用いてやり取りを行った場合のサンプルは以下のようになります。
<?xml version="1.0" encoding="UTF-8"?> <methodCall> <methodName>bookmark.getCount</methodName> <params> <param><value><string>http://d.hatena.ne.jp/</string></value></param> <param><value><string>http://b.hatena.ne.jp/</string></value></param> <param><value><string>http://www.hatena.ne.jp/</string></value></param> </params> </methodCall>
<?xml version="1.0" encoding="us-ascii"?> <methodResponse> <params> <param> <value> <struct> <member> <name>http://www.hatena.ne.jp/</name> <value><int>157</int></value> </member> <member> <name>http://b.hatena.ne.jp/</name> <value><int>198</int></value> </member> <member> <name>http://d.hatena.ne.jp/</name> <value><int>35</int></value> </member> </struct> </value> </param> </params> </methodResponse>
複数のURLに対する被ブックマーク数を出力するPerlサンプルスクリプトは以下のようになります。ここでは XML-RPC の処理に XMLRPC::Lite モジュールを利用しています。
#!/usr/local/bin/perl use strict; use warnings; use XMLRPC::Lite; our $EndPoint = 'http://b.hatena.ne.jp/xmlrpc'; my @urls = ( 'http://d.hatena.ne.jp/', 'http://b.hatena.ne.jp/', 'http://www.hatena.ne.jp/', ); my $map = XMLRPC::Lite ->proxy($EndPoint) ->call('bookmark.getCount', @urls) ->result; printf("%d\t%s\n", $map->{$_}, $_) for @urls;
上記スクリプトをコマンドラインから実行した場合、以下の様な結果が得られます。
$ perl sample.pl 35 http://d.hatena.ne.jp/ 198 http://b.hatena.ne.jp/ 157 http://www.hatena.ne.jp/
先に解説した被ブックマーク数取得API (bookmark.getCount) は特定のページのブックマーク数を取得するためのAPIです。一方、次に紹介するAPIは「特定のページ」ではなく「特定のサイト」の合計ブックマーク数を取得するためのものです。例えば特定の日記で、その日記が全体で何件ブックマークされているかを取得したい場合などに利用することができます。(本API は 2006年10月4日に追加されました。)
メソッド名および指定可能な各属性は、以下の通りです。
- uri
- http://b.hatena.ne.jp/xmlrpc
- methodName
- bookmark.getTotalCount
- parameters
- 件数を取得したいサイトのURLを指定(複数指定不可)
このAPIを用いてやり取りを行った場合のサンプルは以下のようになります。
<?xml version="1.0"?> <methodCall> <methodName>bookmark.getTotalCount</methodName> <params> <param> <value><string>http://d.hatena.ne.jp/hatenadiary/</string></value> </param> </params> </methodCall>
<?xml version="1.0"?> <methodResponse> <params> <param> <value><int>5268</int></value> </param> </params> </methodResponse>
この API を用いて件数を取得する Perl のサンプルコードは以下のようになります。
#!/usr/local/bin/perl use strict; use warnings; use XMLRPC::Lite; my $url = shift or die "usage $0 <url>"; our $EndPoint = 'http://b.hatena.ne.jp/xmlrpc'; my $count = XMLRPC::Lite ->proxy($EndPoint) ->call('bookmark.getTotalCount', $url) ->result; print $count, "\n";
スクリプトの引数に URL を与えて実行すると、
% perl get_all_count.pl http://d.hatena.ne.jp/hatenadiary/ 5268
と http://d.hatena.ne.jp/hatenadiary/ 全体での被ブックマーク件数が出力されます。
2005年12月20日に、任意のASINコードに対する被コレクション件数を取得するAPIを追加しました。(ASINコードに関する説明はhttp://d.hatena.ne.jp/keyword/asinを参照してください。)
メソッド名および指定可能な各属性は、以下の通りです。
- uri
- http://b.hatena.ne.jp/xmlrpc
- methodName
- bookmark.getAsinCount
- parameters
- 件数を取得したいASINコードを指定(複数指定可能/50件まで)
本APIによるリクエストの応答、返却は基本的に bookmark.getCount() の場合と同様となります。
複数のASINに対する被コレクション数を出力するPerlサンプルスクリプトは以下のようになります。
#!/usr/local/bin/perl use strict; use warnings; use XMLRPC::Lite; my @asin = qw(4774124966 4886487319); my $map = XMLRPC::Lite ->proxy('http://b.hatena.ne.jp/xmlrpc') ->call('bookmark.getAsinCount', @asin) ->result; printf("%d\t%s\n", $map->{$_}, $_) for @asin;
上記スクリプトをコマンドラインから実行した場合、以下の様な結果が得られます。
$ perl sample.pl 72 4774124966 6 4886487319
本APIを利用されるにあたっては、以下の点にご注意ください。