はてなブックマーク件数取得API

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

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

変更履歴

• 2009年08月11日 GETリクエストのシンプルなAPIを追加
• 2006年10月4日 被ブックマーク合計数取得APIを追加
• 2005年12月20日 被コレクション件数取得APIを追加
• 2005年12月12日 リリース

GET リクエストでのシンプルな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 をご利用ください。

XMLRPC API仕様の解説

任意の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

先に解説した被ブックマーク数取得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/ 全体での被ブックマーク件数が出力されます。

被コレクション件数の取得API

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を利用されるにあたっては、以下の点にご注意ください。

• 本APIは実験的に公開されているものであり、API の仕様変更ならびに API の公開停止を予告なしに行う場合があります。
• 本APIへのリクエストに際して、1クライアントあたりの上限回数はいまのところありません。ただし、過度なリクエストはサーバーの過負荷ならびにサービスのレスポンス低下に繋がりますので、繰り返しリクエストされる場合は、リクエスト毎に数秒の間隔をあけていただくなど、サーバーリソースの節約にご協力ください。

参照

• http://d.hatena.ne.jp/keyword/%a4%cf%a4%c6%a4%ca%a5%d6%a5%c3%a5%af%a5%de%a1%bc%a5%afAtomAPI
• http://d.hatena.ne.jp/keyword/%a4%cf%a4%c6%a4%ca%a5%d6%a5%c3%a5%af%a5%de%a1%bc%a5%af%a5%d5%a5%a3%a1%bc%a5%c9%bb%c5%cd%cd
• はてなウェブサービス