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

​
はじめに

Analytics の指標は、パートナーや広告主が X 上でプロモーションするコンテンツの成果を把握するのに役立ちます。これには、インプレッション、クリック、動画再生数、支出額などの情報が含まれます。さらに、パートナーや広告主は、リーチしたオーディエンスをさまざまなセグメントで切り分けた詳細指標を取得できます。 Ads API では、キャンペーンの詳細なパフォーマンス指標を取得する方法として、同期方式と非同期方式の 2 種類をサポートしています。同期型の analytics 呼び出しでは、要求した指標がレスポンスで返されます。非同期型の analytics エンドポイントでは、関連する「ジョブ」の処理が完了すると、ダウンロード可能な結果ファイルで要求した指標を取得できます。同期エンドポイントは短期間に対応しており、リアルタイムのキャンペーン最適化に最適です。非同期エンドポイントはより長期間に対応しており、より多くのデータの取得に適しているため、レポート作成や過去データの補完に最適です。

​
詳細

​
同期処理と非同期処理

同期処理と非同期処理のアナリティクスエンドポイントの違いは、次の表にまとめています。どちらのエンドポイント群を使用するかを判断する際の参考情報です。
機能同期処理非同期処理
レート制限ユーザーレベル: 15分あたり250リクエストアカウントレベル: 同時実行100件*のジョブ
期間7日間90日間（非セグメント）
45日間（セグメントあり）
セグメンテーションなしあり
レスポンスの内容メトリクスデータジョブの処理状態**
推奨ユースケースリアルタイム最適化
ユーザーインターフェースからのリクエスト		定期的な同期
履歴データのバックフィル
  • 任意の時点で処理中状態にできるジョブの最大数を指します。
** ジョブの処理が正常に完了すると、URLが返されます。そこから圧縮（gzip）された結果ファイルをダウンロードできます。これ以外の点では、両エンドポイントは同一の機能を提供します。

​
ユースケース

主なアナリティクスのユースケースは3つあります。
  1. リアルタイム最適化：パフォーマンス指標を用いて稼働中のキャンペーンを更新
  2. 同期：定期実行のバックグラウンド同期
  3. 新規アカウントのオンボーディング：履歴データのバックフィル
同期アナリティクスエンドポイントは、直近5〜15分の指標変化に基づいてキャンペーンを更新するリアルタイム最適化に使用できます。アナリティクスの同期には、いずれのエンドポイントも使用可能です。希望する時間範囲やセグメンテーションの要否により、使用すべきエンドポイントが決まる点に留意してください。新規アカウントのオンボーディングは、非同期アナリティクスエンドポイントのみで行ってください。（大量のdataを取得するために同期アナリティクスエンドポイントを使用してはいけません。） 非同期アナリティクスエンドポイントは、指標をバックエンド処理で同期することで、ダッシュボードやその他のUI要素を駆動できます。実装においては、ユーザーインターフェースのリクエストを満たす目的で非同期アナリティクスエンドポイントを呼び出すことは避けてください。

​
リクエストオプション

Analytics リクエストは広告アカウント単位でスコープされるため、リソースパスにアカウント ID が必要です。以下のリクエストオプションはクエリパラメータとして指定します。次の値が必須です。
  • エンティティ: エンティティタイプと、Analytics を取得したいエンティティ ID（最大 20 件）
  • 期間: ISO 8601 で表現された開始時刻と終了時刻
    • 注: 時刻は端数のない 1 時間単位で指定する必要があります
  • メトリックグループ: 関連するメトリクスの 1 つ以上の集合（各メトリックグループに含まれるメトリクス一覧は「Metrics and Segmentation」を参照）
  • 粒度: メトリクスを返す集計レベルを指定
  • 配信面: X のオンサイトまたはオフサイトで配信された広告のメトリクスを取得するかを指定
    • 注: リクエストごとに指定できる配信面の値は 1 つのみです
start_time と end_time リクエストパラメータで期間を指定します。これらの値は、以下のとおり指定した粒度に整合させる必要があります。
  1. TOTAL: 任意の期間を指定（エンドポイントの制限内）
  2. DAY: アカウントのタイムゾーンにおける午前 0 時に、開始時刻と終了時刻の両方をそろえる必要があります
  3. HOUR: 任意の期間を指定（エンドポイントの制限内）
終了時刻は排他的です。たとえば、start_time=2019-01-01T00:00:00Z と end_time=2019-01-02T00:00:00Z のリクエストは、この期間が 24 時間のみをカバーするため、1 日分の Analytics メトリクス（2 日分ではありません）を返します。 セグメンテーション 非同期の Analytics エンドポイントでのみ利用可能なセグメンテーションを使用すると、パートナーや広告主は特定のターゲティング値ごとに分解されたメトリクスを取得できます。セグメント化されたメトリクスをリクエストするには、segmentation_type リクエストパラメータを使用します。セグメンテーションの詳細は、Metrics and Segmentation および Metrics and Segmentation を参照してください。

​
よくある質問

なぜ Ads API の数値が X Ads の UI に表示されるものと一致しないのですか？
  • 両方のプレースメント ALL_ON_TWITTER に加え、PUBLISHER_NETWORK、SPOTLIGHT、TREND のデータを必ずリクエストしてください。
  • Ads API の終了時刻は「排他的」、Ads UI の終了時刻は「包括的」であることに注意してください。
なぜ、データのリクエスト時期によって数値が変わるのですか？
  • レポート指標は利用可能になり次第、ほぼリアルタイムで取得できます。これらの初期結果は推定値のため変動が見込まれます。支出データを除き、指標は 24 時間後に確定します。
  • 支出指標は一般的にイベントから 3 日以内に確定します。ただし、請求データは（スパムフィルタリングなどのため）イベント日から最大 14 日間処理されます。
特定の期間にどのエンティティの id をリクエストすべきかはどう判断できますか？ なぜ analytics のレスポンスの値がすべて null なのですか？
  • リクエストした期間中にキャンペーンが配信されていなかった可能性があります。
  • どのエンティティについて、どの期間の analytics を取得するかを判断するには、Active Entities エンドポイントを使用してください。
なぜ API は null を示すのに、UI では 0 が表示されるのですか？
  • UI はこれらの値を 0 として表示する仕様ですが、意味としては同等です。
X のタイムラインのような粒度の細かいプレースメントに関連する指標は、どのようにリクエストできますか？
  • analytics では次のプレースメント値をサポートしています: ALL_ON_TWITTER に加え、PUBLISHER_NETWORK、SPOTLIGHT、TREND（すなわち X Audience Platform）。
削除済みまたは一時停止中のエンティティの指標を取得できますか？
  • 可能です。エンティティのステータスは analytics 指標の取得可否に影響しません。
なぜセグメント化された値が、非セグメント化の値と一致しないのですか？
  • この情報の導出方法により、セグメント化されたデータが非セグメント化のデータに 100% 集計されることは想定されていません。
複数のディメンションでセグメント化したデータをリクエストできますか？
  • 複数セグメンテーションはサポートしていません。

​
ベストプラクティス

Ads API からanalyticsデータを収集する際のベストプラクティス。

​
レート制限とリトライ

  • レート制限されたクエリ（HTTP 429 ステータスコードを返すもの）の場合は、x-rate-limit-reset ヘッダーを確認し、示された時刻以降にのみリトライしてください。
  • HTTP 503 Service Unavailable ステータスコードとなるクエリの場合は、retry-after ヘッダーを確認し、示された時刻以降にのみリトライしてください。
  • 指定されたリトライ時刻に従わないアプリケーションは、予告なく Ads API へのアクセスを取り消されたり、制限（スロットリング）されたりする場合があります。

​
アナリティクス指標の要点

  • すべてのアナリティクス指標は billed_charge_local_micro を除き、24時間後にロックされ、変更されません。
  • billed_charge_local_micro 指標は、data が返された後、最大3日間は推定値です。
  • 24時間経過後、この指標は過剰配信に対するクレジット（指定した end_time 以降に配信された広告）や、ジャンクと判断された課金対象イベントにより減少する場合があります。24時間以降の変動は最小限です。
  • 詳細は Analytics を参照してください。

​
リアルタイムの非セグメントデータの取得

  • 常に start_time と end_time の両方を指定してください。
  • 7日より前のエンティティのデータは取得しないでください。
  • （理想的には）HOUR 粒度でデータをリクエストしてください。メトリクスは集計して DAY や TOTAL の粒度にまとめられます。
  • （理想的には）line_items および promoted_tweets レベルでデータをリクエストしてください。メトリクスは集計して、キャンペーン、資金手段、アカウントなど広告エンティティ階層全体の合計にまとめられます。
  • 分析メトリクスの値はローカルに保存・保管してください。
  • 30日より前のデータを繰り返しクエリしないでください。このデータは変化せず、ローカルに保存すべきです。
  • 非セグメントデータはすべてリアルタイムで、イベント発生から数秒以内に利用可能になります。
  • コンバージョン関連メトリクスと非コンバージョン関連メトリクスは別々のリクエストに分けてください。

​
セグメント化データの取得

  • 上記の「リアルタイムの非セグメント化データの取得」のガイドラインを参照してください。以下に追加の注意事項を示します。
  • 多くのセグメント化データでは、データが最大1時間にわたり確定しない場合があります。INTERESTS でセグメント化されたデータは、最大12時間遅延することがあります。
  • この情報の算出方法により、セグメント化データが非セグメント化データと100%一致して集計されることは想定されていません。

​
履歴データの取得

  • データのバックフィル（例：新しい広告主アカウントの追加）を行う場合は、start_time と end_time を細かい期間に分割して複数回リクエストする必要が生じることがあります。
  • 取得は30日間の期間ウィンドウに制限してください。
  • レート制限を消費し切らないよう、これらのリクエストはスロットリングし、時間を分散して実行してください。

​
サンプル

これらのベストプラクティスの一部を示すサンプルスクリプト（fetch_stats）は、ads-platform-tools の GitHub リポジトリで公開しています。

​
目的別のメトリクス

エンティティに適用されるメトリクスは、キャンペーンの目的によって異なります。本ガイドを参考に、各目的タイプで取得すべき関連するメトリクスグループを特定し、あわせて追加の派生メトリクスの算出方法を確認してください。

​
ENGAGEMENTS

関連するメトリックグループ: ENGAGEMENT と BILLING。クリエイティブでメディアを使用している場合は MEDIA も対象です。
派生メトリック公開メトリックの計算式
エンゲージメント率engagements/impressions
CPEbilled_charge_local_micro/engagements
メディア視聴率media_views/impressions

​
WEBSITE_CLICKS と WEBSITE_CONVERSIONS

関連するメトリックグループ: ENGAGEMENT、BILLING、WEB_CONVERSION。クリエイティブでメディアを使用している場合は MEDIA も適用されます。
派生メトリック露出メトリックの計算式
CPMbilled_charge_local_micro/impressions/1000
クリック率clicks/impressions
CPLCbilled_charge_local_micro/clicks
合計コンバージョンconversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
コンバージョン率合計コンバージョン / impressions
CPAbilled_charge_local_micro / 合計コンバージョン

​
APP_INSTALLS と APP_ENGAGEMENTS

関連するメトリックグループ：ENGAGEMENT、BILLING、MOBILE_CONVERSION、および LIFE_TIME_VALUE_MOBILE_CONVERSION。クリエイティブでメディアまたは動画アプリカードを使用している場合は、MEDIA と VIDEO も対象です。
派生メトリック公開メトリックの算出方法
CPMbilled_charge_local_micro/impressions/1000
アプリクリック率app_clicks/impressions
CPACbilled_charge_local_micro/app_clicks
CPIbilled_charge_local_micro/mobile_conversion_installs

​
FOLLOWERS

関連するメトリックグループ: ENGAGEMENT と BILLING。クリエイティブでメディアを使用している場合は MEDIA も該当します。
派生メトリクス公開メトリクスの計算式
CPMbilled_charge_local_micro/impressions/1000
フォロー率follows/impressions
CPFbilled_charge_local_micro/follows
メディア視聴率media_views/impressions

​
LEAD_GENERATION

関連するメトリックグループ：ENGAGEMENT および BILLING。クリエイティブでメディアを使用している場合は MEDIA も該当します。
派生メトリック公開メトリックの算出方法
CPMbilled_charge_local_micro/impressions/1000
リード数card_engagements
リード率card_engagements/impressions
リード単価billed_charge_local_micro/card_engagements

​
VIDEO_VIEWS

関連するメトリックグループ：ENGAGEMENT、BILLING、VIDEO
派生メトリクス公開メトリクスの計算式
CPMbilled_charge_local_micro/impressions/1000
動画視聴率video_total_views/impressions
視聴あたりのコスト（CPV）billed_charge_local_micro/video_total_views

​
VIDEO_VIEWS_PREROLL

関連メトリクスグループ: ENGAGEMENT、BILLING、VIDEO
派生メトリクス公開メトリクスの計算式
CPMbilled_charge_local_micro/impressions/1000
ビデオレートvideo_total_views/impressions
1視聴あたりのコストbilled_charge_local_micro/video_total_views

​
指標とセグメンテーション

このドキュメントでは、各エンティティタイプごとに当社のAnalyticsで利用可能な指標の概要と、それぞれの指標で利用可能なセグメンテーションの概要を示します。
指標グループ
エンティティENGAGEMENTBILLINGVIDEOMEDIAWEB_CONVERSIONMOBILE_CONVERSIONLIFE_TIME_VALUE_MOBILE_CONVERSION
ACCOUNT✔*
FUNDING_INSTRUMENT✔*✔
CAMPAIGN✔✔✔✔✔✔✔
LINE_ITEM✔✔✔✔✔✔✔
PROMOTED_TWEET✔✔✔✔✔✔✔
MEDIA_CREATIVE✔✔✔✔✔✔✔
ORGANIC_TWEET✔✔
*ENGAGEMENT 指標ファミリーの一部の指標は、アカウントおよび資金提供手段レベルでは利用できません。詳細は ENGAGEMENT セクションを参照してください。

​
メトリクスグループ別の利用可能な指標

​
ENGAGEMENT

Metric説明セグメンテーションの可用性データ型アカウント / Funding Instrument で利用可能
engagementsエンゲージメントの合計数✔整数配列✔
impressionsインプレッションの合計数✔整数配列✔
retweetsリツイートの合計数✔整数配列✔
repliesリプライの合計数✔整数配列✔
likesいいねの合計数✔整数配列✔
followsフォローの合計数✔整数配列✔
card_engagementsカードのエンゲージメント合計✔整数配列
clicksいいねなどの他のエンゲージメントを含むクリックの合計数✔整数配列
app_clicksアプリのインストールまたは起動の試行回数✔整数配列
url_clicks広告内のリンクまたは Website Card への総クリック数（獲得分を含む）✔整数配列
qualified_impressions有効なインプレッションの合計数✔整数配列
carousel_swipesカルーセル画像または動画のスワイプ合計✔整数配列

​
BILLING

Metric説明セグメンテーションの可否データ型
billed_engagements課金対象エンゲージメントの総数✔整数の配列
billed_charge_local_microマイクロ単位での総支出額✔整数の配列

​
VIDEO

動画指標の定義変更に関するお知らせ: MRC標準に従い、VIDEO 指標グループ内の video_total_views は、少なくとも2秒間、画面上に50%以上表示された視聴をカウントします。 従来の動画ビュー定義（少なくとも3秒間、100%が画面上に表示）については、VIDEO 指標グループ内の新しい video_3s100pct_views 指標として引き続き利用できます。従来のビュー定義に基づいて入札と課金を継続するには、新たに利用可能な VIEW_3S_100PCT bid_unit を使用してください。
Metric説明セグメンテーション可否データ型
video_total_views動画ビューの総数✔整数配列
video_views_25動画の少なくとも25%が視聴されたビューの総数✔整数配列
video_views_50動画の少なくとも50%が視聴されたビューの総数✔整数配列
video_views_75動画の少なくとも75%が視聴されたビューの総数✔整数配列
video_views_100動画の100%が視聴されたビューの総数✔整数配列
video_cta_clicksCall to Action への総クリック数✔整数配列
video_content_starts動画の再生開始回数の総数✔整数配列
video_3s100pct_views100%が画面上に表示された状態で少なくとも3秒間再生されたビューの総数（従来の video_total_views）✔整数配列
video_6s_views動画の少なくとも6秒が視聴されたビューの総数✔整数配列
video_15s_views動画の少なくとも15秒、または総再生時間の95%が視聴されたビューの総数✔整数配列

​
MEDIA

Metric説明セグメンテーション可否データ型
media_viewsVideos、Vines、GIFs、Images におけるメディアの合計視聴回数（自動再生およびクリック再生）。✔整数の配列
media_engagementsVideos、Vines、GIFs、Images におけるメディアの合計クリック数。✔整数の配列

​
WEB_CONVERSION

Metric説明利用可能なセグメンテーションデータ型
conversion_purchasesPURCHASE タイプのコンバージョン数と、それに対応する売上金額および注文数PLATFORMS のみJSON オブジェクト
conversion_sign_upsSIGN_UP タイプのコンバージョン数と、それに対応する売上金額および注文数PLATFORMS のみJSON オブジェクト
conversion_site_visitsSITE_VISIT タイプのコンバージョン数と、それに対応する売上金額および注文数PLATFORMS のみJSON オブジェクト
conversion_downloadsDOWNLOAD タイプのコンバージョン数と、それに対応する売上金額および注文数PLATFORMS のみJSON オブジェクト
conversion_customCUSTOM タイプのコンバージョン数と、それに対応する売上金額および注文数PLATFORMS のみJSON オブジェクト

​
MOBILE_CONVERSION

モバイルコンバージョンの統計は、MACT が有効になっている広告主アカウントでのみ利用できます。
メトリック説明利用可能なセグメントデータ型
mobile_conversion_spent_creditsSPENT タイプのモバイル向けコンバージョン内訳_Post単位のCREDIT_ビュー、Post_エンゲージメント、アシスト、オーダー_数量、販売_金額✔JSON オブジェクト
mobile_conversion_installsPost別のINSTALLタイプのモバイルコンバージョン内訳_表示、Post_エンゲージメント、アシスト、オーダー_数量、販売_金額✔JSONオブジェクト
mobile_conversion_content_viewsCONTENT タイプのモバイルコンバージョン内訳_Post別のVIEW_表示、Post_エンゲージメント、アシスト、オーダー_数量と売上_金額✔JSON オブジェクト
mobile_conversion_add_to_wishlistsADD タイプのモバイルコンバージョン内訳_宛先_PostごとのWISHLIST_表示、Post_エンゲージメント、アシスト、オーダー_数量、販売_金額✔JSON オブジェクト
mobile_conversion_checkouts_initiatedCHECKOUT タイプのモバイルコンバージョンの内訳_Post によって開始_表示、投稿_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSON オブジェクト
mobile_conversion_reservationsPost別RESERVATIONタイプのモバイルコンバージョン内訳（post_view、post_engagement、assisted、order_quantity、sale_amount別）_ビュー、Post_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSON オブジェクト
mobile_conversion_tutorials_completedモバイルコンバージョン（TUTORIAL タイプ）の内訳_Post別の完了_ビュー、Post_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSON オブジェクト
mobile_conversion_achievements_unlockedACHIEVEMENT タイプのモバイルコンバージョンの内訳_Postによって解除_ビュー、ポスト_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSON オブジェクト
mobile_conversion_searchesPost別SEARCHタイプのモバイルコンバージョン内訳_ビュー、Post_エンゲージメント、アシスト、注文_数量、売上_金額✔JSON オブジェクト
mobile_conversion_add_to_cartsモバイルコンバージョン（タイプ: ADD）の内訳_宛先_Post単位のCART_表示、Post_エンゲージメント、アシスト、注文_数量、販売_金額✔JSON オブジェクト
mobile_conversion_payment_info_additionsPAYMENTタイプのモバイルコンバージョンの内訳_情報_Postごとの追加_ビュー、Post_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSON オブジェクト
mobile_conversion_re_engagesRE タイプのモバイルコンバージョン内訳_Post別のENGAGE_表示、Post_エンゲージメント、アシスト、オーダー_数量、販売_金額✔JSON オブジェクト
mobile_conversion_sharesPost別SHAREタイプのモバイルコンバージョン内訳_閲覧、Post_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSONオブジェクト
mobile_conversion_ratesPost別RATEタイプのモバイルコンバージョン内訳_ビュー、Post_エンゲージメント、アシスト、注文_数量と売上_金額✔JSON オブジェクト
mobile_conversion_loginsPost別のLOGINタイプのモバイルコンバージョン内訳_表示、Post_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSON オブジェクト
mobile_conversion_updatesPost別UPDATEタイプのモバイルコンバージョン内訳_表示、Post_エンゲージメント、アシスト、オーダー_数量、売上_金額✔JSON オブジェクト
mobile_conversion_levels_achievedLEVELタイプのモバイルコンバージョンの内訳_Post別の達成状況_ビュー、ポスト_エンゲージメント、アシスト、オーダー_数量、販売_金額✔JSON オブジェクト
mobile_conversion_invitesPost別のINVITEタイプのモバイルコンバージョン内訳_ビュー、Post_エンゲージメント、アシスト、注文_数量、販売_金額✔JSON オブジェクト
mobile_conversion_key_page_viewsKEYタイプのモバイルコンバージョン内訳_ページ_Post別のビュー_閲覧と投稿_エンゲージメント✔JSONオブジェクト
モバイル_コンバージョン_ダウンロードPost単位のDOWNLOADタイプのモバイルコンバージョン内訳_表示、Post_エンゲージメント、アシスト、注文_数量と売上_金額✔JSON オブジェクト
モバイル_コンバージョン_購入Post単位のPURCHASEタイプのモバイルコンバージョン内訳_表示、Post_エンゲージメント, アシスト, オーダー_数量、売上_金額✔JSONオブジェクト
モバイル_コンバージョン_記号_おっとSIGNタイプのモバイルコンバージョンの内訳_Post別のアップ_表示、Post_エンゲージメント、アシスト、オーダー_数量、販売_金額✔JSON オブジェクト
モバイル_コンバージョン_サイト_訪問数SITEタイプのモバイルコンバージョン内訳_Post別のVISIT_表示、Post_エンゲージメント、アシスト、オーダー_数量、販売_金額✔JSON オブジェクト

​
LIFE_TIME_VALUE_MOBILE_CONVERSION

ライフタイムのモバイルコンバージョン統計は、MACT が有効になっている広告主アカウントでのみ利用できます。
指標説明セグメンテーションの可否データ型
mobile_conversion_lifetime_value_purchasesPURCHASE タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_sign_upsSIGN_UP タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_updatesUPDATE タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_tutorials_completedTUTORIAL_COMPLETED タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_reservationsRESERVATION タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_add_to_cartsADD_TO_CART タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_add_to_wishlistsADD_TO_WISHLIST タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_checkouts_initiatedCHECKOUT_INITIATED タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_levels_achievedLEVEL_ACHIEVED タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_achievements_unlockedACHIEVEMENT_UNLOCKED タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_sharesSHARE タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_invitesINVITE タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_payment_info_additionsPAYMENT_INFO_ADDITION タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_spent_creditsSPENT_CREDIT タイプのモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_ratesRATE タイプのモバイルコンバージョンの内訳JSON オブジェクト

​
セグメンテーション

セグメンテーションレポートでは、指定したターゲティングタイプの各値ごとに分解した指標を取得できます。セグメンテーションは、追加の複雑性が高いため、非同期アナリティクスクエリでのみ利用可能です。 MEDIA_CREATIVE および ORGANIC_TWEET エンティティではセグメンテーションはサポートされません。 一部のセグメンテーションタイプでは、追加パラメータの指定が必要です。詳細は以下をご確認ください。 CITIES または POSTAL_CODES でセグメント化する場合、API はターゲティング対象のロケーションのみを返します。地域およびメトロによるセグメンテーションでは、ターゲティング対象・非対象の両方のロケーションが返されます。
セグメンテーションタイプcountry パラメータ必須platform パラメータ必須
AGE
APP_STORE_CATEGORY
AUDIENCES
CITIES✔
CONVERSATIONS
CONVERSION_TAGS
DEVICES✔
EVENTS
GENDER
INTERESTS
KEYWORDS
LANGUAGES
LOCATIONS
METROS✔
PLATFORMS
PLATFORM_VERSIONS✔
POSTAL_CODES✔
REGIONS✔
SLIDES
SIMILAR_TO_FOLLOWERS_OF_USER
TV_SHOWS

​
派生指標

キャンペーン指標は、そのキャンペーンの目的に依存します。設定されている目的に基づき、利用する派生指標の算出方法を判断する際は本ガイドをご活用ください。 波括弧のないmetricは、Ads API のanalyticsエンドポイントで返される指標です。名前が{波括弧}で囲まれている場合は、そのカテゴリの派生指標を示します。

​
エンゲージメント

派生指標公開指標の計算式
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {インプレッション数} / 1000
{総エンゲージメント数}promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements または promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows
{エンゲージメント率}{総エンゲージメント数} / {インプレッション数}
billed_charge_local_micro / {総エンゲージメント数}
{メディア視聴数}promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{メディア視聴率}{メディア視聴数} / {インプレッション数}

​
WEBSITE_CLICKS

派生指標公開指標の算出式
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks
{Link Clicks} / {Impressions}
billed_charge_local_micro / {Link Clicks}
conversion_site_visits
conversion_site_visits / {Impressions}
billed_charge_local_micro / conversion_site_visits

​
APP_INSTALLS と APP_ENGAGEMENTS

派生指標公開指標の計算式
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions
billed_charge_local_micro / {インプレッション数} / 1000
promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks
{アプリクリック数} / {インプレッション数}
billed_charge_local_micro / {アプリクリック数}
billed_charge_local_micro / mobile_conversion_installs

​
フォロワー

派生指標公開指標の算出方法
promoted_account_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_account_follows
{Follow Rate}promoted_account_follow_rate
billed_charge_local_micro / promoted_account_follows
{Media Views}promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}{Media Views} / {Impressions}

​
LEAD_GENERATION

派生指標公開指標の計算式
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_tweet_search_card_engagements + promoted_tweet_timeline_card_engagements + promoted_tweet_profile_card_engagements
{Lead Rate}{Leads} / {Impressions}
{Cost Per Lead}billed_charge_local_micro / {Leads}

​
VIDEO_VIEWS

派生指標露出指標の計算
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Video Views}promoted_video_total_views
{Video Rate}promoted_video_total_views / {Impressions}
{Cost Per View}billed_charge_local_micro / promoted_video_total_views

​
QUALIFIED_IMPRESSIONS

導出指標露出指標の計算
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Qualified Impressions}promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions
{Qualified Impression Rate}{Qualified Impressions} / {Impressions}
{Cost Per 1000 Qualified Impressions}billed_charge_local_micro / {Qualified Impressions} / 1000

​
カスタム

placement_type が PROMOTED_ACCOUNT の場合は、上記の FOLLOWERS 目標を参照してください。その他のすべてのプレースメントについては、対応する派生指標について ENGAGEMENTS を参照してください。

​
ガイド

​
アクティブなエンティティ

​
はじめに

Active Entitiesエンドポイントは、同期および非同期アナリティクスエンドポイントと併用することを想定して設計されており、どのキャンペーンの分析データをリクエストすべきかの情報を提供します。広告エンティティとそのメトリクスが変更された時期の詳細を返すことで、この機能を実現しています。このエンドポイントを使用することで、コードとアナリティクス取得ロジックを大幅に簡素化できます。 このガイドでは、エンドポイントとそのデータソースに関する情報とコンテキストを提供します。また、使用ガイドラインと一連のリクエスト例により、Active Entitiesをアナリティクスエンドポイントと併用する方法を示しています。概要セクションでは、推奨されるアプローチの概要を説明しています。

​
データ

広告エンティティのメトリクスに変更があるたびに、その変更に関する情報を記録します。これらの変更イベントは1時間ごとのバケットに格納され、エンティティの詳細に加え、変更が適用される時刻も含みます。後者が必要なのは、変更イベントが必ずしも記録時点と一致しないためです。請求調整がその一般的な理由ですが、他にも要因があります。

​
エンドポイント

​
リクエスト

Active Entities のリクエストは広告アカウントをスコープとし、必須のクエリパラメータが3つあります: entity、start_time、end_time。 twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z" サポートされている entity の値は次のとおりです: CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_ACCOUNT、PROMOTED_TWEET。これは、当社のアナリティクスエンドポイントがサポートするエンティティタイプを反映しています。 start_time と end_time の値は ISO 8601 形式で指定し、クエリ対象となる1時間ごとのバケットを示す必要があります。これらはちょうどの時刻（1時間単位）で指定してください。 このエンドポイントは、結果をフィルタリングするために使用できる3つの任意パラメータもサポートします: funding_instrument_ids、campaign_ids、line_item_ids。これらは広告階層のあらゆるレベルおよび指定した任意の entity タイプで機能します。

​
レスポンス

上記のリクエストに対する Active Entities のレスポンスは次のとおりです。 
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-03-05T00:00:00Z",
          "end_time": "2019-03-06T00:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2r0wxw",
          "activity_start_time": "2019-03-04T20:55:20Z",
          "activity_end_time": "2019-03-05T03:43:56Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2r30fn",
          "activity_start_time": "2019-03-05T08:11:08Z",
          "activity_end_time": "2019-03-05T14:40:59Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }
data 配列には、後続のアナリティクスリクエストに含めるべき各エンティティごとのオブジェクトが含まれます。この集合に含まれない ID についてアナリティクスをリクエストしてはいけません。 各オブジェクトには 4 つの fields が含まれます: entity_id、activity_start_time、activity_end_time、placements。アクティビティの開始時刻と終了時刻は、関連するエンティティの変更イベントが適用される時間範囲を表し、そのため後続のアナリティクスリクエストで指定すべき日付を決定します。placements 配列には、ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND の値を含めることができます。これは、指定されたエンティティ ID に対してどの配置をリクエストすべきかを示します。

​
使い方

Active Entities エンドポイントは、analytics リクエストの行い方の指針となるべきです。以下の利用ガイドラインは analytics の同期を支援する目的で記載されており、パートナーが自社のデータストアを Twitter と同期状態に保てるようにします。言い換えると、定期的に実行されるバックグラウンド同期の方法を説明しています。 開発者は次の2点を判断する必要があります。
  1. アクティブなエンティティ情報をどの程度の頻度で取得するか、ひいては analytics をどれくらいの頻度で取得するか。
  2. アクティビティの開始時刻と終了時刻をどのように用いて、analytics リクエストの start_time と end_time の値を決定するか。
これらについては、要約の後に続く2つの小節で詳しく説明します。

​
概要

以下の方法で Active Entities エンドポイントを使用し、analytics リクエストの実行方法を決定します。アクティブなエンティティ情報の取得頻度、ひいては analytics の取得頻度を決めた後に、次の手順に従ってください。
  1. Active Entities リクエストを送信します。
  2. レスポンスを placement ごとに分割します。ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND それぞれに1つずつグループを作成します。
  3. 各 placement グループに対して、次を実行します。
    1. エンティティの ID を抽出します。
    2. analytics の start_time と end_time を決定します。
      • 最小の activity_start_time を見つけ、この値を切り下げます。
      • 最大の activity_end_time を見つけ、この値を切り上げます。
    3. analytics リクエストを送信します。
      • エンティティの ID を20件ずつのバッチにまとめます。
      • #3b で決定した start_time と end_time を使用します。
      • 適切な placement を指定します。
    4. データストアに書き込みます。
Python SDK を使用した例として、active_entities.py を参照してください。

​
頻度

最初の設問への回答に基づいて、Active Entities リクエストで使用すべき時間範囲が決まります。たとえば、毎時 Active Entities の情報を取得する場合は時間範囲を1時間に、1日1回取得する場合は1日に設定します。言い換えると、現在のリクエストの start_time は、前回のリクエストの end_time と同一になるように時間範囲を選択してください。
注意: 各時間ウィンドウは1度だけリクエストしてください。同じウィンドウを複数回リクエストすると、不要な分析リクエストが発生します（下記の例外を参照）。
パートナーが「現在進行中の」1時間について、その1時間の間に複数回分析データを取得したい場合でも、同じ考え方が適用されます—取得頻度が時間範囲を決定します。以下の表は、このシナリオにおける Active Entities の開始・終了タイムスタンプの例です。
リクエスト時刻start_time タイムスタンプend_time タイムスタンプ
00:15:0000:00:0000:15:00
00:30:0000:15:0000:30:00
00:45:0000:30:0000:45:00
01:00:0000:45:0001:00:00
変更イベントの保存方法により、上記4つの Active Entities リクエストはいずれも同じ1時間のバケットを照会します。これはこのユースケースでは必要ですが、現在の1時間を過ぎた後は、その時間バケットを再度照会しないでください。

​
アクティビティ時刻

アクティビティの開始時刻と終了時刻を扱う際は、以下の方法を推奨します。Active Entities のレスポンス内のすべてのオブジェクトを対象に、最小の activity_start_time と最大の activity_end_time を見つけます。これらの値を、最小のアクティビティ開始時刻は切り下げ、最大のアクティビティ終了時刻は切り上げるように調整します。具体的には、どちらのタイムスタンプも時・分・秒をゼロに設定し、終了時刻にさらに 1 日を加えます。以下の表のとおりです。これらが、その後の analytics リクエストで指定すべき開始時刻と終了時刻です。
最小・最大のアクティビティ時刻導出された時刻
2019-03-04T20:55:20Z

2019-03-05T14:40:59Z		2019-03-04T00:00:00Z

2019-03-06T00:00:00Z
注: 時・分・秒をゼロに設定したタイムスタンプを含めることが重要です。そうしない場合、日付のみが渡されたとき、ads アカウントのタイムゾーンでの午前0時開始・午前0時終了の analytics をリクエストしているとみなしますが、これは望ましくない場合があります。たとえば、最小のアクティビティ開始時刻が 2019-02-28T01:30:07Z で、オフセットが -08:00:00 の ads アカウントでタイムスタンプを省略した場合、01:30～08:00 の間に発生した変更は analytics リクエストから漏れてしまいます。 また、日単位に拡張せず、返されたアクティビティの時間ウィンドウのみで analytics をリクエストすることも可能です。この方法では、導出される開始時刻と終了時刻はそれぞれ 2019-03-04T20:00:00Z と 2019-03-05T15:00:00Z になります。（なお、analytics リクエストで DAY の粒度を指定する場合、このような範囲は受け付けられません。）

​
例

このセクションでは、Active Entities を同期型の analytics エンドポイントと組み合わせて使用する方法を示します。（可読性向上のため、レスポンスは一部調整しています。）この例では、Active Entities エンドポイントを毎時ちょうどに呼び出し、各リクエストは直前の1時間を対象とします。レスポンスに基づいて、同期型 analytics エンドポイントの使用方法を決定します。 最初の Active Entities リクエストは 03:00:00 に行われます。レスポンスは、line item「dvcz7」のメトリクスに変更があり、その変更イベントが 02:02:55 から 02:28:12 の時間枠に適用されることを示しています。 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:02:55Z",
          "activity_end_time": "2019-02-11T02:58:12Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
これらのアクティビティの開始時刻と終了時刻に基づき、前述の方法を用いると、analytics の start_time と end_time はそれぞれ 2019-02-11T00:00:00Z と 2019-02-12T00:00:00Z に設定されます。以下の各メトリクス配列では、アクティブなエンティティ情報どおり、3 番目の要素が非ゼロであることが確認できます。 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
次の Active Entities リクエストは 04:00:00 に実行され、直前の1時間のみを対象とします。前述のとおり、同じ時間ウィンドウは一度だけリクエストすべきです。レスポンスによると、このラインアイテムの変更イベントは 02:00:00 と 03:00:00 の両方に適用されます。続く analytics リクエストでは、両時間帯の変更が確認できるはずです。 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:07:17Z",
          "activity_end_time": "2019-02-11T03:49:22Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
03:00:00 に非ゼロの指標が表示されていることに加え、impressions、spend、MRC video views が以前の値から更新されていることがわかります。たとえば、impressions は 02:00:00 の時間帯で、2,792 から 2,995 に増加しています。これは、03:00:00 の時間帯に記録された変更イベントが 02:00:00 の時間帯に反映されることを示しています。 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
05:00:00 の Active Entities リクエストでは、今回も直前の1時間のみを対象にしているため、変更イベントは 03:00:00 の時間帯にのみ適用されることが示されています。続くリクエストでのアナリティクス指標の変化は、その内容を反映しています。 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T03:42:39Z",
          "activity_end_time": "2019-02-11T03:48:48Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
analytics のレスポンスでは、03:00:00 の時間帯のメトリクスのみが変更され、02:00:00 の時間帯の値は前回の analytics リクエスト時と同じであることが示されています。 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
最後に、06:00:00 時点で追加の変更イベントがないことが確認できます。注: ただし、これはこのラインアイテムの指標が今後も変わらないことを意味するものではありません。 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"`

    {
      "request": {},
      "data": []
    }

​
非同期処理ガイド

​
API リファレンス

​
非同期分析

​
はじめに

非同期アナリティクスのエンドポイントは、パートナーや広告主が作成リクエストを送信し、サーバー側で非同期処理することでメトリクスを取得できるようにします。（これらを非同期アナリティクスの「ジョブ」と呼びます。）この方式では、リクエストが完了するまでクライアントの接続を開いたままにしておく必要はありません。 これらのエンドポイントは、同期版と同様に、パートナーや広告主がキャンペーンのパフォーマンスに関する詳細な統計をリクエストできます。アカウント、ファンディングインストゥルメント、キャンペーン、ラインアイテム、プロモツイート、メディアクリエイティブのデータ取得をサポートします。同期エンドポイントとの違いは、非同期アナリティクスのエンドポイントが最大90日までのより長い期間やセグメンテーションをサポートする点です。両者の違いの詳細は、Analytics Overview ページをご覧ください。 同期エンドポイントとは異なり、レート制限は特定のアカウントに対する同時実行ジョブ数に基づきます。言い換えると、ある時点で処理中となり得るジョブの数に基づきます。これは広告アカウント単位で計測されます。

​
使用方法

非同期 analytics エンドポイントを使用してキャンペーン指標を取得するには、複数の手順が必要です。ジョブを作成し、処理完了を確認し、最後に data をダウンロードします。data ファイルは解凍する必要があります。具体的な 4 つの手順は次のとおりです。
  1. POST stats/jobs/accounts/:account_id エンドポイントを使用してジョブを作成します。
  2. ジョブの処理が完了したかどうかを確認するため、一定間隔で GET stats/jobs/accounts/:account_id エンドポイントにリクエストします。
  3. ジョブの処理が完了したら、data ファイルをダウンロードします。
  4. data ファイルを解凍します。
data ファイルで返されるレスポンスオブジェクトは、同期 analytics エンドポイントのレスポンスと同じ JSON スキーマです。 セグメント化されたキャンペーン指標は非同期 analytics エンドポイントでのみ利用可能です。キャンペーン指標は、地域、性別、興味関心、キーワードなどで内訳できます。オプションの一覧は、Metrics and Segmentation ページを参照してください。セグメント化された指標をリクエストするには、ジョブ作成時に segmentation_type リクエストパラメータを使用します。

​
例

このセクションでは、非同期の analytics エンドポイントの使い方を説明します。 まず、POST stats/jobs/accounts/:account_id エンドポイントでジョブを作成します。以下の例では、特定のラインアイテムについて1週間分のエンゲージメント指標（インプレッション、いいね、クリックなど）をリクエストしています。（タイムスタンプが深夜に設定されているため、指定した期間は3月20日の直前までで、3月20日自体は含まれない点に注意してください。） 
$ twurl -X POST -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2019-03-12T00:00:00Z&end_time=2019-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"

    {
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      },
      "data": {
        "start_time": "2019-03-12T00:00:00Z",
        "segmentation_type": null,
        "url": null,
        "id_str": "1120829647711653888",
        "entity_ids": [
          "el32n"
        ],
        "end_time": "2019-03-20T00:00:00Z",
        "country": null,
        "placement": "ALL_ON_TWITTER",
        "id": 1120829647711653888,
        "expires_at": null,
        "account_id": "18ce54d4x5t",
        "status": "PROCESSING",
        "granularity": "TOTAL",
        "entity": "LINE_ITEM",
        "created_at": "2019-04-23T23:19:46Z",
        "platform": null,
        "updated_at": "2019-04-23T23:19:46Z",
        "metric_groups": [
          "ENGAGEMENT"
        ]
      }
    }
このレスポンスはラインアイテムのメトリクスを返しません。作成したジョブに関する情報のみを提供します。ジョブのステータスを確認するにはジョブIDが必要で、レスポンス属性の id と id_str の両方に含まれます。 次に、前のレスポンスで取得した id_str を使って、作成したジョブが処理を完了し、レスポンス内で "status": "SUCCESS" と表示されているかを確認します。これは data のダウンロード準備ができたことを意味します。url フィールドにはダウンロードリンクが含まれています。 
$ twurl -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"

    {
      "request": {
        "params": {
          "job_ids": [
            1120829647711653888
          ]
        }
      },
      "next_cursor": "1120828505715920896",
      "data": [
        {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "url": "https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz",
          "id_str": "1120829647711653888",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "id": 1120829647711653900,
          "expires_at": "2019-04-25T23:19:48Z",
          "account_id": "18ce54d4x5t",
          "status": "SUCCESS",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "created_at": "2019-04-23T23:19:46Z",
          "platform": null,
          "updated_at": "2019-04-23T23:19:48Z",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      ]
    }
上の例では単一のジョブIDを渡していますが、実際には最大200件のジョブIDを指定し、job_ids パラメータを使って複数のジョブのステータスを同時に確認するのがよいでしょう。 次に、記載されている url の値を使ってデータファイルをダウンロードします。 
    $ wget https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    --2019-04-23 17:52:12--  https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    ton.twimg.com (ton.twimg.com) を解決しています... 72.21.91.70
    ton.twimg.com (ton.twimg.com)|72.21.91.70|:443 に接続しています... 接続しました。
    HTTP リクエストを送信しました、応答を待っています... 200 OK
    Length: 381 [application/gzip]
    保存先: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

    zBkuuPeEVx-5OygDVcZpqNtwt51Z5 100%[=================================================>]     381  --.-KB/s    in 0s

    2019-04-23 17:52:12 (5.27 MB/s) - 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' を保存しました [381/381]
最後に、ファイルを解凍します。 
`$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz`
ファイルの内容は以下のとおりです。 
`$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json`

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "el32n",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  3482
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": [
                  102
                ],
                "unfollows": null,
                "likes": [
                  15
                ],
                "engagements": [
                  171
                ],
                "clicks": [
                  30
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​
到達数と平均頻度

​
GET stats/accounts/:account_id/reach/campaigns

指定したキャンペーンのリーチと平均フリークエンシーに関する分析指標を取得します。

​
リソース URL

https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns

​
パラメータ

名前説明
account_id
必須		利用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

型: string

例: 18ce54d4x5t
campaign_ids
必須		目的のキャンペーンのみを対象にするため、識別子のカンマ区切りリストを指定します。最大 20 個の ID を指定できます。

注記: 最大 20 個のキャンペーン ID を指定できます。

型: string

例: 8fgzf
end_time
必須		取得対象のデータを、ISO 8601 で表した指定の終了時刻までに限定します。

注記: 時刻はちょうどの時（分 0、秒 0）で指定する必要があります。

型: string

例: 2017-05-26T07:00:00Z
start_time
必須		取得対象のデータを、ISO 8601 で表した指定の開始時刻からに限定します。

注記: 時刻はちょうどの時（分 0、秒 0）で指定する必要があります。

型: string

例: 2017-05-19T07:00:00Z

​
リクエスト例

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26

​
レスポンス例

    {
      "request": {
        "params": {
          "campaign_ids": [
            "8fgzf"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "8fgzf",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​
GET stats/accounts/:account_id/reach/funding_instruments

指定したファンディングインスツルメントのリーチと平均フリークエンシーの分析指標を取得します。

​
リソースURL

https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments

​
パラメータ

名前説明
account_id
必須		利用対象アカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
funding_instrument_ids
必須		識別子のカンマ区切りリストを指定して、目的のファンディングインストゥルメントのみにレスポンスを絞り込みます。最大 20 個の ID を指定できます。

注記: 最大 20 個のファンディングインストゥルメント ID を指定できます。

Type: string

Example: lygyi
end_time
必須		取得データを、ISO 8601 で表現された指定の終了時刻に限定します。

注記: 時刻はちょうどの時間（0 分 0 秒）で表現する必要があります。

Type: string

Example: 2017-05-26T07:00:00Z
start_time
必須		取得データを、ISO 8601 で表現された指定の開始時刻に限定します。

注記: 時刻はちょうどの時間（0 分 0 秒）で表現する必要があります。

Type: string

Example: 2017-05-19T07:00:00Z

​
リクエスト例

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2017-05-19&end_time=2017-05-26

​
レスポンスの例

    {
      "request": {
        "params": {
          "funding_instrument_ids": [
            "lygyi"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "lygyi",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​
同期アナリティクス

​
GET stats/accounts/:account_id

現在のアカウントの同期アナリティクスを取得します。指定できる時間範囲（end_time - start_time）の上限は7日です。

​
リソースURL

https://ads-api.x.com/12/stats/accounts/:account_id

​
パラメータ

名前説明
account_id
必須		対象（レバレッジ）アカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須です。指定のアカウントは認証済みユーザーに紐づいている必要があります。

Type: string

Example: 18ce54d4x5t
end_time
必須		取得対象のデータを指定した終了時刻までに限定します。ISO 8601 で指定します。

注: 時刻は正時（分・秒が 0）で指定する必要があります。

Type: string

Example: 2017-05-26T07:00:00Z
entity
必須		データを取得するエンティティの種類。

Type: enum

Possible values: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids
必須		データを取得する特定のエンティティ。カンマ区切りのエンティティ id のリストを指定します。

注: 最大 20 個のエンティティ id を指定できます。

Type: string

Example: 8u94t
granularity
必須		取得するデータの粒度を指定します。

Type: enum

Possible values: DAY, HOUR, TOTAL
metric_groups
必須		返すメトリクスのグループ。カンマ区切りでメトリクスグループを指定します。詳細は Metrics and Segmentation を参照してください。

注: MOBILE_CONVERSION のデータは個別にリクエストしてください。

Type: enum

Possible values: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement
必須		取得対象のデータを特定のプレースメントに限定します。

注: 1 リクエストにつき指定できる値は 1 つのみです。X と X Audience Platform の両方のプレースメントを持つエンティティは、各プレースメントごとに個別のリクエストが必要です。

Type: enum

Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time
必須		取得対象のデータを指定した開始時刻からに限定します。ISO 8601 で指定します。

注: 時刻は正時（分・秒が 0）で指定する必要があります。

Type: string

Example: 2017-05-19T07:00:00Z

​
リクエストの例

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT

​
レスポンス例

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "8u94t",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  1233
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": null,
                "likes": [
                  1
                ],
                "engagements": [
                  58
                ],
                "clicks": [
                  58
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2017-05-19T07:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "8u94t"
          ],
          "end_time": "2017-05-26T07:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​
有効なエンティティ

​
GET stats/accounts/:account_id/active_entities

指定した期間内に、どのエンティティのアナリティクス指標に変更があったかの詳細を取得します。 このエンドポイントはアナリティクス関連のエンドポイントと併用してください。本エンドポイントの結果は、どの広告エンティティについてアナリティクスを取得すべきかを示します。利用ガイドラインは Active Entities Guide を参照してください。 変更イベントは1時間単位のバケットで提供されます。
  • start_time および end_time は、照会対象の時間バケットを指定します。
  • 返される data 配列には、後続のアナリティクスリクエストに含めるべき各エンティティのオブジェクトが含まれます。
  • 重要: 後続のアナリティクスリクエストで指定すべき日付は、activity_start_time および activity_end_time に基づいて決定してください。
    • これらの値は、保存された変更イベントが適用される時間範囲を表します。これはエンティティごとに返されます。
注: 許可される最大の時間範囲（end_time - start_time）は90日です。

​
リソースURL

https://ads-api.x.com/12/stats/accounts/:account_id/active_entities

​
パラメーター

名前説明
account_id
必須		利用対象のアカウント識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは、認証済みユーザーに紐づいている必要があります。

型: string

例: 18ce54d4x5t
end_time
必須		取得するデータの範囲を、ISO 8601 で表現された指定の終了時刻までに限定します。

注: 時刻はちょうどの時間（分・秒が 0）で指定する必要があります。

型: string

例: 2017-05-26T07:00:00Z
entity
必須		データ取得対象のエンティティ種別。

型: enum

可能な値: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time
必須		取得するデータの範囲を、ISO 8601 で表現された指定の開始時刻からに限定します。

注: 時刻はちょうどの時間（分・秒が 0）で指定する必要があります。

型: string

例: 2017-05-19T07:00:00Z
campaign_ids
任意		識別子のカンマ区切りリストを指定して、対象のキャンペーンに関連付けられたエンティティのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。

注: funding_instrument_ids および line_item_ids と同時に指定することはできません。

型: string

例: 8wku2
funding_instrument_ids
任意		識別子のカンマ区切りリストを指定して、対象のファンディングインストゥルメントに関連付けられたエンティティのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。

注: campaign_ids および line_item_ids と同時に指定することはできません。

型: string

例: lygyi
line_item_ids
任意		識別子のカンマ区切りリストを指定して、対象のラインアイテムに関連付けられたエンティティのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。

注: campaign_ids および line_item_ids と同時に指定することはできません。

型: string

例: 8v7jo

​
リクエスト例

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01

​
レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-02-28T08:00:00Z",
          "end_time": "2019-03-01T08:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2mvb28",
          "activity_start_time": "2019-02-28T01:30:07Z",
          "activity_end_time": "2019-03-01T07:42:55Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        },
        {
          "entity_id": "2mvb29",
          "activity_start_time": "2019-02-27T11:30:07Z",
          "activity_end_time": "2019-03-01T07:42:50Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2mvfan",
          "activity_start_time": "2019-02-27T09:00:05Z",
          "activity_end_time": "2019-03-01T06:06:36Z",
          "placements": [
            "PUBLISHER_NETWORK"
          ]
        },
        {
          "entity_id": "2n17dx",
          "activity_start_time": "2019-02-28T02:02:26Z",
          "activity_end_time": "2019-03-01T07:52:44Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }