Twitter 検索API メモ

twitter api

【2010-02-28 追記】
いつの間にやら結構な数のブックマークをして頂いて、
情報が古いままでは心苦しいので、１年ぶりくらいになってしまいましたが、情報を更新しました。
思ったほど変更はなかったのでよかったです。


〜〜 ここから元々の本文 〜〜

http://apiwiki.twitter.com/Twitter-API-Documentation の「Search API Methods」について のメモですが、
英語がかなり苦手なので、間違ってるとこもあるかもしれません。
あと、大してtwitterを使ってなかったりするので、
twitterの機能面でよくわかってない部分もあります。


検索API : http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-search

出力形式
AtomとJSONに対応。リクエストURLはそれぞれ以下（メソッドはGETで、認証は必要無し）。

  • http://search.twitter.com/search.atom?q=
  • http://search.twitter.com/search.json?q=

(※) JSONの場合は、「callback」パラメータをつけることでJSONPになる
ex. http://search.twitter.com/search.json?callback=foo&q=twitter

      • -

リクエストパラメータ

  • q：検索クエリ

(※) 「"」や「#」、「)」、「(」などはURLエンコードの必要あり
まずは、一般的な検索エンジンと同様に、以下の検索が可能

特別なオペレータもいくつか存在する

    • until:
      • 指定した日時までに投稿されたtweetsから検索
      • ex. http://search.twitter.com/search.atom?q=ftw+until:2009-03-17
      • (※) ただし、後述の「制限事項」でも記載している通り、APIで利用できるデータは4ヶ月前のものまで
      • 指定日時に未来は指定できない
      • NOT検索(-until:)はできない
      • 10日前後くらいまでしか結果が返ってこない気がする
    • source:
      • 指定したsourceを使ってpostされたtweetsから検索
      • ex. http://search.twitter.com/search.atom?q=news+source:twitterfeed
      • web、Tween、movatwitterなどなど(「from なんちゃら」ってとこ)
      • 結果は7日以内のtweetsに制限される
      • q=source:だけでは検索できない。何かしらのキーワードと一緒に検索しないといけない。
  • geocode：指定した緯度＆経度を中心として、指定半径以内にいるユーザのtweetsから検索
    • ユーザの位置情報は、Geotagging APIから取得しようとするが、できなければtwitter profileのものが使用される
    • 緯度・経度・半径の値は、カンマ区切りで指定
      • 半径の単位は、mi(マイル) か km(キロメートル) で指定する
    • ex. http://search.twitter.com/search.atom?geocode=40.757929,-73.985506,25km
    • APIでは、qパラメータのnearオペレータが使えない代わりに、このパラメータで直接位置を指定できる
    • OR検索はサポートしない
    • 結果は7日以内のtweetsに制限される？*2
  • locale：
    • 送信するクエリの言語を指定できる（現在は ja のみ有効）
    • これは言語特有のクライアントのための機能で、大体はデフォルトで(指定しなくて)問題ない


(※) 制限事項（注意点）

  • 約4ヶ月以内のデータのみ利用可能　これに関する記述が2010-02-28時点では見つけることができませんでした。現在、どの程度以前までのデータが使えるのか不明です。
  • nearオペレータは使えないので、geocodeパラメータに置き換える必要がある
  • クエリの長さは140文字まで
  • クエリはURLエンコードすべきである
  • 検索結果に反映されないユーザがいるかもしれない
  • The since_id parameter will be removed from the next_page element as it is not supported for pagination. If since_id is removed a warning will be added to alert you.*3
  • since_idが古い場合は404エラーを返す
  • もし、クエリの生成で悩むことがあれば、advanced search formを参考にするとよい
  • uniqueで意味のあるUserAgentを使用すべき
    • UserAgentを含まないトラフィックは、１時間にAPIを呼べる回数がUserAgentを含んでいるものより少なく制限される
  • リファラはあった方がよいが、必須ではない
  • Warning:「検索APIのユーザID」と「REST APIのユーザID」は一致しない。状況は、Issue214 で確認できる。一致させるには、IDではなく、表示名を使って一致させる必要がある


Guidelines

  1. user agent をセットしてください
  2. 新しいtweetsからの検索には、可能ならsince_idをつかってください
  3. できたら、"Powered by Twitter"のバナーを張ってください
  4. 通常は検索APIの回数制限はしてないけど、悪用(乱用)に対しては措置を取ります。もしあなたが措置を受けたことがわかったら、あなたの要求（使用回数）を記述して我々にご連絡ください
  5. 何か作って公開したなら、チェックできるように連絡してください

trends : http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends

  • http://search.twitter.com/trends.json
  • 現在twitter上で人気のある10トピックを返す
  • メソッドはGET, 認証は無し
  • 出力形式はJSONのみ（callbackパラメータは利用可能）
  • 結果は、以下が含まれる
    • as_of: リクエスト日時（ex. "Wed, 25 Mar 2009 09:10:08 +0000"）
    • trends:
      • name: 人気トピックの名前
      • url: そのトピックのTwitter検索結果ページへのURL

trends/current : http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends-current

trends/daily : http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends-daily

trends/weekly : http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-trends-weekly

*1:この例だと、単語dougwを、dougwのtweets以外から検索

*2:「location operator」の結果が7日以内のtweetsに制限されると書いてありますが、その「location operator」が、このgeocodeパラメータを含んでいるかどうかを確認できませんでしたorz

*3:意味がわかりませんでしたので原文をorz