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

​
概要

Enterprise これは当社のマネージドアクセスレベル内でのみ利用可能な Enterprise API です。この API を利用するには、まず当社のエンタープライズ営業チームと連携してアカウントを設定する必要があります。 詳しくはこちら Engagement API は、Post のインプレッションおよびエンゲージメントに関する metrics へのアクセスを提供します。多くの metrics や endpoint では OAuth 1.0a ユーザーコンテキスト を用いた認証が必要ですが、公開の「お気に入り」「リツイート」「返信」「動画再生数」の metrics には、OAuth 2.0 Bearer Token と /totals endpoint を使用してアクセスできます。   注: 一部の X のウェブダッシュボードで報告される data と Engagement API で報告される data の間に差異が見られる場合があります。これは、ウェブダッシュボードが通常、選択した期間内に発生したエンゲージメントやインプレッションのみを表示するためです。たとえば、ウェブダッシュボードでは暦月の範囲内の Posts へのエンゲージメントのみを表示する一方、Engagement API では、その月の範囲を超えていても、要求した時間範囲内に含まれるエンゲージメントを表示する場合があります。これらの場合、Engagement API を正確な情報源として扱ってください。  

​
リクエスト endpoint

Engagement API には endpoint が3つあります。

​
現在の合計: [/totals]

  • リクエストは、指定した Posts のインプレッション合計およびエンゲージメント合計の metrics を返します
  • 対応する metrics は次に限定されます: Impressions、Engagements、Favorites、Replies、Retweets、Quote Tweets、Video Views
  • OAuth 1.0a ユーザーコンテキストを使用して、過去 90 日以内に作成された Posts の Impressions および Engagements metrics を取得可能
  • OAuth 2.0 Bearer Token を使用して、任意の Post の Favorites、Retweets、Quote Tweets、Replies および Video Views metrics を取得可能
  • 結果は、リクエスト時点のインプレッションおよびエンゲージメントの現在の合計に基づきます
  • ダッシュボードレポートの作成や、複数の @handle にまたがるエンゲージメント率の算出に最適
  • 1 回のリクエストで最大 250 件の Posts の metrics を要求可能  

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

  • リクエストでは、インプレッションの合計metrics、エンゲージメントの合計metrics、そして直近28時間に発生した個別エンゲージメントmetricsの内訳を返すことができます
  • データは Post ID 単位、または集計の時系列（日別・時間別）でグルーピングできます
  • 作成したばかりのコンテンツのパフォーマンス追跡に最適
  • 利用可能なすべてのmetricsに対応
  • 1回のリクエストで最大 25 Posts のmetrics取得に対応  

​
履歴: [/historical]

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

​
利用可能な metrics

以下の表では、Engagement API を通じてアクセスできる metrics の種類を説明します。 これらの metrics の詳細は、Interpreting the metrics ページをご参照ください。
MetricEndpointの可用性ユーザーコンテキストが必要説明
impressionsすべてはいPostが表示された回数のカウント。このmetricsは、過去90日以内に投稿されたPostに対してのみ利用可能です。
engagementsすべてはいユーザーがPostとやり取りした回数のカウント。このmetricsは、過去90日以内に投稿されたPostに対してのみ利用可能です。
favoritesすべてはい - /28hrs & /Historical

いいえ - /totals		Postがお気に入りに追加された回数のカウント。
retweetsすべてはい - /28hrs & /Historical

いいえ - /totals		Postがリツイートされた回数のカウント。
quote_tweets/totalsいいえ - /totalsPostがコメント付きでリツイートされた回数のカウント（引用ツイートとも呼ばれます）。
repliesすべてはい - /28hrs & /Historical

いいえ - /totals		Postに返信された回数のカウント。
video_viewsすべてはい - /28hrs & /Historical

いいえ - /totals		指定されたPost内の動画が少なくとも2秒間50%表示された回数のカウント。

動画再生数は、1800日以内のPostに対してのみ利用可能です。1800日より古いPostの動画再生数をリクエストしようとすると、リクエストした他のmetricsを含む別のオブジェクトと共に、レスポンス内に以下のオブジェクトが返されます：

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

注意： Xが所有・運営するプラットフォーム（モバイルアプリとウェブサイト）で表示される動画再生数metricsと、/28hrおよび/historicalのendpoint経由で受け取る数値との間に差異が生じる場合があります。

_ Xユーザーインターフェースと/totals endpointで表示される動画再生数は、指定された動画が投稿されたすべてのPost全体で集計された動画再生数を表示します。つまり、UIに表示されるmetricsには、動画がリツイートされたり別のPostで再投稿されたりしたすべてのインスタンスからの合計再生数が含まれます。このmetricsにはGIFの動画再生数は含まれません。
_ /28hrおよび/historical endpointによって提供される動画再生数には、metricsを取得している特定のPostによって生成された再生数のみが含まれます。このmetricsにはGIFの動画再生数は含まれません。
media_views/28hr /historicalはい動画、GIF、画像全体でカウントされたメディアのすべての再生数（自動再生とクリック）のカウント。
media_engagements

(旧称 Media Clicks)		/28hr /historicalはいPost内の画像や動画などのメディアがクリックされた回数のカウント。
url_clicks/28hr /historicalはいPost内のURLがクリックされた回数のカウント。
hashtag_clicks/28hr /historicalはいPost内のハッシュタグがクリックされた回数のカウント。
detail_expands/28hr /historicalはいPostがクリックされて詳細を表示した回数のカウント。
permalink_clicks/28hr /historicalはいPostへのパーマリンク（このPostに特化した個別のウェブページ）がクリックされた回数のカウント。
app_install_attempts/28hr /historicalはいPostからAppインストールイベントが発生した回数のカウント。
app_opens/28hr /historicalはいPostからAppオープンイベントが発生した回数のカウント。
email_tweet/28hr /historicalはいPostがメール経由で共有された回数のカウント。
user_follows/28hr /historicalはいこのPostからユーザー（Post作成者）がフォローされた回数のカウント。
user_profile_clicks/28hr /historicalはいこのPostからユーザー（Post作成者）のプロフィールがクリックされた回数のカウント。

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

グルーピングは、返却されるエンゲージメントのmetricsを任意に整理するための機能です。1回のリクエストで指定できるグルーピングは最大3つまでです。metricsは、次のいずれか、または複数の値でグループ化できます。 3つのすべてのendpointでサポート:
  • tweet.id
  • engagement.type  
/28hr と /historical は時系列のmetricsを提供できるため、次をサポート:
  • engagement.day
  • engagement.hour
グルーピングの詳細は、Guides セクション内の Engagement API Grouping ページをご覧ください。

​
ガイド

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

​
はじめに

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

​
Engagement API を統合する

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

​
OAuth での認証

OAuth はテクノロジー業界で広く使われている認証標準です。すでに OAuth（他の X API など）を利用している場合は、言語別の OAuth パッケージで複雑な処理を抽象化している可能性が高いでしょう。OAuth が初めての場合は、OAuth with the X API のページをご覧いただくか、https://oauth.net で詳しく学んでください。そのうえで、まずはご利用の開発言語向けの OAuth パッケージを選び、そこから始めることをおすすめします。これらのパッケージでは、一般的に、キーおよびトークンを設定し、HTTP オブジェクトを作成し、そのオブジェクトでリクエストを送る、という流れで認証します。 たとえば Ruby の場合、以下の擬似コードは、Ruby の gem「oauth」を使って OAuth 対応の App を構築し、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 endpoint で所有していない公開 Posts のエンゲージメント metrics を収集する場合、ユーザーの許可は不要で、アプリケーションのみ認証を使用できます。この場合は、認証に App のキーとシークレットのみを使用します。 OAuth では、ユーザーに紐づくトークンを用いて、アプリが「別のユーザーに代わって」API リクエストを行うこともできます。所有する Posts、つまりあなたがユーザートークンを保有しているユーザーが公開した Posts のエンゲージメント metrics を生成する場合は、ユーザーコンテキストでリクエストを行います。これは、App のキーとユーザー固有の access token の両方で認証することを意味します。これらのユーザー access token は通常、‘Sign-in with X’ のプロセスで提供されるか、ユーザーから直接取得します（ユーザーからトークンを直接取得する場合は、twurl を使用する必要がある点にご注意ください）。ユーザーがトークンを提供すると、それらは有効期限がなく、ユーザーがトークンをリセットしたりパスワードを変更したりしない限り、Engagement API でそのユーザーに代わってリクエストを行うために使用できます。その場合は新しいトークンを提供してもらう必要があります。 どの metrics にどの認証が必要かは、この表で確認できます。

​
Engagement API の endpoint を選ぶ

Engagement API には、次の 3 種類の endpoint があります。
  • Totals - 所有（‘owned’）/非所有（‘unowned’）の Post を対象に、選択された metrics の総計を返します。すべての Post で利用できる metrics もあれば、直近 90 日以内に公開された Post のみに提供されるものもあります。1 回のリクエストで最大 250 件の Post に対応します。
  • 28 hour - 直近 28 時間における ‘owned’ な Post のエンゲージメント metrics の時系列データを返します。1 回のリクエストで最大 25 件の Post に対応します。
  • Historical - 2014 年 9 月 1 日以降に投稿された ‘owned’ な Post を対象に、最大 4 週連続分のエンゲージメント metrics の時系列データを返します。1 回のリクエストで最大 25 件の Post に対応します。  
各 endpoint には固有の特性があります。3 つすべてを利用する場合でも、ユースケースに最適なものを選定する場合でも、それらの違いを理解しておくことが重要です。 以下では、いくつかの主要な概念を紹介し、3 つの endpoint を詳しく説明したうえで、各 endpoint に大まかに対応するサンプルのユースケースを示します。これらの情報が、3 つすべてを効率的に統合する際、または単一の endpoint の中から目的に最も適したものを選ぶ際の助けになれば幸いです。  

​
重要な概念

3つの Engagement API endpoint が提供する機能や、それらで取得できる data を理解するうえで、いくつか押さえておくべき重要な概念があります。  
インプレッションとエンゲージメントのmetrics
インプレッションは、特定のPostがXプラットフォーム上でオーガニックなcontextにおいて閲覧された回数を表します。PromotedまたはPaidのcontextで表示されたPostsによって生成されたインプレッションは含まれません。Engagement API以前は、Postのインプレッションは潜在的な閲覧数の指標にすぎませんでした。これは、投稿者のアカウントのフォロワー数と、そのコンテンツをリツイートしたアカウントのフォロワー数を基に算出されており、特定のユーザーが実際にはそのPostを見ていないという一般的な状況は考慮されていませんでした。 Engagement APIによって生成されるインプレッションのmetricsは、Postが表示のために実際にレンダリングされた回数を示す実測値です。あなたのアカウントのフォロワーがあなたのPostを見逃した場合、それはインプレッションとしてカウントされません。 Engagement APIは、提示されたPostに対してユーザーが取り得る個別のアクションを表す14種類の固有のエンゲージメントmetric typesに関するmetricsを提供します。これには、リツイート、like、返信、#hashtags、リンク、メディアといったエンティティのクリック、投稿者のフォロー、投稿者のプロフィールの閲覧が含まれます。これらすべての個別アクションは、単一のEngagements metricsに集約されます。
自社保有コンテンツと非保有コンテンツ（X）
Engagement では、自社保有の Posts と非保有の Posts を明確に区別します。自社保有の Posts とは、自分のアカウントから投稿された Posts、または Engagement の data をリクエストする権限を取得した Posts を指します。他の X API と同様に、他の X ユーザー／アカウントが、あなたがそのユーザーに代わって API リクエストを行えるようにする access tokens を共有することで、権限を取得します。これらのトークンを取得する一般的な方法としては、“Sign in with X” プロセスがあります。 /totals endpoint は、自社保有の Posts と非保有の Posts の両方に対するエンゲージメント data を提供します。非保有の Posts については、Post の表示で公開されているエンゲージメント metrics（いいね、リツイート、返信）をリクエストできます。これらの metrics について、Engagement API が提供する価値は、これらを自動化された方法で大規模に取得できる点にあります。自社保有の Posts については、/totals endpoint は Impression と（合計）Engagement の metrics も提供します。 /28hr および /historical endpoints は自社保有の Posts のみの metrics を提供します。つまり、これらの endpoints にリクエストする際にはユーザー context を渡す必要があります。
合計および時系列のエンゲージメントデータ
/totals endpoint は、その名称のとおり、エンゲージメントの種類ごとの総計のみを提供します。表示される数値は、その Post が投稿されて以降の最新の累計を表します。Post を投稿した直後に metrics を繰り返しリクエストすると、これらの合計はリクエストのたびに変動するのが一般的です。 /28hr および /historical endpoint は、総計と時系列データの両方を提供できます。時系列データをリクエストする場合、エンゲージメントの metrics は日次または時間単位の data にロールアップできます。   /28hr および /historical endpoint で時系列データをリクエストする方法については、engagement groupings に関するドキュメントをご参照ください。

​
endpointと利用例

上記の特性や差異を踏まえると、各endpointは一般的に異なる種類のユースケースに対応します。特定のユースケースに最適なendpointを選択できるよう、以下にユーザーの想定発話例と、それに最も適合するendpointを示します。
/totals
  • 一部のメトリクス種別（Impressions、Engagements、Favorites、リツイート、Quote Tweets、Replies、Video Views）にだけアクセスできれば十分です。
  • 自社所有のPostsに限らず、任意のPostの基本的なエンゲージメントdataにアクセスする必要があります。
  • 競合他社とのパフォーマンス比較を行いたい。
  • 自分が所有していないPostsを含むハッシュタグやキャンペーンの基本的なエンゲージメント統計を追跡したい。
  • 日別や時間別に分割されたdataは不要で、リクエスト時点の合計値だけが必要です。
  • レポートやダッシュボードに表示する単一のメトリクスが必要で、dataは保存したくありません。
  • ページ読み込み時にdataを表示したいので、リクエストしてレスポンスを受け取るだけで十分です。
  • 1日あたり数十万から数百万のPostsに対してdataをGETできるアクセスが必要です。  
/28hr
  • 17種類すべてのmetricsにアクセスする必要があります。
  • 直近28時間に投稿された最新のPostsのデータを表示したい。
  • 1日1回実行されるジョブで必要なデータを取得しており、直近1日分のデータだけ取得できればよい。
  • metricsを日または時間単位でブレークダウンしたい。
  • ダッシュボードで、時間単位の時系列アクティビティのブレークダウンを表示したい。
  • 1日に数十万件規模のPostsに対して高いアクセス権が必要です。
  • ストレージ機能があり、データは1日1回更新し、累積を保持できます。  
/historical
  • 17種類すべてのmetricsにアクセスする必要があります。
  • Postsの履歴データを、2014年9月までさかのぼって取得する必要があります。
  • キャンペーンを比較する詳細な履歴分析を表示したいです。
  • 日別または時間別に分解されたmetricsが必要です。
  • Engagement APIへの高いアクセスは不要で、1日に数百～数千件のPostsのdataを取得できれば十分です。

​
Engagement API の主な特性

  • RESTful API は JSON データを提供し、JSON 本文を伴う POST リクエストをサポートします。
  • リクエストの種類: クライアントアプリは次の種類のリクエストを行えます:
    • 総計エンゲージメント — HTTP POST リクエスト /totals endpoint
    • 直近28時間のエンゲージメント — HTTP POST リクエスト /28hr endpoint
    • 履歴エンゲージメント — HTTP POST リクエスト /historical endpoint
  • OAuth 認証:
    • OAuth 1.0 User Context: 3-legged OAuth を用いてあなたの App を承認したユーザーが所有する Posts について、利用可能なすべての metrics を取得できます。リクエスト時には、そのユーザーの Access Tokens を使用する必要があります。
    • OAuth 2.0 Bearer Token: 選択された metrics（リツイート、Quote Tweets、返信、いいね、動画再生数）は、公開されている任意の Post に対して利用可能です。
  • リクエストの metadata と構造: リクエストデータは、Post ID の配列、エンゲージメントタイプの配列、エンゲージメントのグルーピング構造で構成される JSON オブジェクトです。
  • リクエストあたりの Posts:
    • /totals endpoint: 250 Post ID
    • /28hr endpoint: 25 Post ID
    • /historical endpoint: 25 Post ID
  • エンゲージメント metrics の提供可否:
    • /totals — Post の投稿以降の合計値。インプレッションとエンゲージメントは直近90日以内に公開された Posts に対して利用可能で、リツイート、Quote Tweets、返信、いいね、動画再生数はすべての Posts に対して利用可能です。
    • /28hr — リクエスト時刻から直近28時間。
    • /historical — 2014年9月1日以降の任意の28日間。
  • Metric types: 各リクエストには Metric Types の配列が含まれます。提供可否は endpoint に依存し、/totals endpoint の場合は Posts がユーザー許可済みかどうかにも依存します。
    • /totals endpoint:
      • すべての Posts: いいね、リツイート、Quote Tweets、返信、動画再生数
      • OAuth 1.0a ユーザーコンテキストが必要: インプレッション、エンゲージメント、いいね、返信、リツイート
    • /28hr および /historical endpoints（Post 所有者の Access Token を用いた OAuth 1.0a ユーザーコンテキストが必要）: インプレッション、エンゲージメント、いいね、返信、リツイート、URL クリック、ハッシュタグクリック、詳細クリック、パーマリンククリック、メディアクリック、アプリインストール試行、アプリ起動、Post メール、動画再生数、メディア再生数
  • エンゲージメントのグルーピング: 各リクエストには Engagement Groupings の配列が含まれます。これらのグルーピングにより、返される metrics の整理方法をカスタマイズできます。各リクエストには最大3つのグルーピングを含められます。metrics は次の値で整理できます:
    • すべての endpoints: Post ID、エンゲージメントタイプ
    • /28hr および /historical endpoints: 追加のグルーピングとして次を指定した場合、時系列を提供します: エンゲージメント日、エンゲージメント時
  • 統合に関する想定事項: 貴チームには以下の責務があります。
    • Engagement API に HTTP リクエストを送信し、リクエストに含まれる Post ID のエンゲージメント metrics を返すクライアントアプリの作成と保守
  • 制限事項
  • 動画再生数は、1800日以内の Posts に対してのみ利用可能です。

​
Engagement API での認証

ご注意: API を利用開始する前に、X 側であなたの開発者用 App に対する Engagement API へのアクセスを有効化する必要があります。そのため、認証に使用予定の App ID をアカウントマネージャーまたはテクニカルサポートチームに共有してください。
Engagement API では、認証方法として OAuth 1.0a と OAuth 2.0 Bearer Token の 2 種類が利用できます。  OAuth 2.0 Bearer Token（「application-only」とも呼ばれます）は、公開されているエンゲージメントの metrics にアクセスできます。この認証方法は、/totals endpoint へのリクエスト時に、公開されている任意の Posts について、Favorites（別名 Likes）、リツイート、Quote Tweets、Replies、動画再生数の合計値を取得するために使用できます。  OAuth 1.0a（「user context」とも呼ばれます）は、ユーザーに代わってリクエストを実行し、当該ユーザーに属する非公開のエンゲージメントの metrics にアクセスできます。  この認証方法が必要となるのは次の場合です:
  • /28hr endpoint および /historical endpoint に送信されるすべてのリクエスト
  • 次のいずれかの非公開 metrics へのアクセス: 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 は、保護された Posts のエンゲージメントデータを取得できません。これらの Posts の所有者に代わって認証している場合でも同様です。これを試みると、メッセージ "Tweet ID(s) are unavailable" とともに 400 Bad Request エラーが返されます。 自分の X アカウント（つまり、開発者用 App を所有するアカウント）に代わってリクエストを送信する場合は、developer portal の開発者用 App の「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 上でのアクティビティのパフォーマンスを監視できる、非常に有用なインプレッションおよびエンゲージメントの metrics を提供します。私たちは継続的に、当社の data に基づくマーケティング判断を可能にすることに取り組んでおり、X 全体で metrics の整合性を高める最近の Engagement API の変更についてお知らせできることを嬉しく思います。  私たちは最近、Engagement API をモダナイズし、X のアナリティクスダッシュボード（analytics.x.com）で使用されているものと同一の metrics 集計手法を採用しました。新しい metrics の導入にあたり、破壊的な API 変更を最小限に抑えるべく慎重に進め、最初の変更セットを 2017 年 10 月 9 日にデプロイしました。これらの変更により、あなたやお客様が X 上でパフォーマンスを監視するあらゆる場所での一貫性が向上します。以下に変更の詳細をご確認ください:
MetricChange
engagements全体の engagements に合算される metrics を更新し、Post アナリティクスダッシュボードとの整合性を持たせました。engagements は「この Post と人々がやり取りした回数」を測定します。

動画や GIF などのメディアを含む Posts の場合、engagements metric には今後、メディアの再生数は含まれません。メディアの再生数は新しい metric である media_views で参照できます。
media_clicks*この metric は新しい “media_engagements” に置き換えられました。
video_views2018 年 7 月 6 日以降、この metric は「unowned」の Posts に対して /totals endpoint 経由で利用可能になりました。これは、App-only 認証を使用することで、すべての Posts の動画再生数にアクセスできることを意味します。 

1800 日以内の動画再生数のみをリクエストできます。1800 日より古い Post の動画再生数をリクエストしようとすると、次のレスポンスが返されます:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

注意: video_views は、少なくとも 2 秒間、動画の 50% が視認されているという MRC 標準に依拠する点で、media_views と異なります。

また、X の自社プラットフォーム（モバイル App およびウェブサイト）に表示される動画再生数と、/28hr および /historical endpoints を介して得られる数値との間に差異が生じる場合があります。

* X のユーザーインターフェースに表示され、/totals endpoint で提供される動画再生数は、該当する動画が投稿されたすべての Posts にわたって集計された値です。つまり、UI に表示される metric には、その動画がリツイートや別の Posts で再投稿されたすべてのインスタンスの合算視聴が含まれます。
* /28hr および /historical endpoints によって提供される動画再生数には、metrics を取得している特定の Post によって生成された再生のみが含まれます。
media_viewsこれは、動画、vines、gifs、画像にわたってカウントされる、メディアのすべての視聴（自動再生およびクリック）を含みます。

注意: 画像を含む Posts は、アナリティクスダッシュボードでは media_views metric を表示しませんが、Engagement API では返されます。
media_engagements*これは、動画、vines、gifs、画像にわたるメディアへのクリック数を含みます。この metric は media_clicks を置き換えるものです。
quote_tweets2020 年 7 月 7 日以降、この metric は「unowned」の Posts に対して /totals endpoint を通じて利用可能になりました。これは、App-only 認証を使用することで、すべての Posts の Quote Post 数にアクセスできることを意味します。

​
metrics の解釈

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

​
インプレッションとエンゲージメントのデータ

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

​
動画 metrics

X には、メディアのインプレッションを表す複数の metrics があります。1 つ目は video views の metric で、MRC の基準（動画の 50% が少なくとも 2 秒間視認されること）に準拠しています。2 つ目は Media Views で、動画・Vine・GIF・画像を対象に、自動再生およびクリックによるすべての視聴を合算します。 video views の metric は、/28hour および /historical endpoint で所有する Posts 向けに提供されるほか、/totals endpoint ではすべての非所有の Posts に対しても提供されます。  X のユーザーインターフェースでも同じ MRC 基準を用いていますが、X の自社プラットフォーム（モバイル App とウェブサイト）に表示される video views の値と、各種 Engagement API endpoint 経由で取得する数値に乖離が生じる場合がある点にご留意ください。
  • /totals endpoint および X のユーザーインターフェースで提供される video views は、当該動画が掲載されたすべての Posts にわたって集計された視聴数を表示します。つまり、/totals で提供され X の UI に表示される metric には、その動画がリツイートや別の Posts で再投稿された事例も含め、あらゆる掲載インスタンスの視聴数が合算されます。
  • /28hour および /historical の Engagement API endpoint で提供される video views には、metrics を取得している特定の Post で発生した視聴のみが含まれます。   
1800 日より前の Posts については video views を提供していません。その代わりに、1800 日より前の Posts を列挙したオブジェクトを返します。リクエストした Posts については、その他のすべての metrics を別オブジェクトで引き続き受け取れます。以下はレスポンス例です: 
{
  "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 の endpoint を持つ自社所有の Posts に対してのみ利用できます。

​
Engagement API のグルーピング

グルーピングを使用すると、返されるエンゲージメント metrics を任意の方法で整理できます。1 回のリクエストに含められるグルーピングは最大 3 つです。metrics は次の値の 1 つ以上でグループ化できます: 3 つすべての endpoint がサポート:
  • tweet.id
  • engagement.type  
/28hr と /historical は時系列の metrics を提供できるため、以下もサポート:
  • 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 レスポンスに、metrics の種類ごとの総計を含むルートレベルの “Grand Totals” 属性が追加されます。 
{
  "Grand Totals": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}
単一のPostに対して、Post IDごとにグループ化した4時間の時系列のmetricsを生成するには、以下の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 レスポンスには、ルートレベルの “Tweets_MetricType_TimeSeries” 属性が含まれ、Post ID、次にメトリックの種類、さらに対応する時間単位の時系列に分解された metrics が格納されます。 
{
  "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"
        }
      }
    }
  }
}

​
よくあるご質問

Enterprise

​
Engagement API

Engagement API へのアクセスは Enterprise サブスクリプションを通じて提供されます。営業チームへの連絡をご希望の方は、こちらのフォームにご記入ください。
契約に Engagement API と併用できるユニークなハンドル数の上限が含まれている場合、X の内部システムは Engagement API でクエリされた Post を所有する認証済みユーザーの数を追跡します。お客様側でもこのユニーク数をクライアント側で管理してください。現在、Engagement API の @handle 利用状況を確認するための使用状況 API や UI はありません。契約より多くの @handle がリクエストされた場合でも、システムが超過をブロックすることはありません。請求月末に、クエリされたユニークな @handle の数が契約数量と比較され、契約条件に従って超過料金が請求されます。
現在、Engagement API の @handle 利用状況を確認するための使用状況 API や UI はありません。契約より多くの @handle がリクエストされた場合でも、システムが超過をブロックすることはありません。請求月末に、クエリされたユニークな @handle の数が契約数量と比較され、契約条件に従って超過料金が請求されます。ペイロードで返される engagements metadata フィールドが、各種エンゲージメント metrics の合計と一致しません。なぜですか？これは想定どおりの動作です。engagements metadata フィールドは、API によって返される個別のエンゲージメント metrics の合計と必ずしも一致しない場合があります。これは、engagements metadata フィールドに、ペイロードで個別の metrics として内訳が提供されない追加のエンゲージメントが含まれる場合があるためです。言い換えると、さまざまなエンゲージメント metrics の合計を足し合わせても、ペイロードで返される engagements metric フィールドに表示される値と一致しないことがあります。engagements metadata フィールドは、Post 上で行われたあらゆるクリックやインタラクションと考えることができます。  ペイロード応答内の url_clicks フィールドが数値を返していますが、対象の Post には URL がありません。なぜですか？ハッシュタグなど（別ページへのリンクを生成する要素）を含む Post が、ユーザーにクリックされると URL クリックとしてカウントされる場合があるためです。  
特定の Post のエンゲージメントデータを取得できない理由はいくつかあります。例として、次のようなものがあります。
  • 代理でデータを取得するために使用している認証トークンに基づき、要求した Post ID が利用できない。
  • /totals endpoint に特有の、要求した Post ID が 90 日以内ではなく、そのため impressions やエンゲージメント metrics を返す対象外となっている。
  • 要求した 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 endpoint で認証を試みる際は、access token や secret を使用しないでください。これらのトークンを含めたうえで、当該トークンに関連付けられていない Post のコンテンツを取得しようとすると、次のようなエラーが発生する可能性があります。
[
    Forbidden to access tweets: 1054424731825229824;
]

​
お探しの内容がまだ見つかりませんか？

技術サポートまでお問い合わせください。速やかにご返信いたします。

​
API リファレンス

​
POST insights/engagement

​
メソッド

Method説明
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 へのアクセスとして登録・承認された App の consumer key と secret に加えて、Tweet の所有者の access token と access token secret を使用して endpoint を呼び出すことを意味します。次のリクエストではこの種類の OAuth が必要です：
  • 所有する Tweets に限定される Impressions および Engagements の指標タイプを取得するための /totals への任意のリクエスト
  • /28hr への任意のリクエスト
  • /historical への任意のリクエスト
Engagement API への一部のリクエストは Application-Only OAuth を使用して実行できます。これは、consumer key と secret、または Bearer Token を用意するだけでよいことを意味します。次のリクエストはこの種類の OAuth で実行できます：
  • 任意の Tweet に対して取得可能な Favorites、Replies、リツイート、または Video Views の指標タイプを取得するための /totals への任意のリクエスト
いずれのリクエストでも、developer.x.com にある App 管理コンソールで Twitter の App と対応する API Key を設定する必要があります。 注意：developer.x.com で Twitter アカウントにログインしている場合、既存の Twitter apps を Twitter app dashboard から表示および編集できます。 App を設定したら、Engagement API へリクエストを行うために、その app ID はアカウント担当者の承認を受ける必要があります。Access Tokens は「現在のユーザー」を表すために使用され、別のユーザーに代わって行うリクエストは有効なトークンで署名する必要があります。OAuth の署名ベース文字列を作成する前に、URL および POST ボディ内で予約文字を適切にエンコードしていることを確認してください。 OAuth の利用開始方法の詳細は、次のリンクをご覧ください：

​
POST /insights/engagement/totals

totals endpoint は、一度に最大250件の tweets の現在の合計インプレッション数とエンゲージメント数を取得できます。
リクエストメソッド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、engagements、groupingsオブジェクトを含む配列として形式化されます。各リクエストには最大250個のTweet IDを含めることができます。

POSTボディの例は次のようになります：


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“favorites”,
“quote_tweets”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
Tweet IDエンゲージメントデータを照会するTweetのTweet IDを含む配列。認証する@handleによって作成されたTweetのデータのみリクエストできることにご注意ください。リクエストごとに最大250個のTweetを含めることができ、Tweet IDは文字列として表現する必要があります。
エンゲージメントタイプ照会するエンゲージメントmetricsのタイプを含む配列。Totals endpointは次のエンゲージメントタイプのみをサポートします：impressions、engagements、favorites、retweets、quote_tweets、replies、video_views。
/totals endpointは、過去90日以内に作成されたTweetのimpressionsとengagements、および任意のTweetのfavorites、retweets、quote_tweets、replies、video_viewsを取得する機能をサポートします。
グループ化Engagement APIからの結果は、ニーズに最適な異なるグループで返すことができます。リクエストごとに最大3つのグループ化を含めることができます。

各グループ化について、アプリケーションでこのグループ化タイプを参照しやすくするために、カスタムグループ化名を定義できます。

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

グループ化は順次実行されるため、group_by値の順序を変更することで希望する結果形式を変更できます。Tweet IDとmetricsタイプで分離されたmetricsを表示するグループ化の例は次のようになります：


“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
POSTサイズ制限一度に最大250個のTweet IDに対してリクエストを行うことができます。
レスポンス形式JSON。リクエストのヘッダーはレスポンスのJSON形式を指定する必要があります。
レートリミット契約で指定されたアクセスレベルに応じて、分単位でレートリミットが適用されます。
リクエスト例（パブリックmetrics）curl —request POST
—url https://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”
],
“engagement_types”: [
“favorites”,“retweets”,“replies”,“quote_tweets”,“video_views”
],
“groupings”: {
“perTweetMetricsUnowned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
—verbose
—compressed
リクエスト例curl —request POST
—url https://data-api.x.com/insights/engagement/totals
—header ‘accept-encoding: gzip’
—header ‘authorization: OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
—header ‘content-type: application/json’
—data ’{
“tweet_ids”: [
“1060976163948904448”,“1045709644067471360”
],
“engagement_types”: [
“favorites”,“replies”,“retweets”,“video_views”,“impressions”,“engagements”
],
“groupings”: {
“perTweetMetricsOwned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}’
—verbose
—compressed
レスポンス例（パブリックmetrics）{
“perTweetMetricsUnowned”: {
“1021817816134156288”: {
“favorites”: “530”,
“quote_tweets”: “79”,
“replies”: “147”,
“retweets”: “323”,
“video_views”: “0”
},
“1067094924124872705”: {
“favorites”: “1360”,
“quote_tweets”: “29”,
“replies”: “56”,
“retweets”: “178”,
“video_views”: “5754512”
},
“1070059276213702656”: {
“favorites”: “69”,
“quote_tweets”: “5”,
“replies”: “7”,
“retweets”: “26”,
“video_views”: “0”
}
}
}
レスポンス例{
“perTweetMetricsOwned”: {
“1045709644067471360”: {
“engagements”: “2”,
“favorites”: “0”,
“impressions”: “47”,
“replies”: “0”,
“retweets”: “8”,
“quote_tweets”: “5”,
“video_views”: “0”
},
“1060976163948904448”: {
“engagements”: “4”,
“favorites”: “0”,
“impressions”: “148”,
“replies”: “1”,
“retweets”: “9”,
“quote_tweets”: “2”,
“video_views”: “0”
}
}
}
利用不可能なTweet ID利用不可能になったTweet ID（削除されたものなど）を含むクエリの場合、利用可能なすべてのTweet IDに対して適切なデータが返され、利用不可能なTweet IDはunavailable_tweet_idsという配列で参照されます。例：

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: “26”,
“quote_tweets”: “2”
}
}
}

​
POST /insights/engagement/28hr

この28時間のendpointは、過去28時間にわたり最大25件のTweetについて、impressionsとengagementsを取得できます。また、サポートされている各個別metricsの取得リクエストにも対応しています。サポート対象のmetricsの全一覧は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、engagements、およびgroupingsオブジェクトを含む配列として形式化されます。各リクエストには最大25個のTweet IDを含めることができます。

POSTボディの例は次のようになります：


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
Tweet IDエンゲージメントデータを照会するTweetのTweet IDを含む配列。認証する@handleによって作成されたTweetのデータのみリクエストできることにご注意ください。28時間endpointは1リクエストあたり最大25個のTweetをサポートし、Tweet IDは文字列として表現する必要があります。
エンゲージメントタイプ照会するエンゲージメントmetricsのタイプの配列。

28時間endpointでは、impressions、engagements、およびすべての個別エンゲージメントタイプがサポートされるmetricsです。サポートされるエンゲージメントmetricsの完全なリストについては、エンゲージメントデータを参照してください。
グループ化Engagement APIからの結果は、ニーズに最適な異なるグループで返すことができます。1リクエストあたり最大3つのグループ化を含めることができます。

各グループ化について、アプリケーションでこのグループ化タイプを参照しやすくするために、カスタムグループ化名を定義できます。グループ化名を定義したら、次の値の1つ以上でグループ化することを選択できます：
tweet.id
engagement.type
engagement.day
engagement.hour
グループ化は順次実行されるため、group_by値の順序を変更することで希望する結果形式を変更できます。Tweet ID、metricsタイプ別にmetricsを分離して表示するグループ化の例は次のようになります：

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


4つのgroup_by項目を持つグループ化は、次の2つの順序のいずれかを使用する場合のみ有効です。次のいずれでもない単一グループ化で4つのgroup_by項目を持つリクエストはエラーを返します。さらに、4つのgroup_by項目を持つグループ化は1リクエストあたり1つのみ許可されます。

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
POSTサイズ制限リクエストは一度に最大25個のTweet IDに対して行うことができます。
レスポンス形式JSON。リクエストのヘッダーはレスポンスのJSON形式を指定する必要があります。
レートリミットアクセスレベルに応じた契約で指定されているとおり、分単位でレートリミットが適用されます。
リクエスト例curl -X POST “https://data-api.x.com/insights/engagement/28hr”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“tweet_ids”: [
“123456789”
],
“engagement_types”: [
“impressions”,
“engagements”
],
“groupings”: {
“hourly-time-series”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]
}
}
}‘
レスポンス例{
“start”: “2015-09-14T17:00:00Z”,
“end”: “2015-09-15T22:00:00Z”,
“hourly-time-series”: {
“123456789”: {
“impressions”: {
“2015-09-14”: {
“17”: “551”,
“18”: “412”,
“19”: “371”,
“20”: “280”,
“21”: “100”,
“22”: “19”,
“23”: “6”
},
“2015-09-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”
}
},
“engagements”: {
“2015-09-14”: {
“17”: “0”,
“18”: “0”,
“19”: “0”,
“20”: “0”,
“21”: “0”,
“22”: “0”,
“23”: “0”
},
“2015-09-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 IDTweet IDが利用不可能になっている（削除されているなど）クエリについては、利用可能なすべてのTweet IDに対して適切なデータが返され、利用不可能なTweet IDはunavailable_tweet_idsという配列で参照されます。例：

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
POST /insights/engagement/historical

この historical endpoint は、最大 25 件の Tweets で構成されるコレクションについて、最長 4 週間の任意の期間におけるインプレッションおよびエンゲージメントを取得できます。現在、2014 年 9 月 1 日より前の data は API からリクエストできません。historical endpoint では、サポート対象のすべての個別 metrics をリクエストすることも可能です。サポートされている metrics の全一覧は 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、engagements、およびgroupingsオブジェクトを含む配列として形式化されます。各リクエストには最大25個のTweet IDを含めることができます。各リクエストは、最大4週間の期間でカスタムの開始日と終了日を指定できます。


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
開始日と終了日リクエストの一部としてstartとendの値でカスタムの開始日と終了日を指定できます。期間が4週間を超えない開始日と終了日を指定する必要があります。現時点で可能な最も古い開始日は2014年9月1日です。将来の終了日はサポートされていません。開始日と終了日が指定されていない場合、APIは直前の4週間をデフォルトとします。

Engagement APIからデータを返すことができる最小の粒度は時間単位です。時間境界に直接該当しない開始値または終了値でリクエストが行われた場合、リクエストは最も近い包括的な時間にデフォルトされます。例えば、“start”:“2015-07-01T12:24:00Z”と”end”:“2015-07-10T08:37:00Z”のリクエストは、“start”:“2015-07-01T12:00:00Z”、“end”:“2015-07-10T09:00:00Z”にデフォルトされます。
Tweet IDエンゲージメントデータを照会するTweetのTweet IDを含む配列。認証する@handleによって作成されたTweetのデータのみをリクエストできることにご注意ください。4週間の履歴endpointは、リクエストあたり最大25個のTweetをサポートし、Tweet IDは文字列として表現する必要があります。
エンゲージメントタイプ照会するエンゲージメントmetricsのタイプを含む配列。

4週間の履歴endpointでは、impressions、engagements、およびすべての個別エンゲージメントタイプがサポートされているmetricsです。サポートされているエンゲージメントmetricsの完全なリストについては、エンゲージメントデータを参照してください。

**注意：**現在、2015年9月15日より前に行われたクエリでゼロとして表示される3つのmetricsがあります：favorites、replies、およびretweets。
グループ化Engagement APIからの結果は、ニーズに最適な異なるグループで返すことができます。リクエストあたり最大3つのグループ化を含めることができます。

各グループ化について、アプリケーションでこのグループ化タイプを参照しやすくするために、カスタムグループ化名を定義できます。グループ化名を定義したら、以下の値の1つ以上でグループ化することを選択できます：
tweet.id
engagement.type
engagement.day
engagement.hour
グループ化は順次実行されるため、group_by値の順序を変更することで希望する結果形式を変更できます。Tweet ID、metricsタイプ別に分離されたmetricsを表示するグループ化の例は以下のようになります：

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


4つのgroup_by項目を持つグループ化は、以下の2つの順序のいずれかを使用する場合にのみ有効です。以下のいずれでもない単一のグループ化で4つのgroup_by項目を持つリクエストはエラーを返します。さらに、4つのgroup_by項目を持つグループ化は、リクエストあたり1つのみ許可されます。

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
POSTサイズ制限リクエストは一度に最大25個のTweet IDに対して行うことができます。
レスポンス形式JSON。リクエストのヘッダーは、レスポンスのJSON形式を指定する必要があります。
レートリミットアクセスレベルに応じた契約で指定されているとおり、分単位でレートリミットが適用されます。
リクエスト例curl -XPOST “https://data-api.x.com/insights/engagement/historical”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“start”: “2015-08-01”,
“end”: “2015-08-15”,
“tweet_ids”: [
“123456789”,
“223456789”,
“323456789”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“types-by-tweet-id”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}‘
レスポンス例{
“start”: “2015-08-01T00:00:00Z”,
“end”: “2015-08-15T00:00:00Z”,
“types-by-tweet-id”: {
“123456789”: {
“impressions”: “0”,
“engagements”: “0”,
“url_clicks”: “0”,
“detail_expands”: “0”
},
“223456789”: {
“impressions”: “788”,
“engagements”: “134”,
“url_clicks”: “30”,
“detail_expands”: “1323”
},
“323456789”: {
“impressions”: “4”,
“engagements”: “0”,
“url_clicks”: “2”,
“detail_expands”: “0”
}
}
}
利用不可能なTweet ID利用不可能になったTweet ID（削除されたものなど）を含むクエリの場合、利用可能なすべてのTweet IDについて適切なデータが返され、利用不可能なTweet IDはunavailable_tweet_idsという配列で参照されます。例：

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:27:50Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
レスポンスコード

ステータステキスト説明
200OKリクエストは正常に処理されました。
400Bad Request一般的に、リクエストに無効な JSON が含まれている場合、または JSON ペイロードが送信されていない場合に返されます。
401Unauthorized無効な認証情報により HTTP 認証に失敗しました。OAuth のキーおよびトークンを確認してください。
404Not Foundリクエスト先の URL にリソースが見つかりません。誤った URL を使用している可能性があります。
429Too Many Requestsお使いの App が 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 が利用できません。多くの場合、該当の Tweet が削除された、または別の理由により公開されていないことを示します。
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]/totals endpoint 向けにリクエストされた Tweet の ID が 90 日以内ではないため、impressions や engagements の metrics は返せません。
"errors":["Forbidden to access tweets: *TWEET_IDS*"]第三者のために data を取得する際に使用している認証トークンの権限に基づき、リクエストされた Tweet の ID にはアクセスできません。
⌘I