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

[Twitter Engagement API](https://developer.twitter.com/en/docs/metrics/get-tweet-engagement/overview) を利用することで、指定したツイートのインプレッション、エンゲージメント、お気に入り、リツイート等を取得することができます。このページでは、Twitter Engagement APIの仕組み、取得できるメトリクス、返ってくるデータ形式について解説しています。

[Twitter Engagement API](https://developer.twitter.com/en/docs/metrics/get-tweet-engagement/overview) は、Twitterの法人プランを契約している開発者のみが利用できます。Twitter Engagement APIを使ったお仕事のご依頼、ご相談については、[@ts_3156](https://twitter.com/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](https://developer.twitter.com/en/docs/metrics/get-tweet-engagement/overview) は、Twitterの法人プランを契約している開発者のみが利用できます。Twitter Engagement APIを使ったお仕事のご依頼、ご相談については、[@ts_3156](https://twitter.com/ts_3156) までお気軽にご連絡ください。

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

[Twitter PowerTrack API を使ってツイートを取得する](https://qiita.com/ts-3156/items/18faf070d5038ef7f3b5)
[Twitter Historical PowerTrack API を使ってツイートを取得する](https://qiita.com/ts-3156/items/47090b045a168bfdd5db)
[Twitter Engagement API を使ってツイートを取得する](https://qiita.com/ts-3156/items/6a31452e680a445811de)
[Twitter Premium Search API を使ってツイートを取得する](https://qiita.com/ts-3156/items/62d2b89a24ea6cfcab8e)

## Twitter Engagement APIと類似するその他のAPI

### リアルタイム

リアルタイムにデータを取得することができる。

- [PowerTrack API](https://developer.twitter.com/en/enterprise#modal-powertrackapi)
    - リアルタイムなデータにルール/フィルタを適用したツイートを取得するAPI。
- [Decahose stream](https://developer.twitter.com/en/enterprise#modal-decahosestream)
    - リアルタイムデータからサンプリングされた10%のツイートを取得するAPI。キーワード等でのフィルタリング機能はない
- [Account Activity API](https://developer.twitter.com/en/enterprise#modal-accountactivityapi)
    - 指定したアカウントの活動を取得するためのAPI。例：ツイート、メンション、リツイート、フォロー、DMの送受信

### ヒストリカル

過去の全ツイートから指定した条件にマッチするツイートのみを取得することができる。

- [30-Days Search API](https://developer.twitter.com/en/enterprise#modal-30daysearchapi)
    - 過去30日の完全なツイートから条件にマッチしたツイートを取得するAPI
- [Full-Archive Search API](https://developer.twitter.com/en/enterprise#modal-fullarchivesearchapi)
    - 過去の全期間のツイートから条件にマッチしたツイートを取得するAPI
- [Historical PowerTrack API](https://developer.twitter.com/en/enterprise#modal-historicalpowertrackapi)
    - 過去の全期間のツイートに対してバッチジョブ形式でツイート取得を行うAPI

### インサイト

ツイートに対するユーザーからの反応を取得することができる。例：ツイートのインプレッション、エンゲージメント、お気に入り、リツイート、リプライ、ビデオビュー

- [Engagement API](https://developer.twitter.com/en/enterprise#modal-engagementapi)
    - 自分のツイートのインプレッション、エンゲージメント、全てのツイートのお気に入り、リツイート、リプライ、ビデオビューを取得するAPI

## Twitter APIのRubyクライアント

RubyからTwitter APIへアクセスするクライアントにはいくつかの種類がある。

### twitter gem

非公式のTwitter REST APIクライアント。通常のREST APIであればほとんど全てを網羅している。

[twitter gem](https://github.com/sferik/twitter)

### search-tweets-ruby

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

[
search-tweets-ruby](https://github.com/twitterdev/search-tweets-ruby)

### twitter-ads gem

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

[twitter-ads gem](https://github.com/twitterdev/twitter-ruby-ads-sdk)

## 関連リンク

[Filter realtime Tweets](https://developer.twitter.com/en/docs/tweets/filter-realtime/overview/powertrack-api)
[Get batch historical Tweets](https://developer.twitter.com/en/docs/tweets/batch-historical/overview)
[Get Tweet engagement](https://developer.twitter.com/en/docs/metrics/get-tweet-engagement/overview)
[Rules and filtering](https://developer.twitter.com/en/docs/tweets/rules-and-filtering/guides/using-premium-operators)
[Twitter Enterprise](https://developer.twitter.com/en/enterprise)