twitter4jからtwitterの検索APIを利用する

概要

　今回はtwitter4jを利用して、検索結果の取得を行う。
　まず初めに、検索APIで利用できるオプションについて列挙した。続いて、twitter4jからそれらオプションを利用して検索結果の取得を行った。

検索(search) APIのオプション

　twitterの検索APIでは、必須となる検索クエリ（文字列）に加えて、以下のオプションが利用可能である*1。

option項目	概要
callback	JSON形式で取得する時専用。渡したcallback関数名のJSONP化する……らしい。twitter4jを利用する場合は不要
lang	取得するツイートの言語を絞り込む。指定には ISO 639-1 code*2を利用する
locale	クエリの言語を指定する。現在はjaのみが有効
rpp	return per page. 位置頁にいくつのツイートを返すかを指定する。最大は100
page	何ページ目のツイートを取得するか
since_id	ツイートを取得する範囲の開始id
max_id	ツイートを取得する範囲の終了id
since	ツイートを取得する範囲の開始日付。"YYYY-MM-DD"のフォーマットで指定する
until	ツイートを取得する範囲の終了日付。"YYYY-MM-DD"のフォーマットで指定する
geocode	ツイートを取得する半径とその中心の緯度経度。"緯度,経度,半径（"mi" or "km")"のフォーマットで指定する
show_user	ツイートにユーザ名を含める。デフォルトはfalse
result_type	mixed, recent, popularの３つから結果を選択する。デフォルトはmixed

　尚、最新の公式ドキュメントでは、max_id及びsinceの存在が確認できない。一方で、twitter API wikiによれば、これらのオプションも存在している*3。どうやら、現在もこの二つのオプションは利用できるようだが、どういう事なのか気になる所だ。

検索APIの利用

　twitter4jから検索APIを利用する場合には、Query クラスと Twitterクラスのsearch(Query) メソッドを利用する*4。検索結果はQueryResultクラスで受け取ることになる。例えば、オプションを指定しない場合には、以下の様にすれば良い。

Twitter twitter = new TwitterFactory().getInstance();
Query query = new Query("hoge");
QueryResult result = twitter.search(query);

　オプションの指定は、全てQueryクラスを通して行う。Queryクラスには、上に挙げたcallbackとshow_userを除いた、全てのオプションに対応するメソッドが存在している。

option項目	対応するメソッド
lang	setLang(java.lang.String lang)
local	setLocale(java.lang.String locale)
rpp	setRpp(int rpp)
page	setPage(int page)
since_id	setSinceId(long sinceId)
until	setUntil(java.lang.String until)
geocode	setGeoCode(GeoLocation location, double radius, java.lang.String unit)
result_type	setResultType(java.lang.String resultType)

　例えば、2009/10/25から2010/10/25までのツイートから"test"という文字列を含むツイート検索し、それを新着順にして一ページに50件表示する場合、次の様に書く。

Query query = new Query("test");
query.since("2009-10-25");
query.until("2010-10-25");
query.setResultType(query.RECENT);
query.setRpp(50);
QueryResult result = twitter.search(query);

検索結果の利用

　検索結果からツイートを取り出すには、QueryResult.getTweets()メソッドを利用する。タイムラインの取得時にはStatusクラス（正確にはインターフェースだが）のListとして受け取った。これに対して、検索結果の取得は、Tweetクラス（やはり正確にはインターフェース）*5のListとして受け取る。
　TweetはStatusと比べていくつかの情報が減っており、ユーザ名やその発言内容など基本的な情報しか得られない。
　検索結果から投稿日時、投稿者、投稿内容を得る場合には、以下の様に書く。

List<Tweet> twitterSerches = result.getTweets();
for (Tweet tweet : twitterSerches) {
    out.println(tweet.getCreatedAt().toString() + ":" + tweet.getFromUser() + ":" + tweet.getText());
}