Twitter Historical PowerTrack API を利用することで、これまでに蓄積された全てのツイートから、自分の指定する条件にマッチしたツイートだけを取得することができます。このページでは、Twitter Historical PowerTrackの仕組み、指定できる条件、返ってくるデータ形式について解説しています。
Twitter Historical PowerTrack API は、Twitterの法人プランを契約している開発者のみが利用できます。Twitter Historical PowerTrack APIを使ったお仕事のご依頼、ご相談については、@ts_3156 までお気軽にご連絡ください。
このページでは、Historical PowerTrack APIを紹介しています。PowerTrack APIについては PowerTrack API を使ってツイートを取得する をご参照ください。
Twitter Historical PowerTrack API とは
Twitter社が提供する、「最初のツイートまでさかのぼって、ルールにマッチしたツイートのみをフィルタリングしてダウンロードする機能」のことです。Historical PowerTrackは、リアルタイムPowerTrackと同じフィルタリング機能を使うことができます。
Historical PowerTrackは、バッチジョブ形式でのデータへのアクセスを提供しています。このバッチジョブの管理にもHistorical PowerTrack APIが利用できます。
※Twitter Historical PowerTrack APIは、Twitterの法人プランを契約している開発者のみが利用できます。
Historical PowerTrack ジョブの構成
- Historical PowerTrack APIを使用してジョブを作成します。この時、APIはサンプリングされた期間から予想されるデータ量とジョブの実行時間の概算値を生成します。
- ステップ1の推定値に基づいて、ジョブを実行するかどうかを決定します。予想されるデータ量や実行時間が予想の範囲外であった場合は、ジョブを拒否することができます。
- ジョブが完了したら、データファイルをダウンロードするためのURLのリストを取得します。
- ステップ3で取得したURLのリストを使用して、データファイルをダウンロードします。1つのファイルは10分間のセグメントを表しており、データはジョブが受理されてから15日間ダウンロードできます。
Historical PowerTrack API と Full-Archive Search API の違い
Historical PowerTrack APIと同じような機能には、Full-Archive Searchがあります。どちらを使った場合でも、2006年の最初のツイートを含む公開されている全てのツイートを取得することができます。
どちらを使ってもアクセスできるツイートは同じですが、内部の仕組みが大きく異なるため、データへアクセスする方法に違いが生じています。例えば、PowerTrackの演算子、ルール/フィルタの数、推定値の提供方法、データの配信方法が違います。
Historical PowerTrack
バッチジョブ形式で設計されており、大規模なツイートデータを取得するように構築されています。このため、ジョブごとにボリュームの推定、ジョブステータスの取得、何千ものデータファイルのダウンロードというフェーズがあります。リクエストの大きさによっては、ジョブの生成に数時間から数日かかることもあります。データファイルは10分ごとに作成されるため、30日間のデータセットは、マッチしたツイートの数に関わらず、約4,300個のファイルで構成されています。
Full-Archive Search
古典的なリクエスト/レスポンスパターンを使用して設計されており、Google検索のように、ある検索条件にマッチする結果を少しずつ取得する機能を提供しています。一度のレスポンスでは最大500件のツイートを提供することができ、ページング機能を使って、全てのデータの完全なセットを作成することになります。
取得するツイートの数が非常に大きい場合、例えば1000万ツイートを超えるような取得を行う場合は、Historical PowerTrackの方がFull-Archive Searchよりも適しています。どちらであってもアクセスできるツイートに違いはありませんが、このデータ量にアクセスするバッチ処理とページング処理では、バッチ処理の方が早くなります。
多くのユースケースでは、実際のツイートそのものよりも、クエリに関連するツイートの数が重要です。Full-Archive Searchでは、一致したツイートの数を時系列で返す「カウント」エンドポイントをサポートしています。このエンドポイントを使うと、1分ごと、1時間ごと、1日ごとの合計ツイート数を把握することができます。
Full-Archive Search APIとHistorical PowerTrack APIの両方が12ヶ月間のサブスクリプションで利用可能です。さらに、Historical PowerTrackは「一回限り」で利用可能です。そのため、1回限りのプロジェクトやその場限りのリサーチのためにツイートデータが必要な場合は、Historical PowerTrackの方が適しています。
過去の全てのツイートではなく、直近の30日間についてのみ検索すればよい場合は、30-Day Search APIの方がより適した選択肢になります。
Historical PowerTrackとFull-Archive Searchの違いについてより詳細に知るには、Choosing a historical API をご参照ください。
Historical PowerTrack APIのルールとフィルタリング
Historical PowerTrack APIでは、リアルタイムPowerTrackと同じルールを利用することができます。
- keyword
- キーワード
- emoji
- 絵文字
- "exact phrase match"
- 正確なフレーズ
- "keyword1 keyword2"~N
- 単語の近接検索。例：「赤いりんご」を検索して「赤りんご」や「赤く実ったりんご」にマッチ
- contains:
- 部分文字列
- from:
- ツイートしたユーザーの指定
- to:
- url:
- ツイートをに含まれるURL
- url_title:
- ツイートに含まれるURLのページタイトル
- url_description:
- ツイートの含まれるURLの説明文
- url_contains:
- ツイートに含まれるURLの本文
- has:links
- sample:
- point_radius:[lon lat radius]
- 位置情報を緯度経度と半径で指定
- bounding_box:[west_long south_lat east_long north_lat]
- 位置情報を矩形で指定
- @
- $
- bio:
- プロフィール
- bio_name:
- ユーザー名
- retweets_of:
- lang:
- 言語
- bio_location:
- ロケーション
- statuses_count:
- ツイート数
- followers_count:
- フォロワー数
- friends_count:
- フォロー数
- listed_count:
- リストされている数
- is:verified
- 認証済みアカウントかどうか
- source:
- place:
- 場所
- place_country:
- 国
- has:geo
- 地理情報付きかどうか
- has:mentions
- メンションされているかどうか
- has:hashtags
- ハッシュタグがあるかどうか
- has:images
- 画像が添付されているかどうか
- has:videos
- 動画が添付されているかどうか
- has:media
- メディアが添付されているかどうか
- has:symbols
- is:retweet
- リツイートかどうか
- is:reply
- リプライかどうか
- is:quote
- retweets_of_status_id:
- in_reply_to_status_id:
- has:profile_geo
- profile_point_radius:[long lat radius]
- profile_bounding_box:[west_long south_lat east_long north_lat]
- profile_country:
- プロフィールの国
- profile_region:
- プロフィールの地域
- profile_locality:
- profile_subregion:
Historical PowerTrackのデータフォーマット
実行が完了したジョブのデータファイルは、gzip圧縮されたJSONファイル形式になっています。各ファイルはクエリで指定した10分間ごとのツイートを含んでいます。ツイートデータの詳細については Tweet objects をご参照ください。
Twitter Historical PowerTrack API を使った仕事のご依頼について
Twitter Historical PowerTrack API は、Twitterの法人プランを契約している開発者のみが利用できます。Twitter Historical PowerTrack APIを使ったお仕事のご依頼、ご相談については、@ts_3156 までお気軽にご連絡ください。
具体的に何をするのかが決まっていない場合であっても、御社のニーズとこのAPIで出来ることのご相談から承っております。
Twitter PowerTrack API を使ってツイートを取得する
Twitter Historical PowerTrack API を使ってツイートを取得する
Twitter Engagement API を使ってツイートを取得する
Twitter Premium Search API を使ってツイートを取得する
Twitter Historical PowerTrack APIと類似するその他のAPI
リアルタイム
リアルタイムにデータを取得することができる。
-
PowerTrack API
- リアルタイムなデータにルール/フィルタを適用したツイートを取得するAPI。
-
Decahose stream
- リアルタイムデータからサンプリングされた10%のツイートを取得するAPI。キーワード等でのフィルタリング機能はない
-
Account Activity API
- 指定したアカウントの活動を取得するためのAPI。例：ツイート、メンション、リツイート、フォロー、DMの送受信
ヒストリカル
過去の全ツイートから指定した条件にマッチするツイートのみを取得することができる。
-
30-Days Search API
- 過去30日の完全なツイートから条件にマッチしたツイートを取得するAPI
-
Full-Archive Search API
- 過去の全期間のツイートから条件にマッチしたツイートを取得するAPI
-
Historical PowerTrack API
- 過去の全期間のツイートに対してバッチジョブ形式でツイート取得を行うAPI
インサイト
ツイートに対するユーザーからの反応を取得することができる。例：ツイートのインプレッション、エンゲージメント、お気に入り、リツイート、リプライ、ビデオビュー
-
Engagement API
- 自分のツイートのインプレッション、エンゲージメント、全てのツイートのお気に入り、リツイート、リプライ、ビデオビューを取得するAPI
Twitter APIのRubyクライアント
RubyからTwitter APIへアクセスするクライアントにはいくつかの種類がある。
twitter gem
非公式のTwitter REST APIクライアント。通常のREST APIであればほとんど全てを網羅している。
search-tweets-ruby
公式のPremium Search API、Enterprise Search APIに対応したライブラリ。gemではなく、通常のRubyコードとして提供されている。
twitter-ads gem
公式のTwitter Ads APIクライアント。
関連リンク
Filter realtime Tweets
Get batch historical Tweets
Get Tweet engagement
Rules and filtering
Twitter Enterprise