サイトのトップへ戻る

Twitter 開発者 ドキュメント日本語訳

サイト内検索

検索用API

Twitter の検索用API は、Twitterの v1.1 REST APIに含まれています。 このAPIを使うと最近のツイートや人気のあるツイートの一覧を検索できるようになり、 Twitter.com searchと同様な動作ができます。, but not exactly like the Search feature available in Twitter mobile or web clients

使用する前に、この検索用APIは関連性のあるものを重視しており、完全一致するものを重視しているわけではないことを知っておいてください。 ツイートやユーザーによっては検索結果から漏れてしまうこともあります。完全に一致する内容を取得したいのであれば、このAPIではなくストリーミングAPI の使用を検討してください。

このAPI エンドポイントの詳細なリファレンスについては、 GET search/tweetsで見ることができます。



クエリーの作り方

クエリを作成し、そのクエリが有効な書式か、合致したツイートを取得できているかをテストするには、 まずはtwitter.com/searchを試してみるのがベストな方法です。 満足する結果が出力されたら、ブラウザに読み込まれたURLには、API エンドポイントで再利用できる適切なクエリ構文が含まれています。以下がその例です:

  1. @twitterapi アカウントを参照しているツイートを検索したい。まず、twitter.com/searchで検索を実行します。
  2. 読み込まれたURLを確認してコピーします。今回はこのようなURLが読み込まれました: https://twitter.com/search?q=%40twitterapi
  3. “https://twitter.com/search” の部分を“https://api.twitter.com/1.1/search/tweets.json” に置き換えます。すると、このようになります: https://api.twitter.com/1.1/search/tweets.json?q=%40twitterapi
  4. このURLを実行してAPIでの検索を実施します

今の API v1.1 ではリクエストには認証が必須となっているので注意してください。認証方法の詳細な情報については Authentication & Authorizationのドキュメントを確認してください。また、twitter.comの検索結果では過去のツイートも取得できる一方、検索APIは通常ここ一週間のツイートのみ提供しているので注意してください。



クエリ演算子

クエリには検索結果を絞るための演算子があり、使用できる演算子は以下の通りです:

演算子 検索するツイート…
watching now “watching” と “now”の両方を含んだツイート。これは既定の演算子です。
“happy hour” “happy hour”のフレーズを正確に含んだツイート。
love OR hate “love”か “hate” (もしくは両方)を含んだツイート。
beer -root “beer” を含むが “root” は含まないツイート。
#haiku ハッシュタグ “haiku” を含むツイート
from:alexiskold “alexiskold”さんから送られたツイート
to:techcrunch “techcrunch”さんへ送られたツイート
@mashable “mashable”さんを参照しているツイート
superhero since:2010-12-27 “superhero” を含み、 “2010-12-27” (年-月-日)以降に送られたツイート。
ftw until:2010-12-27 “ftw” を含み、“2010-12-27”以前に送られたツイート
movie -scary :) “movie”を含むが、 “scary”を含まない、ポジティブ属性のツイート。
flight :( “flight” を含むネガティブ属性のツイート。
traffic ? “traffic” を含む質問をしているツイート。
hilarious filter:links “hilarious” を含むURLへリンクしているツイート。
news source:twitterfeed “news” を含み、TwitterFeedを使って入力しているツイート

クエリを作成する前に、 URL がこうしたクエリにエンコードされているか確認してください。 エンコードを支援するためのツールも色々ありますし、twitter.com/searchで検索してブラウザのアドレスバーからエンコードされたURLをコピーすることもできます。 以下のテーブルは、検索クエリからURLエンコードクエリへの変換例です。:

検索クエリ URL エンコードクエリ
#haiku #poetry %23haiku+%23poetry
“happy hour” :) %22happy%20hour%22%20%3A%29

スペース文字は “%20”や“+”記号で表すことができるので注意してください。



追加パラメータ

検索結果をより詳細に制御するための追加パラメータ一式があります。 パラメータの使い方の詳細情報ついては GET search/tweetsのドキュメントを参照してください。 ここではこれらの機能の簡単な説明のみを行います。:

  • Result Type: ちょうど twitter.com/search の検索結果のように、result_type パラメータで検索結果を最新のものにするか人気のあるものにするか、その両方にするかを選択することができます。
  • Geolocalization:このAPIでは検索演算子 “near” を使うことができませんが、 “緯度,経度,半径”の形式で指定されたgeocodeパラメータを使って位置情報を渡し、クエリをより正確に絞り込むことができます。例えば、 “37.781157,-122.398720,1mi”のような形式で位置情報を指定します。 地理検索を実施する場合、検索用APIではまず指定された位置情報を含むツイートを探し、見つからなかった場合は指定した位置情報をプロフィールに持つユーザーのツイートを探します。 つまり、指定した経度/緯度情報を含まないツイートを取得する可能性もあるのです。
  • Language: lang パラメータは取得するツイートを指定した言語に制限します。
  • Iterating in a result set: ツイートは膨大な数が存在するので、count, until, since_id, max_idのようなパラメータを使って検索結果をどれくらい表示するか制御することができます。 タイムラインを処理する のドキュメントでは、 これらのパラメータを使って検索結果を効率良く信頼性のある内容にまとめる方法を、豊富な内容にイラストを交えて学ぶことができます。


レート制限

GET search/tweets は Twitter REST API 1.1 に含まれており、 他のv1.1メソッドと同様にレート制限がされています。このモデルの詳細情報については REST API 速度制限 v1.1を参照してください。今の段階では、アクセストークンによって識別されるユーザーは15分ごとに180回のリクエスト/クエリを実行できます。 アプリケーション専用認証を使用すると、アプリケーションは15分ごとに450回のリクエスト/クエリをユーザー識別情報なしで実行できます。



ベストプラクティス

  • 全てのパラメータが正しく URL エンコードされていることを確認してください。
  • 検索する際に使うキーワードと演算子は10個までに制限します。
  • 複雑なクエリは制限されることがあります。この制限に該当した場合、検索用 APIはこのようなエラーを返します: {"error":"Sorry, your query is too complex. Please reduce complexity and try again."}.
  • 検索用API は全ツイートを完璧にインデックス化している訳ではなく、最近のツイートをインデックス化しています。 現時点では、6-9日間のツイートがインデックス化されています。


検索例

現在起こっているイベントに参加する場合、あなたはそのイベントのハッシュタグを使った最近のツイートを検索したいと思うでしょう:

  • あなたが欲しいツイート: #superbowlのハッシュタグを含む最近のツイート
  • 検索 URL: https://api.twitter.com/1.1/search/tweets.json?q=%23superbowl&result_type=recent

特定の地域で、特定の言語でつぶやかれているツイートを知りたい場合:

  • あなたが欲しいツイート:リオデジャネイロのマラカナサッカースタジアム 付近で、ポルトガル語で最近つぶやかれた全てのツイート
  • 検索 URL is: https://api.twitter.com/1.1/search/tweets.json?q=&geocode=-22.912214,-43.230182,1km&lang=pt&result_type=recent

特定の人物がハッシュタグを使ったツイートの中で、最も人気のあるものを知りたい:

  • あなたが欲しい情報:@Cmdr_Hadfield さんがハッシュタグ #nasaを使ってつぶやいている中で 人気のあるツイート
  • 検索 URL : https://api.twitter.com/1.1/search/tweets.json?q=from%3ACmdr_Hadfield%20%23nasa&result_type=popular



エンジェル戦記