メインコンテンツへスキップ

​
概要

Enterprise これは当社のマネージドアクセスレベルでのみ利用可能なエンタープライズ向け API です。この API を利用するには、まず当社のエンタープライズ営業チームとアカウントの設定を行う必要があります。 詳細はこちら Engagement API は、Post のインプレッションおよびエンゲージメント指標へのアクセスを提供します。大半の指標とエンドポイントでは OAuth 1.0a ユーザーコンテキスト による認証が必要ですが、OAuth 2.0 Bearer Token と /totals エンドポイントを使用すれば、公開の Favorite、Retweet、Reply、Video Views の指標にアクセスできます。   注: 一部の X のウェブダッシュボードで報告されるデータと Engagement API で報告されるデータに差異が生じる場合があります。これは、ウェブダッシュボードが通常、選択した期間内に発生したエンゲージメントやインプレッションのみを表示するためです。例えば、ウェブダッシュボードはカレンダー上の1か月の範囲内の Post へのエンゲージメントを表示しますが、Engagement API では、その月の範囲外であっても要求された時間範囲内に含まれるエンゲージメントが表示される場合があります。これらの場合、Engagement API を正確な情報源として扱ってください。  

​
リクエストエンドポイント

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

​
現在の合計: [/totals]

  • リクエストは、対象の Post に対するインプレッション合計とエンゲージメント合計のメトリクスを返します
  • 対応メトリクスは次のとおりです: Impressions、Engagements、Favorites、Replies、Retweets、Quote Tweets、Video Views
  • OAuth 1.0a ユーザーコンテキストを使用して、直近90日以内に作成された Post の Impressions および Engagements メトリクスの取得に対応
  • OAuth 2.0 ベアラートークンを使用して、任意の Post の Favorites、Retweets、Quote Tweets、Replies、および Video Views メトリクスの取得に対応
  • 結果は、リクエスト時点の最新のインプレッションおよびエンゲージメントの合計に基づきます
  • ダッシュボードレポートの作成や、さまざまな @handle をまたぐエンゲージメント率の算出に最適です
  • 1 回のリクエストで最大 250 件の Post のメトリクス取得に対応  

​
直近28時間: [/28hr]

  • リクエストは、インプレッションの合計、エンゲージメントの合計、および直近28時間に発生した個別のエンゲージメント指標の内訳を返せます
  • data は Post ID 単位、または時系列（合計、日別、時間別）で集計してグループ化できます
  • 最近作成したコンテンツのパフォーマンスの追跡に最適です
  • 利用可能なすべての指標をサポートします
  • 1回のリクエストで最大25件の Post の指標を取得できます  

​
履歴: [/historical]

  • リクエストは、直近1年間について、Postの作成時刻ではなくエンゲージメント発生時刻に基づき、インプレッション、エンゲージメント、および個別のエンゲージメント指標の内訳を返すことができます。
  • リクエストは開始日と終了日パラメータをサポートし、最大4週間の期間で特定の期間に絞り込む柔軟性を提供します。
  • Postのエンゲージメントdataは、過去365日分に限定されます。
  • dataはPost IDによるグルーピングに加え、集計の時系列（日単位または時間単位）でのグルーピングが可能です。
  • 直近のパフォーマンスを過去のベンチマークと比較評価したり、@handleのパフォーマンスの履歴を把握したりするのに最適です。
  • 利用可能なすべての指標をサポートします。
  • 1回のリクエストで最大25件のPostの指標をリクエストできます。

​
利用可能なメトリクス

以下の表では、Engagement API で取得可能なメトリクスの種類を説明します。 各メトリクスの詳細については、メトリクスの解釈をご参照ください。
メトリクスエンドポイントの稼働状況ユーザーコンテキストが必要です概要
インプレッション数すべてはいPost が閲覧された回数です。この指標は、過去90日以内に投稿された Post にのみ利用可能です。
エンゲージメント数すべてはいユーザーがそのPostとやり取りした回数の合計。この指標は、過去90日以内に投稿されたPostにのみ利用可能です。
お気に入りすべてはい - /28時間&/履歴

いいえ - /totals		Post が「お気に入り」された回数。
リツイートすべてはい - /28時間&/履歴

いいえ - /totals		Post がリツイートされた回数。
引用符_Tweets/totalsいいえ - /totalsコメント付きでRetweet（Quote とも呼ばれる）された Post の回数。
返信すべてはい - /28時間&/履歴

いいえ - /totals		Post に対する返信数。
動画_表示回数すべてはい - /28時間&/履歴

いいえ - /totals		指定されたPost内の動画が、少なくとも2秒間にわたり50%可視だった回数。

動画再生数は、1800日以内のPostに対してのみ取得できます。1800日を超えるPostの動画再生数をリクエストした場合、リクエストしたその他の指標を含む別のオブジェクトとあわせて、レスポンス内に次のオブジェクトが返されます。

“サポート対象外_用_ビデオ_表示数_Tweet_ids”: [“Tweet_ID”]

**ご注意ください：**X が所有・運営するプラットフォーム（モバイルアプリおよびウェブサイト）に表示される動画の視聴数指標と、/28hr および /historical エンドポイントで取得する数値の間に差異が生じる場合があります。

- X のユーザーインターフェースおよび /totals エンドポイントに表示される動画再生数は、当該動画が投稿されたすべての Post を横断して集計された数値です。つまり、UI に表示される指標には、その動画が別の Post でリツイートまたはリポストされたあらゆるインスタンスでの再生数が合算されています。この指標には GIF の動画再生数は含まれません。
- /28hr および /historical エンドポイントで提供される動画再生数には、指標を取得している特定の Post で発生した再生のみが含まれます。この指標には、GIF の動画再生数は含まれません。
メディア_表示数/28時間 /historicalはい動画、GIF、画像を対象に、自動再生とクリックによるすべての閲覧の合計数。
メディア_エンゲージメント数

(旧称 Media Clicks)		/28hr /historicalはいPost 内の画像や動画などのメディアがクリックされた回数。
URL_クリック数/28hr /historicalはいPost 内のURLがクリックされた回数。
ハッシュタグ_クリック数/28hr /historicalはいPost 内のハッシュタグがクリックされた回数。
詳細_拡張/28時間 /historicalはいPost の詳細表示のためにクリックされた回数。
パーマリンク_クリック数/28時間 /historicalはいPost（このPost専用の個別ウェブページ）へのパーマリンクがクリックされた回数。
アプリ_インストール_試行回数/28時間 /historicalはいPost から発生した App Install イベントの発生回数
アプリ_開封数/28時間 /historicalはいPost から発生した App Open イベントの発生回数。
Eメール_Tweet/28時間 /historicalはいPost がメールで共有された回数。
ユーザー_フォロー中/28時間/過去データはいこのPostから、そのユーザー（Postの作成者）がフォローされた回数。
ユーザー_プロフィール_クリック数/28hr /historicalはいこのPostから、そのユーザー（Post の作者）のプロフィールがクリックされた回数。

​
エンゲージメントのグルーピング

グルーピングを使用すると、返されるエンゲージメント指標を任意の区分で整理できます。1回のリクエストにつき最大3つまでグルーピングを指定できます。指標は次の値の1つ以上でグループ化できます。 3つのエンドポイントすべてでサポート:
  • tweet.id
  • engagement.type  
/28hr および /historical は時系列指標を提供できるため、次もサポート:
  • engagement.day
  • engagement.hour
グルーピングの詳細は、ガイド内の Engagement API Grouping ページをご覧ください。

​
ガイド

​
開発者向けスタートガイド

​
はじめに

このドキュメントは、開発者向けに Engagement API との統合方法を紹介することを目的としています。まずは統合する理由を説明し、その後で技術的にどのように実装するかを詳しく見ていきます。
Engagement API は何を提供しますか？
  • Engagement API は、対象アカウントが 3-legged OAuth によってあなたのアプリに代理でメトリクス取得を許可していることを前提に、過去90日間の任意の X アカウントが所有する Post のインプレッションおよびエンゲージメントデータを提供します。強力でありながら実装が容易なこのソリューションにより、インプレッションに加え、URL クリックや #hashtag クリックなどの深いエンゲージメントに即時アクセスできます。
  • Engagement API は、任意の Post に対する「お気に入り」、Retweet、Quote Tweet、返信、動画再生数の合計集計メトリクスを提供します。これは、任意の Post または Post のコレクションに関するベーシックなエンゲージメントデータを取得する強力な手段として利用できます。
  • Engagement API は、15以上のパフォーマンスメトリクスを用いてコンテンツの成果を正確に測定し、X 上での ROI を評価できるようにすることで、ソーシャルリスニング、マーケティング、パブリッシングプラットフォームに新たな価値を提供します。
  • Engagement API はリクエスト/レスポンス型の API であり、アプリ開発者は Post の id、取得したいメトリクス、期間を指定してリクエストを送信でき、API は即座に data を返します。  
なぜ統合するのか？ ユースケース例
  • コンテンツの総リーチを把握し、どれだけのユーザーに閲覧されたかを確認します。動画の再生数、リンクのクリック数、ハッシュタグのクリック数、アプリのインストール数も把握できます。
  • 総計および時系列のエンゲージメント指標を生成します。
  • 任意の公開Postに関する基本的なエンゲージメント指標（いいね、Retweet、Quote Tweet、返信）を把握します。
  • これらの指標を活用して効果的なPostのタイプを見極め、同様の投稿を増やして、インプレッションとエンゲージメントをさらに獲得します。
  • 自分のPostが100件のLike、または別の閾値に達するたびに、（別の自社アカウントからのRetweetなどの）マーケティング施策を自動化します。
  • A/Bテストの手段として、キャンペーン同士をベンチマーク・比較します。
  • カスタマーサービス部門に響くコンテンツの種類を分析し、対応すべき方法とタイミングを判断します。
  • 自社プラットフォームから公開されたコンテンツのアナリティクスを表示します。  
Engagement APIは2016年にローンチされ、詳細なエンゲージメント指標をスケールして提供した初のX APIでした。Engagement APIは使いやすく、プロセスの自動化を可能にします。以下は、統合例を説明するケーススタディです。 Engagement APIの「なぜ」を見てきたので、ここからは技術的な詳細に踏み込んでいきましょう。

​
Engagement API の統合方法

API の概要
Engagement API は、JSON でエンコードされたリクエストを受け取り、JSON でエンコードされたエンゲージメント指標で応答する、シンプルな RESTful API です。リクエストは主に次の3つの要素で構成されます（詳細はリンク先を参照）:
  • Post ID の配列
  • 関心のあるメトリックタイプを指定する配列。タイプには「impressions」「retweets」「hashtag_clicks」「user_follows」などが含まれます。
  • Engagement groupings。API レスポンスでエンゲージメントのデータをどのようにグルーピングするかを示す JSON 構造です。
多くの場合、Engagement Types と Groupings はリクエスト間で比較的固定で、更新されるのは Post ID のみです。 Engagement API には3つのエンドポイントがあります:
  • Totals - Post に対するエンゲージメントの総計を返します。一部のメトリクスはすべての Post で利用可能ですが、他は過去90日分のみ利用可能です。
  • 28 hour - 直近28時間の時系列エンゲージメント指標を返します。
  • Historical - 2014年9月1日以降に投稿された Post を対象に、最大4週連続の時系列エンゲージメント指標を返します。
/totals エンドポイントは、1リクエストあたり 最大250件の Post のメトリクス取得をサポートします。/28hour および /historical エンドポイントは 1リクエストあたり25件 をサポートします。 Engagement API へのアクセス方法について説明した後、API リクエストの作成手順、OAuth の概要、その他の技術リソースへのリンクを順に紹介します。
API へのアクセスの取得
このドキュメントをお読みの場合、すでに Engagement API へのアクセス権をお持ちの可能性が高いです。未取得の場合は、エンタープライズのアカウントマネージャーに連絡するか、こちらからエンタープライズアクセスを申請してください。 最初のステップは、開発者ポータルから承認済みの開発者アカウントを用いて X アプリ を作成することです。アクセス付与のために、アカウントマネージャーはこのアプリに関連付けられた数値の App ID を必要とします。開発者アカウントの申請が必要な場合は、こちらから申請できます。
リクエストの作成
朗報です。Engagement API へのリクエストはシンプルです。今回は、次の2つの @XDevelopers のPostについて、Retweet、Quote Tweet、Favorite、返信の合計値を取得します。
1/ 本日、X API プラットフォームの未来に向けたビジョンを共有します！https://t.co/XweGngmxlP — Twitter Dev (@TwitterDev) 2017年4月6日
あなたのPostに関するPostをお見逃しなく。 iOS で、コメント付きのRetweetを1か所でまとめて確認できるようになりました。 pic.x.com/oanjZfzC6y — X (@X) 2020年5月12日
最初のステップは、JSON で API リクエストを組み立てることです。2つのPostのidを配列に入れ、取得したいエンゲージメント種別の配列を用意し、レスポンスでのメトリクスの並びを指定する、任意名の「groupings」JSON オブジェクトを含めます。以下がリクエストの例です。 Example image 
{
  "tweet_ids": [
    1260294888811347969, 850006245121695744
  ],
  "engagement_types": [
    "retweets", "quote_tweets", "favorites", "replies"
  ],
  "groupings": {
    "engagement-types-by-id": {
      "group_by": [
        "Tweet.id", "engagement.type"
      ]
    }
  }
}
これらの合計メトリクスを取得するには、https://data-api.x.com/insights/engagement/totals エンドポイントにこの JSON リクエストを POST します。 リクエストが JSON でエンコードされ、かつ Gzip 圧縮されていること（リクエストボディが大きくなる場合があります）を示すため、次のヘッダーを含めます。
  • Content-Type: application/json
  • Accept-Encoding: gzip  
リクエスト送信時の認証には OAuth を使用します。詳細は次のセクションで説明します。 API は次のペイロードを返します。 
{
  "グループ名": {
    "1260294888811347969": {
      "いいね": "17111",
      "引用ポスト": "3254",
      "返信": "1828",
      "リポスト": "5218"
    },
    "850006245121695744": {
      "いいね": "492",
      "引用ポスト": "66",
      "返信": "42",
      "リポスト": "324"
    }
  }
}
レスポンスには、「groupings」の定義で説明されている構造に従って、要求したメトリクスが含まれている点に注意してください。メトリクスはまず Post のIDごとに、その次の階層でエンゲージメント種別ごとに列挙されています。 簡単でしたね。OAuth での認証が初めての方は、次のセクションをご覧ください。

​
OAuth での認証

OAuth はテクノロジー業界で広く利用されている認証標準です。すでに OAuth（他の X API など）を利用している場合は、細かな面倒を吸収してくれる言語別の OAuth パッケージを使っている可能性が高いでしょう。OAuth が初めての方は、まず OAuth with the X API のページをご覧いただくか、https://oauth.net に直接アクセスして学んでください。そのうえで、使用する言語に合った OAuth パッケージを選び、そこから始めることをおすすめします。これらのパッケージでは、一般的に、キーやトークンを設定し、HTTP オブジェクトを作成し、そのオブジェクトでリクエストを送る、という流れで認証を行います。 例えば Ruby では、以下の擬似コードは、Ruby の gem “oauth” を用いて OAuth 対応のアプリを構築し、POST リクエストを行う手順の例を示しています。 
require 'oauth'

#JSONリクエストを組み立てます（上記参照）。
request = make_json_request()

#アプリのコンシューマキーとシークレットを使って、アプリのコンシューマオブジェクトを作成します。
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => ‘https://data-api.x.com’})
#権限を付与したアカウントから提供されたトークンでユーザートークンを作成します。アプリ専用のリクエスト（/totals エンドポイントで許可不要の Tweet を確認する場合）では、この手順は省略できます。
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#OAuth対応のアプリオブジェクトを作成します。
app = OAuth::AccessToken.from_hash(consumer, token)
#POST リクエストを送信します。
result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})
Engagement API は、アプリケーションのみ認証とユーザーコンテキスト認証の両方をサポートしています。/totals エンドポイントで、所有していない公開 Post のエンゲージメント指標を収集する場合、ユーザーの許可は不要で、アプリケーションのみ認証を利用できます。この場合は、認証にアプリキーとシークレットのみを使用します。 OAuth では、ユーザーに紐づくトークンを用いて、アプリが「他のユーザーに代わって」API リクエストを行うこともできます。所有する Post、すなわちユーザートークンを保有しているユーザーが投稿した Post のエンゲージメント指標を生成する場合は、ユーザーコンテキストでリクエストを行います。これは、アプリキーとユーザー固有のアクセストークンの両方で認証することを意味します。これらのユーザーアクセストークンは通常、‘Sign-in with X’ プロセスで提供されるか、ユーザーから直接取得されます（ユーザーから直接トークンを取得する場合は twurl を使用する必要があります）。ユーザーがトークンを提供した後は、それらは有効期限がなく、ユーザーがトークンをリセットするかパスワードを変更しない限り、そのユーザーに代わってリクエストを行うために Engagement API で使用できます。いずれかに該当する場合は、新しいトークンを提供してもらう必要があります。 どの指標にどの認証が必要かは、この表で確認できます。

​
Engagement API エンドポイントの選択

Engagement API には次の 3 つの明確に異なるエンドポイントがあります。
  • Totals - “owned” または “unowned” の Post を対象に、選択した指標の合計値を提供します。一部の指標はすべての Post で利用可能ですが、他の指標は過去 90 日以内に公開された Post のみ利用可能です。1 リクエストあたり最大 250 件の Post に対応します。
  • 28 hour - 過去 28 時間の “owned” な Post に対する時系列のエンゲージメント指標を提供します。1 リクエストあたり最大 25 件の Post に対応します。
  • Historical - 2014 年 9 月 1 日以降に投稿された “owned” な Post を対象に、最大 4 週間連続の時系列エンゲージメント指標を提供します。1 リクエストあたり最大 25 件の Post に対応します。  
各エンドポイントには固有の特性があります。3 つすべてを利用する場合でも、ユースケースに最適なものを選定する場合でも、それらの違いを理解することが重要です。 以下では、主要な概念を紹介し、3 つのエンドポイントを詳しく解説し、一般的に特定のエンドポイントに対応するユースケース例を示します。本情報が、3 つすべてを効率的に統合する、または単一のエンドポイントのうち目的に最適なものを選ぶ際の助けとなれば幸いです。  

​
重要な概念

3つの Engagement API エンドポイントが備える機能や提供されるデータの違いを示すうえで役立つ、いくつかの重要な概念があります。  
インプレッションおよびエンゲージメント指標
インプレッションは、特定のPostがXプラットフォーム上でオーガニックなコンテキストで表示された回数を表します。PromotedまたはPaidのコンテキストで表示されたPostによるインプレッションは含まれません。Engagement API以前は、Postのインプレッションは潜在的な閲覧数を示す指標に過ぎず、投稿者のアカウントのフォロワー数や、そのコンテンツをRetweetしたアカウントのフォロワー数の合計に基づいていました。特定のユーザーが実際にはそのPostを見ていないという一般的な状況は考慮されていませんでした。 Engagement APIによって生成されるインプレッション指標は、Postが表示のために実際にレンダリングされた回数を測定したものです。あなたのアカウントのフォロワーがあなたのPostを見逃した場合、それはインプレッションとしてカウントされません。 Engagement APIは、Postが表示された際にユーザーが取り得る個別のアクションを表す、14種類の固有のエンゲージメント指標タイプに関するメトリクスを提供します。これには、Retweet、Like、Reply、#hashtags・リンク・メディアなどのエンティティのクリック、投稿者のフォロー、投稿者のプロフィールの閲覧が含まれます。これらすべての個別アクションは、単一のEngagements指標に集約されます。
所有コンテンツと非所有コンテンツ（X）
Engagement では、所有している Post と所有していない Post を明確に区別します。所有している Post とは、あなたのアカウントから投稿された Post、またはその Post の Engagement データをリクエストする許可を取得したものを指します。他の X API と同様に、この許可は、他の X ユーザー／アカウントが、あなたがそのユーザーに代わって API リクエストを行えるようにするアクセス トークンを共有することで得られます。これらのトークンを取得する一般的な方法としては、Sign in with X のフローがあります。 /totals エンドポイントは、所有・非所有いずれの Post に対してもエンゲージメントの data を提供します。非所有の Post については、Post の表示で公開されているエンゲージメント指標（Favorite、Retweet、Reply）をリクエストできます。Engagement API の価値は、これらの指標を自動化された手段で大規模に取得できる点にあります。所有している Post については、/totals エンドポイントで Impression および（合計）Engagement 指標も提供されます。 /28hr および /historical エンドポイントは、所有している Post に対する指標のみを提供します。つまり、これらのエンドポイントにリクエストする際は、ユーザー コンテキストを付与する必要があります。
合計および時系列のエンゲージメントデータ
/​totals エンドポイントは、その名称が示すとおり、各エンゲージメント種別の合計のみを提供します。これらの数値は、Post が投稿されてから現在までの最新の累計を表します。Post を投稿した直後にメトリクスを繰り返しリクエストすると、リクエストのたびにこれらの合計が更新されるのが一般的です。 /​28hr と /​historical エンドポイントは、合計と時系列データの両方を提供できます。時系列データをリクエストする場合、エンゲージメントのメトリクスは日次または時間単位で集計できます。   /​28hr および /​historical エンドポイントで時系列データをリクエストする方法については、engagement groupings に関するドキュメントを参照してください。

​
エンドポイントと利用例

上で述べた特性や相違点を踏まえると、各エンドポイントは一般的に異なる種類のユースケースに対応します。特定のユースケースに最適なエンドポイントを選ぶ際の参考として、以下にユーザーの想定発話例と、それに最適なエンドポイントを示します。
/totals
  • 一部のメトリック種別（Impressions、Engagements、Favorites、Retweets、Quote Tweets、Replies、Video Views）へのアクセスだけで十分です。
  • 自分が所有するPostだけでなく、任意のPostの基本的なエンゲージメントdataにアクセスしたい。
  • 競合他社とのパフォーマンスを比較したい。
  • 自分が所有していないPostを含むハッシュタグやキャンペーンの基本的なエンゲージメント統計を追跡したい。
  • 日別や時間別に分割されたdataは不要で、リクエスト時点の合計値だけが必要です。
  • レポートやダッシュボードに表示する単一のメトリックが必要で、dataは保存したくない。
  • ページ読み込み時にdataを表示したく、リクエストしてレスポンスを受け取るだけでよい。
  • 1日に数十万〜数百万件のPostのdataを取得するためのアクセスが必要です。  
/28hr
  • 17種類すべての指標タイプにアクセスする必要があります。
  • 直近28時間に投稿された最新のPostのデータを表示したい。
  • 1日1回実行するジョブがあり、必要なデータは直近1日分のみ取得すればよい。
  • 指標を日別または時間別に分割して取得する必要があります。
  • ダッシュボードで1時間ごとのアクティビティを時系列で表示したい。
  • 1日あたり数十万件のPostに対して高いアクセス権限が必要です。
  • ストレージのキャパシティがあり、1日1回dataをリフレッシュして累計を持続的に保持できます。  
/historical
  • 17種類すべてのメトリックタイプにアクセスする必要があります。
  • 2014年9月まで遡って作成されたPostの過去データを取得する必要があります。
  • キャンペーン同士を比較する詳細な過去分析を表示したいです。
  • メトリクスを日別または時間別に内訳で確認できる必要があります。
  • Engagement API への高レベルのアクセスは不要で、1日に数百〜数千件のPostについてのdataを取得できれば十分です。

​
Engagement API キーの特性

  • RESTful API は JSON データを返し、JSON ボディを持つ POST リクエストをサポートします。
  • リクエストの種類: クライアントアプリは次の種類のリクエストを行えます:
    • 合計エンゲージメント — /totals エンドポイントへの HTTP POST リクエスト
    • 直近28時間のエンゲージメント — /28hr エンドポイントへの HTTP POST リクエスト
    • 履歴エンゲージメント — /historical エンドポイントへの HTTP POST リクエスト
  • OAuth 認証:
    • OAuth 1.0a ユーザーコンテキスト: 3-legged OAuth を使用してあなたのアプリを認可したユーザーが所有する Post については、提供されるすべての指標が利用できます。リクエスト時にはそのユーザーの Access Token を使用する必要があります。
    • OAuth 2.0 ベアラートークン: 特定の指標（Retweets、Quote Tweets、Replies、Favorites、Video Views）は、任意の公開 Post で利用可能です。
  • リクエストのメタデータと構造: リクエストデータは、Post ID の配列、エンゲージメントタイプの配列、エンゲージメントのグルーピング構造で構成される JSON オブジェクトです。
  • リクエストあたりの Post 数:
    • /totals エンドポイント: 250 Post ID
    • /28hr エンドポイント: 25 Post ID
    • /historical エンドポイント: 25 Post ID
  • エンゲージメント指標の提供範囲:
    • /totals — Post の投稿以降の累計。Impressions と Engagements は直近90日以内に公開された Post で利用可能で、Retweets、Quote Tweets、Replies、Favorites、Video Views はすべての Post で利用可能です。
    • /28hr — リクエスト時点から直近28時間。
    • /historical — 2014年9月1日から始まる任意の28日間。
  • 指標タイプ: 各リクエストには Metric Types の配列が含まれます。提供範囲はエンドポイントに依存し、/totals エンドポイントの場合は Post がユーザー許可済みかどうかにも依存します。
    • /totals エンドポイント:
      • すべての Post: Favorites、Retweets、Quote Tweets、Replies、Video Views
      • OAuth 1.0a ユーザーコンテキストが必要: Impressions、Engagements、Favorites、Replies、Retweets
    • /28hr および /historical エンドポイント（Post 所有者の Access Token を用いた OAuth 1.0a ユーザーコンテキストが必要）: Impressions、Engagements、Favorites、Replies、Retweets、URL Clicks、Hashtag Clicks、Detail Click、Permalink Clicks、Media Clicks、App Install Attempts、App Opens、Post Emails、Video Views、Media Views
  • エンゲージメントのグルーピング: 各リクエストには Engagement Groupings の配列が含まれます。これらのグルーピングにより、返される指標の整理方法をカスタマイズできます。各リクエストには最大3つまでグルーピングを含められます。指標は以下の値で整理できます:
    • すべてのエンドポイント: Post ID、Engagement Type
    • /28hr および /historical エンドポイント: 次の追加グルーピングを指定した場合、時系列が提供されます: Engagement Day、Engagement Hour
  • 統合に関する期待事項: 貴チームには以下の責任があります。
    • リクエストに含まれる Post ID についてエンゲージメント指標を返す Engagement API へ HTTP リクエストを送信できるクライアントアプリの作成と保守。
  • 制限事項
  • Video Views は、Post が公開から 1,800 日以内のものに限り利用可能です。

​
Engagement API での認証

ご注意: API を使用開始する前に、X があなたの開発者アプリに対して Engagement API へのアクセスを有効化する必要があります。認証に使用する予定のアプリの App ID を、アカウントマネージャーまたはテクニカルサポートチームに必ず共有してください。
Engagement API には 2 つの認証方法があります: OAuth 1.0a と OAuth 2.0 Bearer Token。 OAuth 2.0 Bearer Token（「application-only」とも呼ばれます）は、公開されているエンゲージメント指標へアクセスできます。この認証方法は、/totals エンドポイント へのリクエスト時に、公開されている任意の Post について Favorites（別名 Likes）、Retweets、Quote Tweets、Replies、動画再生数の合計値を取得するために使用できます。 OAuth 1.0a（「user context」とも呼ばれます）は、ユーザーに代わってリクエストを送信し、当該ユーザーに属する非公開のエンゲージメント指標にアクセスできます。 この認証方法が必要となるのは次の場合です:
  • /28hr エンドポイント および /historical エンドポイント に送信されるすべてのリクエスト
  • 次のいずれかの非公開メトリクスへのアクセス: Impressions、Engagements、Media Views、Media Engagements、URL Clicks、Hashtag Clicks、Detail Expands、Permalink Clicks、App Install Attempts、App Opens、Email Post、User Follows、User Profile Clicks
OAuth 1.0a でリクエストを送信する場合、対象の Post または保護されたリソースの所有者であるユーザーの Access Tokens（Access Token と Secret）を含める必要があります。保護されたユーザーデータをリクエストする際に正しいユーザーの Access Tokens を提供しない場合、Engagement API は 403 Forbidden エラーを返します。 Engagement API では、たとえこれらの Post の所有者であるユーザーに代わって認証している場合でも、保護された Post のエンゲージメントデータを取得することはできません。これを試みると、メッセージ "Tweet ID(s) are unavailable" とともに 400 Bad Request エラーが返されます。 自分の X アカウント（つまり、開発者アプリを所有するアカウント）に代わってリクエストを送信する場合は、開発者ポータル の該当アプリの「Keys and tokens」タブから、必要な Access Tokens を直接生成できます。 他のユーザーに代わってリクエストを送信する場合は、必要な Access Tokens を取得するために 3-legged OAuth フローを使用する必要があります。方法の詳細は次のドキュメントを参照してください: OAuth 1.0a: how to obtain a user’s access tokens。 その他の例（OAuth 1.0a を使用した認証方法を含む）については、X Developers の Engagement API 向けサンプル Python コードを参照してください。

​
Engagement API の最近の変更

Engagement API は、X 上でのアクティビティの成果を監視するために不可欠なインプレッションおよびエンゲージメント指標を提供します。X 全体で指標の整合性を高め、当社の data に基づくマーケティング判断を可能にする継続的な取り組みの一環として、Engagement API の最近の変更点をお知らせします。   最近、Engagement API をモダナイズし、X のアナリティクスダッシュボード（analytics.x.com）で使用されているものと同一の指標集計手法に合わせる変更を展開しました。新しい指標の導入にあたり、破壊的な API 変更を最小限に抑えるよう慎重に進め、2017 年 10 月 9 日に最初の変更セットを展開しました。これらの変更により、あなたやお客様が X 上の成果を可視化するあらゆる場所で一貫性が向上します。以下に変更点の詳細を示します。
MetricChange
engagementsoverall engagements を構成する内訳指標を更新し、Post アナリティクスダッシュボードとの整合性を持たせました。Engagements は「この Post にユーザーが操作・反応した回数」を表します。

動画や GIF などのメディアを含む Post では、engagements 指標にメディアのビューは含まれなくなりました。メディアのビューは新しい指標 media_views で参照できます。
media_clicks*この指標は新しい指標「media_engagements」に置き換えられました。
video_views2018 年 7 月 6 日以降、この指標は「未所有」の Post についても /totals エンドポイントで利用可能です。つまり、アプリのみの認証を使用することで、すべての Post の動画再生数にアクセスできます。 

リクエストできる動画再生数は 1800 日以内のものに限られます。1800 日より前の Post の動画再生数をリクエストすると、次のレスポンスが返されます。

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

注意: media_views と異なり、video_views は MRC の基準（動画の 50% が少なくとも 2 秒間視認されること）に準拠します。

また、X が自社運営するプラットフォーム（モバイルアプリおよびウェブサイト）に表示される動画再生数と、/28hr および /historical エンドポイントで取得する数値に差異が生じる場合があります。

* X のユーザーインターフェースに表示され、/totals エンドポイントで提供される動画再生数は、該当する動画が投稿されたすべての Post を横断して集計された値です。つまり、UI に表示される指標には、その動画がリポストや引用リポストされたすべてのインスタンスの合算ビューが含まれます。
* /28hr および /historical エンドポイントで提供される動画再生数は、指標を取得している特定の Post によって生成されたビューのみを含みます。
media_views動画、Vine、GIF、画像全体でカウントされた、あなたのメディアのすべてのビュー（自動再生およびクリック再生）を含みます。

注意: 画像を含む Post については、アナリティクスダッシュボードには media_views 指標が表示されませんが、Engagement API では返されます。
media_engagements*動画、Vine、GIF、画像全体でのメディアへのクリック数を含みます。この指標は media_clicks を置き換えるものです。
quote_tweets2020 年 7 月 7 日以降、この指標は「未所有」の Post についても /totals エンドポイントで利用可能です。つまり、アプリのみの認証を使用して、すべての Post の引用 Post 数にアクセスできます。

​
指標の解釈

注: 一部のXのウェブダッシュボードで報告されるdataと、Engagement APIで報告されるdataに差異が見られる場合があります。これは、ウェブダッシュボードが通常、選択した期間内に発生したエンゲージメントやインプレッションのみを表示するためです。たとえば、ウェブダッシュボードはカレンダー月の期間内のPostへのエンゲージメントのみを表示しますが、Engagement APIはその月をまたいでいても、要求した時間範囲内に含まれるエンゲージメントを表示する場合があります。これらの場合には、Engagement APIを正確な情報源として参照してください。  

​
インプレッションおよびエンゲージメントデータ

Engagement API は、オーガニックのインプレッションとエンゲージメントデータを提供します。 インプレッションは、特定の Post が X プラットフォーム上でオーガニックなコンテキストで表示された回数を指します。プロモーションや有料のコンテキストで表示された Post によるインプレッションは含まれません。 エンゲージメントは、特定の Post が閲覧者からオーガニックおよびプロモーションの両コンテキストで反応を得た回数を指します。エンゲージメントには、リツイート、いいね、返信、URL クリック、ハッシュタグクリック、メンションクリック、メディア再生（閲覧）などが含まれますが、これらに限定されません。含まれるエンゲージメントアクションの全一覧は、Engagement Data セクションをご参照ください。 ベースラインのエンゲージメント率を算出するには、分析対象期間内の特定の Post について、エンゲージメント総数をインプレッション総数で割ってください。 インプレッションおよびエンゲージメントデータは、あなたが所有する @handle の Post、またはあなたのアプリに自分の Post の詳細閲覧を許可した @handle の Post に対してのみ取得できます。内部的には、Engagement API は、契約上の @handle 上限に対してリクエストされた一意の @handle 数を追跡します。クライアント側でも、月間を通じて @handle のリクエスト使用状況を追跡することを推奨します。  

​
動画メトリクス

X 内のメディアのインプレッションを表すメトリクスには、いくつかの種類があります。1つ目は動画視聴数（video views）で、動画の50%が少なくとも2秒間視認されているという MRC 標準に基づきます。2つ目は Media Views で、自動再生およびクリックによる視聴を含む、動画・Vine・GIF・画像にわたるメディアのすべての視聴を合算します。 動画視聴数メトリクスは、所有する Post に対しては /28hour および /historical エンドポイントで、すべての非所有の Post に対しては /totals エンドポイントで利用できます。  X のユーザーインターフェース内の動画視聴数メトリクスも同じ MRC 標準を使用していますが、X が所有・運営するプラットフォーム（モバイルアプリおよびウェブサイト）に表示される動画視聴数と、各 Engagement API エンドポイントから取得する数値の間に差異が生じる場合がありますのでご注意ください。
  • /totals エンドポイントおよび X のユーザーインターフェースで提供される動画視聴数は、当該動画が投稿されたすべての Post を横断して集計された値を表示します。つまり、/totals で提供され、X の UI に表示されるメトリクスには、その動画が別の Post で Retweet または再投稿された各インスタンスからの視聴数が合算されています。
  • /28hour および /historical の Engagement API エンドポイントで提供される動画視聴数は、メトリクスを取得している特定の Post によって生成された視聴のみを含みます。   
1800日より前の Post に対する動画視聴数は提供していませんのでご注意ください。代わりに、1800日より前の Post を列挙したオブジェクトを返します。リクエストした Post に関するその他のすべてのメトリクスは、別のオブジェクトで引き続き受け取ることができます。以下はレスポンスの例です: 
{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "grouping name": {
    "479311209565413376": {
      "favorites": "69",
      "impressions": "1692",
      "retweets": "142",
      "video_views": "0"
    },
    "477139122520219648": {
      "favorites": "10",
      "impressions": "1023",
      "retweets": "6",
      "video_views": "0"
    },
    "1397568983931392004": {
      "favorites": "268",
      "impressions": "26803",
      "retweets": "56",
      "video_views": "17902"
    }
  }
}
Media Views メトリックは、/28hour および /historical エンドポイントで、所有する Post に対してのみ利用できます。

​
Engagement API のグルーピング

グルーピングを使うと、返されるエンゲージメント指標を任意の方法で整理できます。1 回のリクエストに含められるグルーピングは最大 3 つです。指標は次の値の 1 つ以上でグループ化できます: 3 つすべてのエンドポイントでサポート:
  • tweet.id
  • engagement.type  
/28hr と /historical は時系列指標を提供できるため、次もサポート:
  • engagement.day
  • engagement.hour
グルーピングは指定順に適用されるため、group_by の値の順序を変えることで、希望する結果の形式に変更できます。group_by の値が 4 つ含まれるグルーピングは、次の 2 つの形式のいずれかでのみサポートされます: 
"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.hour"
  ]
または 
"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.hour"
]
たとえば、メトリクスの総計を算出したい場合は、リクエストに次の「groupings」指定を含めてください（リクエストの組み立て方法の詳細は API Reference ページをご覧ください）: 
{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "Grand Totals": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}
このグループ化を指定すると、Engagement API の JSON レスポンスには、メトリクス種別ごとの総計を格納したルートレベルの “Grand Totals” 属性が含まれます。 
{
  "合計": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}
単一のPostのメトリクスをPostのidでグループ化し、4時間の時系列として生成するには、次のGrouping仕様をリクエストに含めます。 
{
  "start": "2016-02-10T17:00:00Z",
  "end": "2016-02-10T21:00:00Z",
  "tweet_ids": [
    "697506383516729344"
  ],
  "engagement_types": [
    "impressions",
    "engagements"
  ],
  "groupings": {
    "Tweets_MetricType_TimeSeries": {
      "group_by": [
        "tweet.id",
        "engagement.type",
        "engagement.hour"
      ]
    }
  }
}
このグルーピングを使用すると、Engagement API の JSON レスポンスには、Post の ID、メトリクス種別、そして対応する毎時の時系列で順に区分されたメトリクスを格納する、ルートレベルの “Tweets_MetricType_TimeSeries” 属性が含まれます。 
{
  "Tweets_MetricType_TimeSeries": {
    "697506383516729344": {
      "impressions": {
        "2016-02-10": {
          "17": "551",
          "18": "412",
          "19": "371",
          "20": "280"
        }
      },
      "engagements": {
        "2016-02-10": {
          "17": "8",
          "18": "6",
          "19": "3",
          "20": "0"
        }
      }
    }
  }
}

​
よくあるご質問

エンタープライズ

​
Engagement API

Engagement API へのアクセスは、エンタープライズのサブスクリプションで提供しています。営業チームへの連絡はこのフォームからご送信ください。
ご契約に、Engagement API で使用できるユニークな handle 数の上限が含まれている場合があります。X の内部システムは、Engagement API でクエリされた Post を所有する認証済みユーザー数を追跡します。お客様側でも、このユニーク数をクライアント側で管理してください。現在、Engagement API の @handle 利用状況を確認するための Usage API や UI はありません。契約数を超える @handle がリクエストされた場合でも、システムがブロックすることはありません。請求月末に、クエリされたユニークな @handle の数が契約数量と照合され、契約条件に従って超過分が課金されます。
現在、Engagement API の @handle 利用状況を確認するための Usage API や UI はありません。契約数を超える @handle がリクエストされた場合でも、システムがブロックすることはありません。請求月末に、クエリされたユニークな @handle の数が契約数量と照合され、契約条件に従って超過分が課金されます。ペイロードで返される engagements メタデータフィールドが、各種エンゲージメント指標の合計と一致しません。なぜですか？これは想定どおりの挙動です。engagements メタデータフィールドは、API が返す個々のエンゲージメント指標の合計と常に一致するとは限りません。これは、engagements メタデータフィールドに、ペイロード内で個別の指標として分解されていない追加のエンゲージメントが含まれる場合があるためです。言い換えると、各種エンゲージメント指標を合算しても、ペイロードで返される engagements 指標フィールドの値と一致しない場合があります。engagements メタデータフィールドは、Post 上で行われたあらゆるクリックやインタラクションと考えることができます。  ペイロードレスポンスの url_clicks フィールドが数値を返していますが、該当の Post には URL がありません。どうしてですか？ハッシュタグのように（別ページへのリンクを生成する）要素を含む Post の場合、ユーザーがそれをクリックすると URL クリックとして計上されることがあるためです。  
特定の Post のエンゲージメントデータを取得できない理由はいくつか考えられます。例えば、次のような場合です。
  • リクエストした Post ID が、第三者に代わってデータを取得するために使用している認証トークンに基づいて利用できない。
  • /totals エンドポイントに関するリクエストで、対象の Post ID が過去90日以内ではなく、そのためインプレッションやエンゲージメント指標の返却対象外である。
  • リクエストした Post ID がすでに利用できなくなっている（削除された、または他の理由で公開されなくなっていることを示すのが一般的）。
上記のいずれの場合にも受け取る可能性が高いエラーメッセージをご確認ください。
Engagement API へのリクエスト時に、レスポンスヘッダーで返される x-per-minute-limit と x-per-minute-remaining の情報を使用して消費状況を監視できます。x-per-minute-limit は許容量を、x-per-minute-remaining は残りのコール回数を示します。

​
エラーのトラブルシューティングガイド

Engagement API の認証に関するガイドラインを必ず確認してください。
[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]
/totals エンドポイントでの認証時には、access token や secret を使用しないでください。これらのトークンを含めた状態で、当該トークンに関連付けられていない Post のコンテンツを取得しようとすると、次のようなエラーが発生する可能性があります:
[
    Forbidden to access tweets: 1054424731825229824;
]

​
まだお探しの情報が見つかりませんか？

技術サポートまでお問い合わせください。迅速にご対応いたします。

​
API リファレンス

​
POST insights/engagement

​
メソッド

メソッド説明
POST /insights/engagement/totals複数の Tweet の合計インプレッション数とエンゲージメント数を取得します。
POST /insights/engagement/historical2014年9月1日までさかのぼり、最長4週間の期間における複数の Tweet のインプレッション数とエンゲージメント数を取得します。
POST /insights/engagement/28hr過去28時間における複数の Tweet のインプレッション数とエンゲージメント数を取得します。

​
認証

Engagement API の利用には HTTPS が必須で、User Context と Application-Only OAuth の両方をサポートしています。Engagement API への大半のリクエストには 3-Legged OAuth（User Context の一種）が必要です。これは、Twitter のアカウントマネージャーにより Engagement API へのアクセス用として登録・承認されたアプリのコンシューマーキーとシークレットに加え、Tweet の所有者のアクセストークンとアクセストークンシークレットを用いてエンドポイントを呼び出すことを意味します。次のリクエストではこの種類の OAuth が必要です:
  • 所有する Tweet に限定される Impressions および Engagements のメトリクスタイプを取得するための /totals への任意のリクエスト
  • /28hr への任意のリクエスト
  • /historical への任意のリクエスト
Engagement API への一部のリクエストは Application-Only OAuth でも実行できます。この場合、コンシューマーキーとシークレット、またはベアラートークンのみを提供すれば十分です。次のリクエストはこの種類の OAuth で実行できます:
  • 任意の Tweet を対象に取得できる Favorites、Replies、Retweets、または Video Views の各メトリクスタイプを取得するための /totals への任意のリクエスト
いずれのリクエストでも、developer.x.com のアプリ管理コンソールで Twitter アプリと対応する API キーを設定する必要があります。 ご注意ください — 既存の Twitter apps は、developer.x.com 上で Twitter アカウントにログインしている場合、Twitter app dashboard から表示・編集できます。 アプリの設定が完了したら、Engagement API へのリクエストを行えるように、アプリの ID はアカウント担当者の承認を受ける必要があります。アクセストークンは「現在のユーザー」を表すために使用し、別ユーザーの代わりに行うリクエストは有効なトークンで署名する必要があります。OAuth の署名ベース文字列を準備する前に、URL および POST ボディ内で予約文字をエンコードしていることを確認してください。 OAuth の利用開始方法の詳細は、以下のリンクをご参照ください:

​
POST /insights/engagement/totals

totals エンドポイントでは、一度に最大250件の Tweet の集合に対し、現在の総インプレッション数と総エンゲージメント数を取得できます。
リクエストメソッドHTTP POST
URLhttps://data-api.x.com/insights/engagement/totals
コンテンツの種類application/json
圧縮Gzip。Gzip 圧縮でリクエストするには、接続時のリクエストに Accept-Encoding ヘッダーを付与してください。
ヘッダーは次のようになります。

Accept-Encoding: gzip
Post の形式リクエストは、本文にTweet IDのコレクションと目的のグルーピングを含むJSONオブジェクトを持つPOSTリクエストとして送信できます。POSTは次の形式の配列としてフォーマットされます。tweets、エンゲージメント、およびgroupingsオブジェクト。各リクエストには最大で250件のTweet IDを含めることができます。

POST リクエストボディの例は次のとおりです：


{
“Tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”、
“Tweet ID 3”
],
“エンゲージメント_型”: [
“表示回数”、
“エンゲージメント数」、
“ブックマーク”、
“引用文_Tweets”
],
“グループ化”:{
“グルーピング名”：{
“グループ_提供元”: [
“tweet.id”、
“engagement.type”
]
}
}
}
Tweet の IDエンゲージメントデータの取得対象となる Tweet の Tweet ID を含む配列です。認証中の @handle が作成した Tweet に対してのみ data をリクエストできます。1 回のリクエストに含められるのは最大 250 件の Tweet までで、Tweet ID は文字列として指定する必要があります。
エンゲージメントの種別クエリ対象のエンゲージメント指標の種類を含む配列。Totals エンドポイントでは、以下のエンゲージメントタイプのみがサポートされています：インプレッション、エンゲージメント,favorites,retweets、quote_tweets、replies、video_views。
The/totalsこのエンドポイントは取得に対応していますimpressionsおよびエンゲージメント過去90日以内に作成されたTweetについて、かつfavorites、retweets、quote_tweets、返信、およびvideo_views任意のTweetに対して。
グループ化Engagement API の結果は、ニーズに最適な形で返せるよう、複数のグループに分けて取得できます。1 回のリクエストで指定できるグループは最大 3 つです。

各グループ化ごとに、アプリ内でこのグループ化タイプを参照しやすくするためのカスタム名を定義できます。

グルーピング名を定義したら、tweet.id および/または engagement.type でグループ化することを選択できますtweet.idおよび／またはengagement.type.

グルーピングは順番どおりに適用されるため、group_by の順序を変えることで、目的の結果フォーマットに変更できます_値ごとに。たとえば、Tweet ID と指標タイプでメトリクスを分けて表示するグループ化は次のようになります：


“グループ化”:{
“自分のグループ名”:{
“グループ_作成者:”: [
“Tweet.id”、
“engagement.type”
]
}
}
POST サイズ上限1回のリクエストで、最大250件のTweetのIDを指定できます。
応答形式JSON。リクエストヘッダーでレスポンス形式として JSON を指定してください。
レートリミットアクセスレベルに応じ、契約で定められたとおり、1分単位のレート制限が適用されます。
リクエスト例（公開メトリクス）curl —request POST
—urlhttps://data-api.x.com/insights/engagement/totals
—header’accept-encoding: gzip’
—header’Authorization: Bearer’
—header’Content-Type: application/json’
—data’{
“Tweet_ids”: [
“1070059276213702656”、“1021817816134156288”,“1067094924124872705”
],
“エンゲージメント_型”: [
“お気に入り”、“リツイート”、“返信”,“引用符_Tweets”、“動画_表示回数”
],
“グループ化”:{
“perTweetMetricsUnowned”:{
“グループ_作成者：”: [
“tweet.id”、
“engagement.type”
]
}
}
}
—verbose
—compressed
リクエストの例curl —request POST
—urlhttps://data-api.x.com/insights/engagement/totals
—header’accept-encoding: gzip’
—header’authorization: OAuth oauth_消費者_key=“アプリのコンシューマーキー”,oauth_nonce=“生成ノンス”,oauth_signature=“生成署名”,oauth_署名_method=“HMAC-SHA1”, OAuth_timestamp=“生成タイムスタンプ”,oauth_token=“認証済みユーザーのアクセストークン”, OAuth_version=“1.0”’
—header’content-type: application/json’
—data’{
“Tweet_ids”: [
“1060976163948904448”、“1045709644067471360”
],
“エンゲージメント_型”: [
“お気に入り”、“返信”、“リポスト”、“ビデオ_表示回数”、“インプレッション”、“エンゲージメント”
],
“グループ化”：{
“perTweetMetricsOwned”:{
“グループ_作成者:”: [
“tweet.id”、
“engagement.type”
]
}
}
}’
—verbose
—compressed
レスポンス例（公開メトリクス）{
“perTweetMetricsUnowned”:{
“1021817816134156288”：{
“お気に入り”:“530”、
“引用符_Tweets”:“79”,
“返信”:“147”、
“リポスト”：“323”、
“動画_表示回数”:“0”
},
“1067094924124872705”:{
“お気に入り”：“1360”、
“引用_Tweet”：“29”、
“返信”:“56”、
“リツイート”：“178”、
“動画_表示回数”:“5754512”
}、
“1070059276213702656”：{
“お気に入り”:“69”、
“引用文_Tweets”:“5”、
“返信”：“7”,
“リツイート数”:“26”、
“動画_表示回数”：“0”
}
}
}
応答例{
“perTweetMetricsOwned”:{
“1045709644067471360”:{
“エンゲージメント”:“2”、
“お気に入り”：“0”、
“インプレッション数”:“47”、
“返信”:“0”、
“リポスト”：“8”、
“引用句_Tweets”:“5”、
“動画_表示回数”:“0”
}、
“1060976163948904448”:{
“エンゲージメント数”:“4”、
“お気に入り”：“0”、
“インプレッション数”:“148”、
“返信”:“1”、
“リツイート”:“9”、
“引用符_Tweet”:“2”、
“ビデオ_表示数”:“0”
}
}
}
利用不可の Tweet ID利用できなくなった（例：削除された）Tweet ID を含むクエリでは、利用可能なすべての Tweet ID について適切なデータが返され、利用できない Tweet ID は unavailable_tweet_ids という配列で参照されます。unavailable_tweet_ids。例：

{
“開始”:“2015-11-17T22:00:00Z”,
“終了”:“2015-11-19T02:00:00Z”、
“利用できません_Tweet_ids”: [
“323456789”
],
“グループ1”:{
“423456789”:{
“ブックマーク”:“67”、
“返信”:“8”、
“リツイート”:“26”,
“引用_Tweets”:“2”
}
}
}

​
POST /insights/engagement/28hr

この 28 hour エンドポイントは、過去28時間における最大25件の Tweet のインプレッションおよびエンゲージメントを取得できます。さらに、サポート対象のすべての個別指標についてメトリクスをリクエストすることも可能です。サポートされている指標の一覧は Metric Availability を参照してください。
リクエストメソッドHTTP POST
URLhttps://data-api.x.com/insights/engagement/28hr
コンテンツタイプapplication/json
圧縮Gzip。Gzip圧縮を利用してリクエストするには、接続リクエストで Accept-Encoding ヘッダーを送信してください。
ヘッダーは次のようになります。

Accept-Encoding: gzip
Post の形式リクエストは、本文にTweetのIDコレクションと希望するグルーピングを含むJSONオブジェクトを持つPOSTリクエストとして送信できます。POSTは配列として、次の形式でフォーマットされます。tweets、エンゲージメント、ならびにgroupingsオブジェクト。各リクエストで指定できる Tweet ID の上限は 25 件です。

POST リクエストボディの例は次のとおりです：


{
“Tweet_ids”: [
“Tweet ID 1”、
“Tweet ID 2”、
“Tweet ID 3”
],
“エンゲージメント_型”: [
“インプレッション数”、
“エンゲージメント数”、
“url_クリック数”、
“詳細_拡張”
],
“グループ化”:{
“グルーピング名”:{
“グループ_作成者”: [
“tweet.id”、
“engagement.type”、
“engagement.hour”
]
}
}
}
Tweet の IDエンゲージメントデータを取得する対象の Tweet の Tweet ID を含む配列です。認証中の @handle が作成した Tweet に対してのみデータをリクエストできます。28 時間エンドポイントでは、1 回のリクエストで最大 25 件の Tweet に対応しており、Tweet ID は文字列として指定する必要があります。
エンゲージメントの種類照会するエンゲージメント指標の種類を指定する配列。

28時間のエンドポイントの場合、インプレッション、エンゲージメント、個々のエンゲージメントの種類はすべてサポート対象の指標です。サポートされているエンゲージメント指標の一覧はエンゲージメント・データ.
グループ化Engagement API の結果は、ニーズに最も適した形となるよう、異なるグループで返すことができます。1回のリクエストで指定できるグルーピングは最大3つです。

各グループ化ごとに、アプリケーション内でこのグループ化タイプを参照しやすくするためのカスタム名を定義できます。名前を定義したら、以下の値のうち1つ以上でグループ化できます:
tweet.id
engagement.type
engagement.day
engagement.hour
グループは順次評価されるため、group_by の並び順を変更すれば、求める結果の形式を切り替えられます_値ごと。例えば、Tweet ID とメトリックの種類で指標を分けて表示するグループ化の例は、次のようになります：

“グループ化”:{
“グループ名（自分用）”:{
“グループ_作成者”: [
“tweet.id”、
“engagement.type”、
“engagement.day”
]
}
}


group_by が 4 つあるグルーピングgroup_byitems は、次のいずれか 2 通りの順序で並んでいる場合にのみ有効です。4group_by単一のグループ内で、以下のいずれにも該当しない項目はエラーとなります。さらに、4group_byリクエストごとに許可されるアイテム数は items です。

“グループ_作成者：”: [
“tweet.id”、
“engagement.type”、
“engagement.day”、
“engagement.hour”
]

“グループ_作成者：”: [
“engagement.type”、
“tweet.id”、
“engagement.day”,
“engagement.hour”
]
POST サイズ制限1回のリクエストで最大25件のTweet IDを指定できます。
応答フォーマットJSON。レスポンス形式が JSON であることを、リクエストのヘッダーで指定してください。
レートリミットアクセス権限レベルに応じ、契約で定められたとおり、1分単位のレート制限が適用されます。
リクエストの例curl -X POST”https://data-api.x.com/insights/engagement/28hr”
-H’Accept-Encoding: gzip’
-H’認可 OAuth oauth_消費者_key=“アプリのコンシューマーキー”,oauth_nonce=“生成ノンス”,oauth_signature=“生成済み署名”,oauth_署名_method=“HMAC-SHA1”, OAuth_timestamp=“生成タイムスタンプ”,oauth_token=“認証済みユーザー用アクセス トークン”, OAuth_version=“1.0”’
-d’{
“Tweet_ids”: [
“123456789”
],
“エンゲージメント_型”: [
“インプレッション数”,
“エンゲージメント数”
],
“グループ化”:{
“時間単位の時系列”:{
“グループ_作成者”: [
“tweet.id”、
“engagement.type”、
“engagement.day”,
“engagement.hour”
]
}
}
}‘
応答例{
“開始”:“2015-09-14T17:00:00Z”,
“終了”:“2015-09-15T22:00:00Z”,
“時間単位タイムシリーズ”：{
“123456789”:{
“インプレッション数”:{
“2015-09-14”:{
“17”:“551”、
“18”:“412”、
“19”：“371”,
“20”:“280”、
“21”:“100”,
“22”:“19”,
“23”:“6”
}、
“2015年9月15日”:{
“00”:“5”,
“01”：“2”、
“02”:“7”,
“03”:“3”、
“04”:“1”,
“05”:“0”,
“06”:“0”、
“07”:“0”,
“08”:“0”,
“09”:“0”、
“10”:“0”,
“11”:“0”、
“12”:“0”,
“13”:“0”、
“14”:“0”,
“15”:“0”、
“16”:“0”,
“17”:“0”、
“18”:“0”,
“19”:“0”,
“20”:“0”,
“21”:“0”
}
}、
“エンゲージメント数”:{
“2015年9月14日”:{
“17”:“0”、
“18”:“0”,
“19”:“0”,
“20”:“0”、
“21”:“0”、
“22”:“0”、
“23”:“0”
},
“2015年9月15日”:{
“00”:“0”、
“01”:“0”、
“02”:“0”、
“03”：“0”、
“04”:“0”,
“05”:“0”、
“06”:“0”、
“07”:“0”、
“08”:“0”,
“09”:“0”,
“10”：“0”、
“11”:“0”,
“12”:“0”、
“13”:“0”,
“14”:“0”、
“15”:“0”、
“16”:“0”、
“17”：“0”,
“18”:“0”、
“19”:“0”,
“20”:“0”、
“21”:“0”
}
}
}
}
}
取得できない Tweet のID利用できなくなった（例：削除された）Tweet ID を含むクエリでは、利用可能なすべての Tweet ID については適切な data が返され、利用できない Tweet ID は unavailable_tweet_ids という配列で示されますunavailable_tweet_ids。例：

{
“開始”:“2015-11-17T22:00:00Z”,
“終了”：“2015-11-19T02:00:00Z”、
“利用できません_Tweet_ids”: [
“323456789”
],
“group1”:{
“423456789”:{
“お気に入り”：“67”、
“返信”:“8”、
“リポスト”: 26
}
}
}

​
POST /insights/engagement/historical

この履歴エンドポイントでは、最大25件のTweetのコレクションについて、最長4週間の任意の期間にわたるインプレッションとエンゲージメントを取得できます。現在、2014年9月1日より前のdataはAPIからリクエストできません。履歴エンドポイントでは、サポートされているすべての個別指標のメトリクスも取得できます。サポートされているメトリクスの一覧については、Metric Availabilityを参照してください。
リクエストメソッドHTTP POST
URLhttps://data-api.x.com/insights/engagement/historical
コンテンツの種類application/json
圧縮Gzip。Gzip 圧縮でリクエストするには、接続リクエストに Accept-Encoding ヘッダーを付与してください。
ヘッダーは次のようになります。

Accept-Encoding: gzip
POST のフォーマットリクエストは、本文にTweetのIDの集合と希望するグルーピングを含むJSONオブジェクトを持つPOSTリクエストとして送信できます。POSTは、次の形式の配列としてフォーマットされますtweets、エンゲージメント、およびgroupingsobject. 各リクエストで指定できる Tweet ID の最大数は 25 件です。各リクエストには、最長 4 週間のカスタムの開始日と終了日を指定できます。


{
“Tweet_ids”: [
“Tweet ID 1”、
“Tweet ID 2”、
“Tweet ID 3”
],
“エンゲージメント_型”: [
“インプレッション数”、
“エンゲージメント数”、
“URL_クリック数”、
“詳細_展開”
],
“グループ化”:{
“グループ名”:{
“グループ_作成:”: [
“Tweet.id”、
“engagement.type”、
“engagement.hour”
]
}
}
}
開始日と終了日開始日と終了日は、カスタム値で指定できますstartおよびendリクエストの一部として start と end の値を指定します。開始日と終了日は、期間が4週間を超えないように設定する必要があります。現時点で指定可能な最も古い開始日は2014年9月1日です。将来日を終了日に指定することはできません。開始日と終了日が指定されない場合、APIは直前の4週間をデフォルトとして使用します。

Engagement API から返される data の最小粒度は1時間です。Start または End の値がちょうど1時間の区切りに一致しないリクエストは、最も近い包含的な時刻（1時間単位）に丸められます。たとえば、次のリクエストでは”開始”:“2015-07-01T12:24:00Z”および”終了”：“2015-07-10T08:37:00Z”既定では～になります”開始”:“2015-07-01T12:00:00Z”、“終了”:“2015-07-10T09:00:00Z”.
Tweet の IDエンゲージメントデータを取得する対象のTweetのTweet IDを含む配列です。注意：リクエストできるのは、認証中の@handleが作成したTweetに限られます。4週間の履歴エンドポイントでは、1リクエストあたり最大25件のTweetをサポートし、Tweet IDは文字列として指定する必要があります。
エンゲージメントの種類クエリ対象のエンゲージメント指標の種類を含む配列。

4週間の履歴エンドポイントでは、インプレッション、エンゲージメント、すべての個別のエンゲージメント種別がサポート対象の指標です。サポートされているエンゲージメント指標の一覧については次を参照してくださいエンゲージメント・データ。

注: 2015年9月15日以前のクエリでは、現在、次の3つの指標がゼロで表示されます。favorites、返信、ならびにretweets。
グルーピングEngagement API の結果は、ニーズに最も適した形で複数のグループに分けて返すことができます。1 回のリクエストに含められるグルーピングは最大 3 つです。

各グループごとに、アプリ内でこのグループ種別を参照しやすくするためのカスタムのグループ名を定義できます。グループ名を定義した後は、次の値のうち1つ以上でグループ化を選択できます。
tweet.id
engagement.type
engagement.day
engagement.hour
グループ化は逐次的に適用されるため、グループの順序を変えることで、望ましい結果の形式に調整できます_値別。たとえば、Tweet ID とメトリックの種類ごとに指標を分けて表示するグループ化は、次のようになります。

“グループ化”：{
“自分のグループ名”:{
“グループ_作成者：”: [
“tweet.id”,
“engagement.type”、
“engagement.day”
]
}
}


4 つの group_by を含むグルーピングgroup_by``group_by アイテムは、次の2種類の順序のいずれかを使用している場合にのみ有効です。4つの group_by``group_by以下のいずれにも該当しない単一のグルーピング内の group_by 項目はエラーを返します。さらに、4group_byリクエストごとに許可される項目数は制限されます。

“グループ_作成者：”: [
“tweet.id”、
“engagement.type”、
“engagement.day”、
“engagement.hour”
]

“グループ_作成者：”: [
“engagement.type”、
“tweet.id”、
“engagement.day”、
“engagement.hour”
]
Post のサイズ上限1回のリクエストで指定できる Tweet ID の最大数は25件です。
応答形式JSON。レスポンスは JSON 形式になるよう、リクエストヘッダーで JSON を指定してください。
レートリミットアクセスレベルに応じて、契約で定められたとおり、1分あたりのレート制限が適用されます。
リクエストの例curl -X POST”https://data-api.x.com/insights/engagement/historical”
-H’Accept-Encoding: gzip’
-H’認可 OAuth oauth_消費者_key=“アプリ用のconsumer_key”,oauth_nonce=“生成ノンス”,oauth_signature=“生成された署名”,oauth_署名_method=“HMAC-SHA1”, OAuth_timestamp=“生成タイムスタンプ”,oauth_token=“認証済みユーザーのアクセス トークン”, OAuth_version=“1.0”’
-d’{
“開始”：“2015年8月1日”、
“終了”:“2015-08-15”,
“Tweet_ids”: [
“123456789”、
“223456789”、
“323456789”
],
“エンゲージメント_型”: [
“インプレッション数”、
“エンゲージメント数”,
“URL_クリック数”,
“詳細_拡張”
],
“グループ化”:{
“types-by-tweet-id”:{
“グループ_作成:”: [
“Tweet.id”,
“engagement.type”
]
}
}
}‘
サンプル応答{
“開始”:“2015-08-01T00:00:00Z”,
“終了”：“2015-08-15T00:00:00Z”、
“types-by-tweet-id”:{
“123456789”：{
“インプレッション”:“0”、
“エンゲージメント数”：“0”、
“URL_クリック数”：“0”、
“詳細_展開する”：“0”
},
“223456789”：{
“インプレッション数”:“788”、
“エンゲージメント数”:“134”、
“URL_クリック数”:“30”、
“詳細_拡張する”：“1323”
},
“323456789”：{
“インプレッション数”：“4”,
“エンゲージメント数”:“0”、
“URL_クリック数”：“2”,
“詳細_拡張”:“0”
}
}
}
利用できない Tweet のID削除などにより利用できなくなった Tweet ID を含むクエリでは、利用可能なすべての Tweet ID については適切なdataが返され、利用できない Tweet ID は unavailable_tweet_ids という配列で示されます。unavailable_tweet_ids。例えば：

{
“開始”:“2015-11-17T22:00:00Z”、
“終了”:“2015-11-19T02:27:50Z”、
“利用できません_Tweet_ids”: [
“323456789”
],
“グループ1”:{
“423456789”:{
“お気に入り”:“67”、
“返信”：“8”、
“リポスト”: 26
}
}
}

​
レスポンスコード

StatusTextDescription
200OKリクエストは成功しました。
400Bad Request一般的に、リクエストに無効な JSON が含まれている場合、または JSON ペイロードが送信されていない場合に返されます。
401Unauthorized無効な認証情報のため、HTTP 認証に失敗しました。OAuth のキーとトークンを確認してください。
404Not Foundリクエスト先の URL にリソースが見つかりません。URL が誤っている可能性があります。
429Too Many Requestsアプリが API リクエストの上限を超過しました。
500Internal Server ErrorGnip 側でエラーが発生しました。指数バックオフで再試行してください。
502Proxy ErrorGnip 側でエラーが発生しました。指数バックオフで再試行してください。
503Service UnavailableGnip 側でエラーが発生しました。指数バックオフで再試行してください。

​
エラーメッセージ

さまざまな状況で、Engagement API は状況に応じたエラーメッセージを返します。アプリケーションはそれらに対処できるよう準備しておく必要があります。以下の表は、一般的なエラーメッセージの例とその解釈方法を示します。多くの場合、Engagement API は、より詳しい情報を含む 200 OK レスポンスの一部として、特定のエラーメッセージとともに、利用可能な data の部分的な結果を返します。
エラーメッセージ説明
"errors":["Your account could not be authenticated. Reason: Access token not found"]リクエストの認証に関するエラーです。“Reason” にトラブルシューティングに役立つ情報が記載されます。解決できない場合は、“Reason” を含むエラー全文をサポートチーム宛てに送付してください。
"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]リクエストした Tweet の ID が利用できません。通常は削除された、または他の理由により公開されていないことを示します。
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]/totals エンドポイント向けにリクエストした Tweet の ID が 90 日以内ではないため、impressions や engagements のメトリクスは返されません。
"errors":["Forbidden to access tweets: *TWEET_IDS*"]第三者のために data を取得する目的で使用している認証トークンの権限に基づき、リクエストした Tweet の ID にはアクセスできません。