Twitter Engagement API を使ってツイートを取得する

Twitter Engagement API を利用することで、指定したツイートのインプレッション、エンゲージメント、お気に入り、リツイート等を取得することができます。このページでは、Twitter Engagement APIの仕組み、取得できるメトリクス、返ってくるデータ形式について解説しています。

Twitter Engagement API は、Twitterの法人プランを契約している開発者のみが利用できます。Twitter Engagement APIを使ったお仕事のご依頼、ご相談については、@ts_3156 までお気軽にご連絡ください。

Twitter Engagement API とは

Twitter社が提供する、「ツイートのインプレッション、エンゲージメント、お気に入り、リツイート等を取得する機能」のことです。ほとんどの機能にはユーザーコンテキストが必要ですが、公開情報についてはアプリケーションコンテキストを介してアクセスすることができます。

※Twitter Engagement APIは、Twitterの法人プランを契約している開発者のみが利用できます。

ユーザーコンテキストとは

「あるユーザーとしてログインしている状態」でデータを取得するためのAPI設定のこと。ログインしているユーザーしか知り得ない情報を取得する場合には、ユーザーコンテキストが必要です。Engagement APIの場合は、ツイートのインプレッション、エンゲージメントがこれに該当します。

アプリケーションコンテキストとは

「ログインしているユーザーに関係ない状態」でデータを取得するためのAPI設定のこと。ログインしていなくても分かる情報を取得する場合には、アプリケーションコンテキストが必要です。Engagement APIの場合は、あるツイートのお気に入り、リツイート、リプリ、ビデオビューがこれに該当します。

Engagement API のリクエストエンドポイント

Engagement APIには3つのエンドポイントがあります。

Current Totals: /totals

• 指定したツイートのインプレッションとエンゲージメントの合計指標を返します。
• 取得できるのは、インプレッション、エンゲージメント、お気に入り、リプライ、リツイート、ビデオビューの6つです。
• ユーザーコンテキストを使用して、過去90日以内に作成された自分のツイートのインプレッションとエンゲージメントのメトリクスを取得できます。
• アプリケーションコンテキストを使用して、任意のツイートのお気に入り、リツイート、リプライ、ビデオビューのメトリクスを取得できます。
• リクエストした時点でのインプレッション数とエンゲージメント数に基づいた分析データを取得します。
• ダッシュボードレポートの作成や、自分が所有する複数のアカウントを横断したエンゲージメント率の計算に最適です。
• リクエストごとに最大250ツイートまでのメトリクスのリクエストをサポートしています。

Last 28 hours: /28hr

• インプレッションの合計メトリック、エンゲージメントの合計メトリック、過去28時間以内に発生した個々のエンゲージメントメトリックの内訳を返すことができます。
• データはTweet IDでグループ化し、時系列で集計、日別、時間別にまとめることができます。
• 最近作成されたコンテンツのパフォーマンスを追跡するのに最適です。
• 利用可能なすべてのメトリクスをサポートしています。
• リクエストごとに最大25ツイートまでのメトリクスのリクエストをサポートしています。

Historical: /historical

• 2014年9月1日以降の任意の期間（期間は最大4週間）のインプレッション、エンゲージメント、個別のエンゲージメントメトリクスの内訳を返すことができます。
• 開始日と終了日のパラメータをサポートしており、期間が最大4週間までの特定の時間枠に絞り込む柔軟性を提供します。
• データはTweet IDでグループ化し、時系列で集計、日別、時間別にまとめることができます。
• 過去のベンチマークに対する最近のパフォーマンスを評価するのに最適です。
• 利用可能なすべてのメトリクスをサポートしています。
• リクエストごとに最大25ツイートまでのメトリクスのリクエストをサポートしています。

Engagement API で利用できるメトリクス

インプレッション Implressions

ツイートが閲覧された回数。この指標は、過去90日以内に投稿されたツイートのみが対象です。

エンゲージメント Engagements

ユーザーがそのツイートに対して何らかのアクションを起こした回数。この指標は、過去90日以内に投稿されたツイートのみが対象です。

お気に入り Favorites

ツイートがお気に入りされた回数。

リツイート Retweets

ツイートがリツイートされた回数。

リプライ Replies

ツイートに返信された回数。

ビデオビュー Video Views

指定されたツイート内の動画が少なくとも2秒間、50%表示された回数。

メディアビュー Media Views

ツイート内のメディアのすべてのビュー（自動再生とクリック）を、動画、GIF、画像でカウントした回数。

メディアエンゲージメント Media Engagements

ツイート内の画像や動画などのメディアがクリックされた回数。

URLクリック URL Clicks

ツイート内のURLがクリックされた回数。

ハッシュタグクリック Hashtag Clicks

ツイート内のハッシュタグがクリックされた回数。

詳細クリック Detail Click

ツイート内の「もっと見る」がクリックされた回数。

リンククリック Permalink Clicks

ツイートへのパーマリンク（このツイート専用の個別のWebページ）がクリックされた回数。

アプリインストール App Install Attempts

ツイートからのインストールイベントが起きた回数。

アプリオープン App Opens

ツイートからのアプリオープンイベントが起きた回数。

メールツイート Tweet Emails

メールでシェされた回数。

フォロー User Follows

ツイートからツイートの作者がフォローされた回数。

ユーザープロフィールクリック User Profile Clicks

ツイートからツイートの作者のプロフィールがクリックされた回数。

Twitter Engagement API を使った仕事のご依頼について

Twitter Engagement API は、Twitterの法人プランを契約している開発者のみが利用できます。Twitter Engagement APIを使ったお仕事のご依頼、ご相談については、@ts_3156 までお気軽にご連絡ください。

具体的に何をするのかが決まっていない場合であっても、御社のニーズとこのAPIで出来ることのご相談から承っております。

Twitter PowerTrack API を使ってツイートを取得する
Twitter Historical PowerTrack API を使ってツイートを取得する
Twitter Engagement API を使ってツイートを取得する
Twitter Premium Search API を使ってツイートを取得する

Twitter Engagement 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であればほとんど全てを網羅している。

twitter gem

search-tweets-ruby

公式のPremium Search API、Enterprise Search APIに対応したライブラリ。gemではなく、通常のRubyコードとして提供されている。

search-tweets-ruby

twitter-ads gem

公式のTwitter Ads APIクライアント。

twitter-ads gem

関連リンク

Filter realtime Tweets
Get batch historical Tweets
Get Tweet engagement
Rules and filtering
Twitter Enterprise