チュートリアル

履歴APIを選択する

このページの各セクションへのリンク

 

はじめに

Historical PowerTrackおよびFull-Archive Searchはどちらも、2006年3月の最初のツイート以降、一般公開されているすべてのツイートにアクセスできます。どちらの商品がお客様の使用目的により適しているかを決定することは、必要なときに必要なデータを収集するために重要です。この記事では、この2つの履歴商品の相違点に注目しており、今後のツイート履歴データセットの生成にどちらを使用すべきかを判断するために役立てていただけます。

どちらの履歴商品も、ツイートのアーカイブをスキャンし、対象期間中に投稿されたツイートを調査し、クエリに一致するツイートのセットを生成します。ただし、Historical PowerTrackとFull-Archive Searchはそれぞれ、大きく異なるアーカイブアーキテクチャをベースにしており、商品としては根本的に別のものです。これらの相違点には、サポートされるPowerTrack演算子、リクエスト1件あたりのルールやフィルターの数、推測の提供方法、データの配信方法などがあります。

まず、Historical PowerTrack APIとFull-Archive Search APIの概要を説明し、次にその相違点について詳しく解説します。まとめとして、履歴商品を選択する際の一般的なガイダンスを提供します。

Historical PowerTrack

Historical PowerTrack(HPT)は、バッチを使用して大規模にツイートを提供するために構築された、ジョブベースの設計となっており、APIは複数のフェーズを通してジョブを移動するために使用されます。これらのフェーズには、容量の推定、ジョブの許可や拒否、ジョブステータスの取得、何千にも及ぶ可能性のあるデータファイルのダウンロードなどがあります。リクエスト期間の長さによっては、ジョブの生成に数時間から数日かかることがあります。データファイルは、10分間分を1ファイルとして生成され、少なくとも1つのツイートを含みます。そのため、30日分のデータセットでは、一致するツイート数とは関係なく、一般的におよそ4,300ファイルが含まれます。

Historical PowerTrackは、2012年にGnipから提供されました。ファイルベースアーカイブ上に構築されており、各ファイルには短期間のリアルタイムツイートのFirehoseが含まれます。Historical PowerTrackがデータセットを生成する際、各ファイルを開いてファイル操作を行い、ファイル内の各ツイートを調べます。このプロセスの間、Historical PowerTrackは、関連付けられたPowerTrack演算子を持つJSONペイロードの全セクションにアクセスします。Historical PowerTrackでは、リアルタイムPowerTrackでサポートされているすべてのPowerTrack演算子セットをサポートしています。

Full-Archive Search

Full-Archive Search(FAS)は、Google検索と同様の方法で、条件に合うツイートを提供します。特定の語句について検索する場合、Google検索では、何百万にもなる可能性のある一致結果をすべて同時に返す、あるいは表示することはありません。そうではなく、スクロールできるページ内に少数の結果が表示され、ユーザーは [Next] をクリックして結果を含む後続のページを表示します。すべての一致項目が返されるまでこの操作を続けます。Full-Archive Searchも、ツイートのサブセットを使用して応答することで同様に機能します。必要に応じてより多くのツイートを返すようにページ割りができる機能があります。

Full-Archive Searchは、従来のRESTfulのリクエスト/応答パターンを使用して設計されています。ここでは、1つのPowerTrackルールが発行され、それに一致するツイートのある応答が直ちに提供されます。Full-Archive Searchでは、1つの応答で最大500ツイートを提供できます。クエリに対する全ツイートが受け取られるまで、「次へ」のトークンが表示されてページが続きます。クエリに一致するツイートが多いほど、検索APIを通じてすべてのデータを取得するのに要する時間は長くなります。これは、返された全データのセットを完成させるために、ページ割りされた結果のセットを順番につなぎ合わせる必要があるためです。

多くのユースケースでは、実際のツイートメッセージ自体ではなく、クエリに関連付けられたツイートの数に焦点を置いています。Full-Archive Searchは、一致するツイートの数を時系列で返す「カウント」エンドポイントをサポートしています。これらのツイート数は、分単位、時間単位、または日にち単位の総数が時系列で返されます。

なお、Twitterは、30日検索APIも提供しています。直近30日間のデータのみが必要な場合は、おそらくこのAPIがユースケースに最適です。

 

商品の相違点

Historical PowerTrackとFull-Archive Searchには、次のような根本的な相違点があります。

  • リクエスト1件あたりでサポートされるルール数

    • Historical PowerTrackのジョブは、最大1,000個のルールをサポートできます。
    • Full-Archive Searchで許可されるのは、1リクエストあたり1ルールです。

    • 注:各商品で、1つのルールに使用できる文字数は最大2,048字です。
  • データの提供方法

    • Historical PowerTrackは時系列のデータファイルを生成し、各ファイルには10分間分のデータが含まれます。たとえば、1時間分のデータは10分ごとのデータファイル6個で提供されます(10分間ごとに最低1つのツイートがあると仮定。ツイートがない場合、ファイルは作成されません)。そのため、Historical PowerTrackの「ジョブ」が終了したら、次の手順はそのデータファイルをダウンロードすることです。各履歴のPowerTrackファイルの内部には、JSONツイートペイロードが最小単位で書き込まれており、JSON配列には表示されません。ファイルの内容は、改行を区切り文字として解析する必要があります。
    • Full-Archive Searchでは、各応答に含まれるツイートが「結果」配列に整列されます。1リクエストにつき最大500ツイートが取得可能で、それ以上のツイートがある場合は、「次へ」トークンが表示されます。たとえば、1つのPowerTrackルールにおいて60日間を対象にしたリクエストで10,000件のツイートが一致する場合、検索APIを使用するには少なくとも20のリクエストが必要です。
  • サポートされるPowerTrack演算子

    • HPTがサポートする演算子の大多数はFASでもサポートされますが、FASで使用できない演算子のセットは次のとおりです。
bio: profile_bounding_box:
bio_location: profile_point_radius:
bio_name: profile_subregion:
contains: retweets_of_status_id:
is:quote sample:
followers_count: source:
friends_count: statuses_count:
has:lang url_contains:
in_reply_to_status_id:    url_description:
listed_count: url_title:
  • 各商品の演算子の全リストについては次を参照してください。
  • 使用可能な演算子を並べて比較するには、こちらを参照してください。
  • データ量の推定

    • Full-Archive Searchには、一致するツイートを分、時間、日付の時系列で生成するために使用される「カウント」エンドポイントがあります。実際のデータのほか、データ量についても知る必要があるユースケースの場合は、Full-Archive Searchの「カウント」エンドポイントが有用です。なお、「カウント」エンドポイントは、プレコンプライアントの一致ツイートの指標です。プレコンプライアントとは、ツイートの合計に削除されたツイートや保護されたツイートが考慮されていないことを意味するものです。データリクエストには削除されたツイートや非公開のツイートは含まれません。

    • Historical PowerTrack APIでは、1つのジョブで一致するツイートの数に関して大まかな推定数を提供します。これらの推定数は、サンプリングする対象期間に基づいており、履歴ジョブが返すデータ量に関する大まかな目安と認識してください。Historical PowerTrackの推定は、ジョブで一致するツイートの数が100,000単位なのか、1,000,000単位なのかを知るためのヒントとなるものです。この目的は、1つのリクエストが返すデータの量について妥当な予想値を提供することであり、Historical PowerTrackを推定ツールとして使用するべきではありません。

  • 商品のライセンスと価格

Full-Archive Search APIとHistorical PowerTrack APIはどちらも、12か月のサブスクリプションで使用できます。さらに、Historical PowerTrackは「1回限り」のご利用も可能です。そのため、一定期間のプロジェクトや一時的な調査のためにツイートの履歴データが必要な場合は、Historical PowerTrackが適しています。

 

履歴商品の選択

Full-Archive Searchは、比較的量の少ないデータセットを収集する場合に最適です。これに対し、Historical PowerTrackは、より大量のデータセットを扱う場合により適しています。一般的な推奨としては、ツイート数が数百万件以下のデータセットにはFull-Archive Searchが最適です。この推奨は、意図的にあいまいな表現になっています。膨大な量のリクエストにFull-Archive Searchを使用できない技術上の理由があるわけではないからです。ただし、予定しているデータの取得方法やAPIレート制限の使用方法によって、実際にHistorical PowerTrackの方がHistorical PowerTrackよりも高速にデータを処理できるというしきい値が存在します。たとえば、Historical PowerTrackジョブは6時間で800万ツイートを提供できます。Full-Archive Searchで800万ツイートを引き出すには、最低でも16,000の検索リクエストが必要です。また2秒の応答時間と、1つのスレッドでページ割りを行うアプリを仮定すると、Full-Archive Searchが800万のツイートデータセットを取得するのに必要な時間は、さらに長くなります。

データ量の検討や完了時間の比較以外にも、一方の履歴商品がユースケースに適している理由があります。Historical PowerTrackは、現在Full-Archive Searchでサポートされていない演算子を必要とする場合に最適な商品です(上述を参照)。Historical PowerTrackは、時間に制約のある調査には非常に有用です。Historical PowerTrackは、クエリにルールセットが大量にある場合にも適しています。検索API商品は、1つのリクエストにつき1つのPowerTrackルールのみをサポートするためです。一方、Historical PowerTrackは、最大1,000個のルールをサポートします。最後に、Historical PowerTrackは、「興味関心」の新しいツイート属性(ハッシュタグ、@ツイート、URLなど)をリアルタイムで収集することが履歴リクエストのトリガーとなるようなユースケースで、最適な選択となります。Historical PowerTrackではリアルタイムPowerTrackと同じすべての演算子セットをサポートしているため、対応するリアルタイムのルールをHistorical PowerTrackのジョブに常に「プラグイン」できます。

これに対し、Full-Archive Searchは、ほぼ即時に得られる結果やデータ量の推定に依存するツールを構築する場合に、最適な選択です。履歴ツイートの結果をダッシュボードやユーザーアプリケーションに構築する場合は、高速応答が重要になります。Full-Archive Searchは、ユーザーが作成したフィルターに一致するツイートを直ちに調べることができる多くのシステムに組み込まれてきました。最初の応答によっては、引き続き結果をページに表示することもできますし、あるいはフィルターの範囲を広げたり狭めたりして再試行することもできます。Full-Archive Searchでは、「カウント」エンドポイントを使用してより正確な量の推定ができるため、フィルターで確認してからリアルタイムストリームに追加するという検索方法も広く行われています。

 

次の手順

ソリューション作成の準備が整った方は

ドキュメントを確認して利用を開始しましょう