アナリティクス

概要

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

詳細

同期処理と非同期処理

同期処理エンドポイントと非同期処理エンドポイントの違いを、次の表にまとめています。どのエンドポイント群を使用するかを開発者が選択する際の参考情報です。

機能	同期処理	非同期処理
レート制限	ユーザーレベル: 15 分あたり 250 リクエスト	アカウントレベル: 同時実行ジョブ数 100 件*
期間	7 日間	90 日間 (セグメントなし) 45 日間 (セグメントあり)
セグメンテーション	なし	あり
レスポンスで返される内容	メトリクスデータ	ジョブの処理状態**
推奨ユースケース	リアルタイム最適化ユーザーインターフェースからのリクエスト	定期的な同期処理過去データのバックフィル

任意の時点で同時に「処理中」状態になれるジョブの最大数を指します。

** ジョブの処理が正常に完了すると、URL が返されます。この URL から、圧縮 (gzip) された結果ファイルをダウンロードできます。それ以外の点では、これらのエンドポイントは同じ機能を提供します。

ユースケース

主なアナリティクスのユースケースは 3 つあります。

リアルタイム最適化: パフォーマンス指標を用いて、配信中のキャンペーンを更新する
同期処理: 定期的に実行されるバックグラウンド同期
新規アカウントのオンボーディング: 過去データの補完

同期アナリティクスエンドポイントは、直近 5～15 分以内の指標変化に基づいてキャンペーンを更新するリアルタイム最適化に使用できます。アナリティクスの同期処理には、どちらのエンドポイントも使用できます。必要な時間範囲とセグメンテーションの要否によって、どちらのエンドポイントを使うべきかが決まります。新規アカウントのオンボーディングは、非同期アナリティクスエンドポイントのみを使用して行ってください。 (同期アナリティクスエンドポイントは、大量データの取得には決して使用しないでください。) 非同期アナリティクスエンドポイントは、メトリクスをバックエンドプロセスで同期することで、ダッシュボードやその他の UI 要素を構築できます。実装では、UI のリクエストを処理する目的で非同期アナリティクスエンドポイントを呼び出すことは避けてください。

リクエストオプション

Analytics リクエストは広告アカウント単位でスコープされるため、リソースパス内にアカウント ID が必要です。以下に示すリクエストオプションはクエリパラメータとして指定します。次の種類の値が必要です。

Entities: 分析を取得したいエンティティの entity type と、対象とする最大 20 個のエンティティ id
Time range: ISO 8601 形式で指定する開始時刻と終了時刻
- Note: 1 時間単位の値で指定する必要があります
Metric groups: 関連するメトリクスの 1 つ以上のセット (各 metric group に含まれるメトリクス一覧は「Metrics and Segmentation」を参照)
Granularity: メトリクスがどの集計レベルで返されるかを指定します
Placement: メトリクスを、X 上で配信された広告か、X 外で配信された広告かのどちらに対して取得するかを指定します
- Note: 1 回のリクエストで指定できる placement の値は 1 つだけです

start_time と end_time リクエストパラメータを使用して、タイムレンジを指定します。これらの値は、以下のように指定した granularity と整合している必要があります。

TOTAL: 任意のタイムレンジを指定できます (エンドポイントの制限内)
DAY: start time と end time の両方の値は、アカウントのタイムゾーンにおける午前 0 時に揃えて指定する必要があります
HOUR: 任意のタイムレンジを指定できます (エンドポイントの制限内)

end time は排他的です。たとえば、start_time=2019-01-01T00:00:00Z と end_time=2019-01-02T00:00:00Z を指定したリクエストでは、このタイムレンジが 24 時間のみをカバーするため、2 日分ではなく 1 日分の analytics メトリクスのみが返されます。 Segmentation Segmentation は非同期 analytics エンドポイントでのみ利用可能で、パートナーや広告主が特定のターゲティング値ごとに分割されたメトリクスを取得できるようにします。セグメント化されたメトリクスをリクエストするには、segmentation_type リクエストパラメータを使用します。セグメンテーションオプションの詳細については、Metrics and Segmentation を参照してください。

FAQ

なぜ Ads API の数値は X Ads の UI に表示されるものと一致しないのですか？

ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND のすべてのプレースメントについてデータをリクエストしていることを確認してください。
Ads API における終了時刻は「排他的」ですが、Ads UI では「包括的」であることを忘れないでください。

なぜデータをリクエストするタイミングによって数値が変わるのですか？

レポート用指標が利用可能になり次第、取得できるようになります。これらはほぼリアルタイムで利用可能です。ただし、これらの初期結果は推定値であり、その結果として変動することが想定されています。支出データを除き、指標は 24 時間後に確定します。
支出に関する指標は、一般的にイベント発生から 3 日以内に確定します。ただし、請求データは (スパムフィルタリングなどの理由により) イベント発生日から最大 14 日間にわたって処理されます。

特定の期間について、どのエンティティ ID をリクエストすべきかをどのように判断できますか？

Active Entities エンドポイントを使用してください。

なぜ 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 からアナリティクスデータを収集する際のベストプラクティスです。

レート制限とリトライ

レート制限が適用されたリクエスト (HTTP 429 ステータスコードを返すもの) では、x-rate-limit-reset ヘッダーを確認し、指定された時刻以降にのみリトライする必要があります。
HTTP 503 Service Unavailable ステータスコードが返されたリクエストでは、retry-after ヘッダーを確認し、指定された時刻以降にのみリトライする必要があります。
指定されたリトライ時刻を守らないアプリケーションは、予告なく Ads API へのアクセスを取り消されたり、スロットルされたりする可能性があります。

アナリティクス指標の概要

すべてのアナリティクス指標は、billed_charge_local_micro を除いて、24時間後には値が固定され、それ以降は変更されません。
billed_charge_local_micro 指標は、データが返された時点から最大3日間は推定値として報告されます。
24時間経過後、この指標は、過剰配信 (指定した end_time 以降に配信された広告) に対するクレジットや、無効と判断された課金対象イベントに対するクレジットにより減少することがあります。この指標は24時間以降はごくわずかしか変化しません。
詳細については、Analytics を参照してください。

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

start_time と end_time の両方を常に指定してください。
7 日より前のエンティティについてはデータを取得しないでください。
可能であれば HOUR 粒度でデータをリクエストしてください。DAY や TOTAL 粒度が必要な場合は、常に集計してメトリクスをロールアップできます。
可能であれば line_items および promoted_tweets レベルでデータをリクエストしてください。キャンペーン、funding instrument、アカウントレベルなど、広告エンティティ階層全体の合計値が必要な場合は、これらのメトリクスを集計してロールアップできます。
分析メトリクスの値は、ローカル環境側で保存・保管してください。
30 日より前のデータを繰り返しリクエストしないでください。このデータは変化せず、ローカルに保存しておくべきです。
すべての非セグメント化データはリアルタイムであり、イベント発生から数秒以内に利用できるようになります。
コンバージョンメトリクスと非コンバージョンメトリクスは、別々のリクエストに分けてください。

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

上記の「リアルタイムの非セグメント化データの取得」に関するガイドラインを参照してください。追加の注意点を以下に記載します。
ほとんどのセグメント化データの種別では、データが最大1時間程度完全でない場合があります。INTERESTS でセグメント化されたデータは、最大12時間まで遅延する可能性があります。
セグメント化データは、その情報の算出方法により、非セグメント化データと100%一致するように集計されることは想定されていません。

過去データの取得

バックフィル (例: 新しい広告主アカウントを追加する場合) を行うときは、start_time と end_time で指定する期間をより小さなチャンクに分割して、複数回に分けてリクエストする必要がある場合があります。
取得対象の期間は、30 日間のウィンドウに制限してください。
これらのリクエストはレートを調整し、時間的に分散させて、これらの取得に対するレート制限の上限に達しないようにしてください。

サンプル

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

目的別の指標

どの指標をエンティティに適用できるかは、キャンペーンの目的によって異なります。このガイドを使用して、各目的の種類ごとに取得すべき関連する指標グループと、追加の派生指標の算出方法を確認してください。

`ENGAGEMENTS`

関連するメトリクスグループ：ENGAGEMENT と BILLING。クリエイティブにメディアが使用されている場合は MEDIA も該当します。


派生メトリクス	公開メトリクスの計算方法
エンゲージメント率	`engagements/impressions`
CPE	`billed_charge_local_micro/engagements`
メディアビュー率	`media_views/impressions`

`WEBSITE_CLICKS` と `WEBSITE_CONVERSIONS`

関連するメトリクスグループ：ENGAGEMENT、BILLING、WEB_CONVERSION。クリエイティブでメディアが使用されている場合は MEDIA も該当します。


派生メトリクス	公開メトリクスの計算式
CPM	`billed_charge_local_micro/impressions/1000`
クリック率	`clicks/impressions`
CPLC	`billed_charge_local_micro/clicks`
合計コンバージョン数	`conversion_custom` + `conversion_site_visits` + `conversion_sign_ups` + `conversion_downloads` + `conversion_purchases`
コンバージョン率	合計コンバージョン数 / `impressions`
CPA	`billed_charge_local_micro` / 合計コンバージョン数

`APP_INSTALLS` および `APP_ENGAGEMENTS`

関連するメトリクスグループ：ENGAGEMENT、BILLING、MOBILE_CONVERSION、LIFE_TIME_VALUE_MOBILE_CONVERSION。クリエイティブでメディアまたは動画アプリカードを使用している場合は、MEDIA と VIDEO も対象になります。


派生メトリクス	公開メトリクスに基づく計算式
CPM	`billed_charge_local_micro/impressions/1000`
アプリクリック率	`app_clicks/impressions`
CPAC	`billed_charge_local_micro/app_clicks`
CPI	`billed_charge_local_micro/mobile_conversion_installs`

`FOLLOWERS`

関連する指標グループ：ENGAGEMENT と BILLING。クリエイティブにメディアが含まれる場合は MEDIA も適用されます。


派生指標	公開指標に基づく計算
CPM	`billed_charge_local_micro/impressions/1000`
フォロー率	`follows/impressions`
CPF	`billed_charge_local_micro/follows`
メディア視聴率	`media_views/impressions`

`LEAD_GENERATION`

関連するメトリックグループ：ENGAGEMENT と BILLING。クリエイティブでメディアを使用する場合は MEDIA も該当します。


派生メトリック	公開メトリックの計算式
CPM	`billed_charge_local_micro/impressions/1000`
リード数	`card_engagements`
リード率	`card_engagements/impressions`
リード単価	`billed_charge_local_micro/card_engagements`

`VIDEO_VIEWS`

関連メトリックグループ：ENGAGEMENT、BILLING、VIDEO


派生メトリック	公開メトリックの算出式
CPM	`billed_charge_local_micro/impressions/1000`
動画再生率	`video_total_views/impressions`
視聴単価	`billed_charge_local_micro/video_total_views`

`VIDEO_VIEWS_PREROLL`

関連するメトリックグループ：ENGAGEMENT、BILLING、VIDEO


派生メトリック	公開メトリックの算出式
CPM	`billed_charge_local_micro/impressions/1000`
動画視聴率	`video_total_views/impressions`
動画視聴単価	`billed_charge_local_micro/video_total_views`

メトリクスとセグメンテーション

このドキュメントでは、各エンティティタイプごとに Analytics から取得できるメトリクスの概要と、各メトリクスで利用可能なセグメンテーションについて説明します。


	メトリクスグループ
エンティティ	`ENGAGEMENT`	`BILLING`	`VIDEO`	`MEDIA`	`WEB_CONVERSION`	`MOBILE_CONVERSION`	`LIFE_TIME_VALUE_MOBILE_CONVERSION`
`ACCOUNT`	✔*
`FUNDING_INSTRUMENT`	✔*	✔
`CAMPAIGN`	✔	✔	✔	✔	✔	✔	✔
`LINE_ITEM`	✔	✔	✔	✔	✔	✔	✔
`PROMOTED_TWEET`	✔	✔	✔	✔	✔	✔	✔
`MEDIA_CREATIVE`	✔	✔	✔	✔	✔	✔	✔
`ORGANIC_TWEET`	✔		✔

*ENGAGEMENT メトリクスファミリーに含まれる一部のメトリクスは、ACCOUNT レベルおよび FUNDING_INSTRUMENT レベルでは利用できません。詳細については ENGAGEMENT セクションを参照してください。

メトリクスグループごとの利用可能なメトリクス

`ENGAGEMENT`


Metric	説明	セグメンテーション可否	データ型	アカウント / 資金源で利用可能
`engagements`	エンゲージメント合計数	✔	Array of ints	✔
`impressions`	インプレッション合計数	✔	Array of ints	✔
`retweets`	リツイート合計数	✔	Array of ints	✔
`replies`	返信合計数	✔	Array of ints	✔
`likes`	いいね合計数	✔	Array of ints	✔
`follows`	フォロー合計数	✔	Array of ints	✔
`card_engagements`	カードエンゲージメント合計数	✔	Array of ints
`clicks`	お気に入りなどその他のエンゲージメントを含むクリック合計数	✔	Array of ints
`app_clicks`	App のインストールまたは起動の試行回数	✔	Array of ints
url_clicks	広告内のリンクまたは Website Card へのクリック合計数 (獲得 (earned) 分を含む)	✔	Array of ints
`qualified_impressions`	有効インプレッション合計数	✔	Array of ints
`carousel_swipes`	カルーセル画像または動画のスワイプ合計数	✔	Array of ints

`BILLING`


Metric	説明	セグメンテーション可否	データ type
`billed_engagements`	課金対象となったエンゲージメントの総数	✔	int の配列
`billed_charge_local_micro`	マイクロ単位での合計支出額	✔	int の配列

`VIDEO`

動画メトリクス定義の変更に関するお知らせ: VIDEO メトリクスグループ内の video_total_views メトリクスは、MRC 標準に従い、少なくとも 2 秒間連続して 50%以上が視認範囲内にあるビューをカウントします。元の動画ビュー定義 (少なくとも 3 秒間、100% が視認範囲内) のメトリクスは、VIDEO メトリクスグループ内の新しい video_3s100pct_views メトリクスとして引き続き利用できます。元のビュー定義に基づいて入札および課金を継続するには、新たに利用可能な VIEW_3S_100PCT bid_unit を使用してください。


Metric	説明	セグメンテーション対応	データ型
`video_total_views`	動画ビューの合計数	✔	int の配列
`video_views_25`	動画の少なくとも 25% が再生されたビューの合計数	✔	int の配列
`video_views_50`	動画の少なくとも 50% が再生されたビューの合計数	✔	int の配列
`video_views_75`	動画の少なくとも 75% が再生されたビューの合計数	✔	int の配列
`video_views_100`	動画の 100% が再生されたビューの合計数	✔	int の配列
`video_cta_clicks`	コールトゥアクションへのクリックの合計数	✔	int の配列
`video_content_starts`	動画再生開始の合計数	✔	int の配列
`video_3s100pct_views`	少なくとも 3 秒間、100% が視認範囲内で再生されたビューの合計数 (従来の `video_total_views`)	✔	int の配列
`video_6s_views`	動画の少なくとも 6 秒間が再生されたビューの合計数	✔	int の配列
`video_15s_views`	動画の少なくとも 15 秒間、または総再生時間の 95% が再生されたビューの合計数	✔	int の配列

`MEDIA`


Metric	説明	セグメンテーションの有無	データ型
`media_views`	Videos、Vines、GIFs、Images にわたるメディアの表示回数 (自動再生およびクリック再生) の合計。	✔	int の配列
`media_engagements`	Videos、Vines、GIFs、Images にわたるメディアのクリック数の合計。	✔	int の配列

`WEB_CONVERSION`


Metric	説明	セグメンテーション可否	データ type
`conversion_purchases`	type が PURCHASE のコンバージョン数、そのコンバージョンに対応する売上金額および注文数量	`PLATFORMS` のみ	JSON オブジェクト
`conversion_sign_ups`	type が SIGN_UP のコンバージョン数、そのコンバージョンに対応する売上金額および注文数量	`PLATFORMS` のみ	JSON オブジェクト
`conversion_site_visits`	type が SITE_VISIT のコンバージョン数、そのコンバージョンに対応する売上金額および注文数量	`PLATFORMS` のみ	JSON オブジェクト
`conversion_downloads`	type が DOWNLOAD のコンバージョン数、そのコンバージョンに対応する売上金額および注文数量	`PLATFORMS` のみ	JSON オブジェクト
`conversion_custom`	type が CUSTOM のコンバージョン数、そのコンバージョンに対応する売上金額および注文数量	`PLATFORMS` のみ	JSON オブジェクト

`MOBILE_CONVERSION`

モバイルコンバージョンの指標は、MACT が有効になっている広告主アカウントでのみ利用できます。


指標	説明	セグメント化の可否	データ型
`mobile_conversion_spent_credits`	type が SPENT_CREDIT のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_installs`	type が INSTALL のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_content_views`	type が CONTENT_VIEW のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_add_to_wishlists`	type が ADD_TO_WISHLIST のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_checkouts_initiated`	type が CHECKOUT_INITIATED のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_reservations`	type が RESERVATION のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_tutorials_completed`	type が TUTORIAL_COMPLETED のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_achievements_unlocked`	type が ACHIEVEMENT_UNLOCKED のモバイルコンバージョンを、post_view、post_engagement、assisted、order_quantity、sale_amount ごとに集計した内訳	✔	JSON オブジェクト
`mobile_conversion_searches`	type SEARCH のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_add_to_carts`	type ADD_TO_CART のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_payment_info_additions`	type PAYMENT_INFO_ADDITION のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_re_engages`	type RE_ENGAGE のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_shares`	type SHARE のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_rates`	type RATE のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_logins`	type LOGIN のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_updates`	type UPDATE のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_levels_achieved`	type LEVEL_ACHIEVED のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に集計した内訳。	✔	JSON オブジェクト
`mobile_conversion_invites`	タイプ INVITE のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に分類した内訳	✔	JSON オブジェクト
`mobile_conversion_key_page_views`	タイプ KEY_PAGE_VIEW のモバイルコンバージョンを post_view および post_engagement 別に分類した内訳	✔	JSON オブジェクト
mobile_conversion_downloads	タイプ DOWNLOAD のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に分類した内訳	✔	JSON オブジェクト
mobile_conversion_purchases	タイプ PURCHASE のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に分類した内訳	✔	JSON オブジェクト
mobile_conversion_sign_ups	タイプ SIGN_UP のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に分類した内訳	✔	JSON オブジェクト
mobile_conversion_site_visits	タイプ SITE_VISIT のモバイルコンバージョンを post_view、post_engagement、assisted、order_quantity、sale_amount 別に分類した内訳	✔	JSON オブジェクト

`LIFE_TIME_VALUE_MOBILE_CONVERSION`

ライフタイムモバイルコンバージョンの統計は、MACT が有効になっている広告主アカウントでのみ利用できます。


Metric	説明	セグメンテーションの有無	データ type
`mobile_conversion_lifetime_value_purchases`	type PURCHASE のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_sign_ups`	type SIGN_UP のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_updates`	type UPDATE のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_tutorials_completed`	type TUTORIAL_COMPLETED のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_reservations`	type RESERVATION のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_add_to_carts`	type ADD_TO_CART のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_add_to_wishlists`	type ADD_TO_WISHLIST のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_checkouts_initiated`	type CHECKOUT_INITIATED のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_levels_achieved`	type LEVEL_ACHIEVED のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_achievements_unlocked`	type ACHIEVEMENT_UNLOCKED のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_shares`	type SHARE のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_invites`	type INVITE のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_payment_info_additions`	type PAYMENT_INFO_ADDITION のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_spent_credits`	type SPENT_CREDIT のモバイルコンバージョンの内訳		JSON オブジェクト
`mobile_conversion_lifetime_value_rates`	type RATE のモバイルコンバージョンの内訳		JSON オブジェクト

セグメンテーション

セグメンテーションのレポートでは、特定のターゲティングタイプの値ごとに分割されたメトリックを取得できます。セグメンテーションは、追加される複雑性が大きいため、非同期アナリティクスクエリでのみ利用可能です。セグメンテーションは、MEDIA_CREATIVE または ORGANIC_TWEET エンティティではサポートされていません。一部のセグメンテーションタイプでは、追加パラメータの指定が必要です。これらについては以下に記載します。 CITIES または POSTAL_CODES でセグメントする場合、API はターゲットに設定されたロケーションのみを返します。REGIONS および METROS によるセグメンテーションでは、ターゲットに設定されたロケーションとターゲットに設定されていないロケーションの両方が返されます。


セグメンテーションタイプ	`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 / {Impressions} / 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`
{エンゲージメント率}	`{Total Engagements} / {Impressions}`
`billed_charge_local_micro / {Total Engagements}`
{メディア再生数}	`promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views`
{メディア再生率}	`{Media Views} / {Impressions}`

WEBSITE_CLICKS


導出指標	公開指標の計算式
`promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions`
`billed_charge_local_micro / {Impressions} / 1000`
{Link Clicks}	`promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks`
{Click Rate}	`{Link Clicks} / {Impressions}`
`billed_charge_local_micro / {Link Clicks}`
`conversion_site_visits`
{Conversion Rate}	`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 / {Impressions} / 1000`
{App Clicks}	`promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks`
{App Click Rate}	`{App Clicks} / {Impressions}`
`billed_charge_local_micro / {App Clicks}`
`billed_charge_local_micro / mobile_conversion_installs`

フォロワー


導出指標	公開指標の算出式
`promoted_account_impressions`
`billed_charge_local_micro / {Impressions} / 1000`
`promoted_account_follows`
{フォロー率}	`promoted_account_follow_rate`
`billed_charge_local_micro / promoted_account_follows`
{メディア再生数}	`promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views`
{メディア再生率}	`{Media Views} / {Impressions}`

リード獲得


派生指標	メトリックの算出式
`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`
{有効インプレッション}	`promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions`
{有効インプレッション率}	`{Qualified Impressions} / {Impressions}`
{1,000有効インプレッション当たりのコスト }	`billed_charge_local_micro / {Qualified Impressions} / 1000`

CUSTOM

placement_type が PROMOTED_ACCOUNT の場合は、上記の FOLLOWERS オブジェクティブを参照してください。それ以外のすべてのプレースメントでこのオブジェクティブを使用する場合は、対応する派生メトリクスについて ENGAGEMENTS を参照してください。

ガイド

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

はじめに

Active Entities エンドポイントは、どのキャンペーンについてアナリティクスをリクエストすればよいかを判断するための情報を提供することを目的として、同期および非同期アナリティクスエンドポイントと組み合わせて使用するよう設計されています。広告エンティティの詳細と、そのメトリクスがいつ変化したかを返すことで、この目的を達成します。このエンドポイントを使用することで、コードおよびアナリティクス取得ロジックを大幅に簡素化できます。このガイドでは、このエンドポイントとそのデータソースに関する情報とコンテキストを提供します。また、利用ガイドラインと、Active Entities をアナリティクスエンドポイントと組み合わせて使用する方法を示す一連のリクエスト例も掲載しています。概要セクションでは、推奨されるアプローチの概要レベルの説明を提供します。

データ

広告エンティティのメトリクスが変更されるたびに、その変更に関する情報を記録します。これらの変更イベントは 1 時間単位のバケットに保存され、エンティティに関する詳細と、その変更が適用される時刻の両方が含まれます。後者が必要になるのは、変更イベントが常に記録した時刻と対応するとは限らないためです。請求の調整が一般的な理由ですが、その他にも理由があります。

エンドポイント

Request

Active Entities リクエストは広告アカウント配下にスコープされており、必須クエリパラメータ entity、start_time、end_time が 3 つあります。

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 type で機能します。

レスポンス

上記のリクエストに対する 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 配列には、後続のアナリティクスリクエストに含める必要がある各エンティティごとに 1 つのオブジェクトが含まれます。この集合に含まれない ID については、アナリティクスをリクエストしないでください。各オブジェクトには、entity_id、activity_start_time、activity_end_time、placements の 4 つのフィールドが含まれます。アクティビティの開始時刻と終了時刻は、関連するエンティティの変更イベントが適用される時間範囲を表しており、その結果として、後続のアナリティクスリクエストで指定すべき日付を決定します。placements 配列には、ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND の値を含めることができます。これは、対象のエンティティ ID について、どのプレースメントをリクエストすべきかを示します。

使用方法

Active Entities エンドポイントは、アナリティクスリクエストをどのように行うかを決定する基準となります。以下の利用ガイドラインは、アナリティクスの同期をサポートし、パートナーが自社のデータストアを Twitter と同期した状態に保てるようにするために記述されています。言い換えると、定期的にスケジュールされたバックグラウンド同期処理をどのように実行するかを説明しています。開発者は 2 つの点について判断する必要があります。

アクティブエンティティ情報をどのくらいの頻度でリクエストするか、そしてその結果としてアナリティクスをどのくらいの頻度で取得するか。
アクティビティの開始時刻と終了時刻をどのように使用して、アナリティクスリクエストの start_time および end_time の値を決定するか。

これらについては、以下の 2 つの小節で、概要の後にそれぞれより詳しく説明します。

まとめ

Active Entities エンドポイントを次のように使用して、分析リクエストの実行方法を決定します。アクティブなエンティティ情報をどの程度の頻度で取得するか、つまりどの程度の頻度で分析データを取得するかを決めたあとに、以下に従ってください。

Active Entities リクエストを送信します。
レスポンスを placement ごとに分割します。ALL_ON_TWITTER 用に 1 グループ、PUBLISHER_NETWORK 用に 1 グループ、SPOTLIGHT 用に 1 グループ、TREND 用に 1 グループ作成します。
各 placement グループに対して、次を実行します。
1. エンティティ ID を抽出します。
2. 分析用の start_time と end_time の値を決定します。
  - 最小の activity_start_time を取得し、この値を下方向に丸めます。
  - 最大の activity_end_time を取得し、この値を上方向に丸めます。
3. 分析リクエストを送信します。
  - エンティティ ID を 20 件ずつのバッチにまとめます。
  - 3b で求めた start_time と end_time の値を使用します。
  - 適切な placement の値を指定します。
4. データストアに書き込みます。

Python SDK を使用した例として、active_entities.py を参照してください。

頻度

最初の質問への回答によって、Active Entities リクエストで使用すべき時間範囲が決まります。たとえば、アクティブエンティティ情報を毎時取得する場合、時間範囲は 1 時間にする必要があります。アクティブエンティティ情報を 1 日に 1 回取得する場合、時間範囲は 1 日にする必要があります。言い換えると、現在のリクエストの start_time が直前のリクエストの end_time と等しくなるように時間範囲を選択する必要があります。

Note: 同じ時間ウィンドウは 1 回だけリクエストしてください。同じ時間ウィンドウを複数回リクエストすると、不要なアナリティクスリクエストが発生します (下記の例外を除きます) 。

パートナーが 現在の 1 時間の間に、同じ 1 時間の中で複数回アナリティクスをリクエストしたい場合も、同じパターンが適用されます。すなわち、頻度によって時間範囲が決まります。下の表は、このシナリオにおける Active Entities の start_time と end_time のタイムスタンプ例を示しています。


Request time	`start_time` timestamp	`end_time` timestamp
00:15:00	00:00:00	00:15:00
00:30:00	00:15:00	00:30:00
00:45:00	00:30:00	00:45:00
01:00:00	00:45:00	01:00:00

変更イベントの保存方法により、上記 4 つの Active Entities リクエストはすべて同じ 1 時間ごとのバケットをクエリしますが、このユースケースではそれが必要です。ただし、現在の時間が過ぎた後は、この 1 時間バケットを再度クエリするべきではありません。

アクティビティ時間

アクティビティの開始時刻と終了時刻を扱う際には、次の方法を推奨します。Active Entities レスポンス内のすべてのオブジェクトを対象に、最小の activity_start_time と最大の activity_end_time を探します。これらの値を、最小のアクティビティ開始時刻は切り下げ、最大のアクティビティ終了時刻は切り上げる形で丸めて調整します。具体的には、両方のタイムスタンプの時刻部分を 0 に設定し、終了時刻に 1 日を加えます。以下の表に例を示します。これが、その後のアナリティクスリクエストで指定すべき開始時刻と終了時刻になります。


Min, max activity times	Derived times
2019-03-04T20:55:20Z 2019-03-05T14:40:59Z	2019-03-04T00:00:00Z 2019-03-06T00:00:00Z

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

例

このセクションでは、Active Entities を同期型 analytics エンドポイントと組み合わせて使用する方法を示します (レスポンスは読みやすくするために一部変更されています) 。この例では、Active Entities エンドポイントは毎正時に呼び出され、それぞれのリクエストは直前の 1 時間を対象とします。レスポンスの内容に基づいて、同期型 analytics エンドポイントの使用方法が決まります。最初の Active Entities リクエストは 03:00:00 に行われます。レスポンスは、ラインアイテム 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"
          ]
        }
      ]
    }

これらのアクティビティの開始時刻と終了時刻に基づき、さらに上で説明した方法を用いると、アナリティクスの 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 時間分のみを対象とします。前述のとおり、各時間ウィンドウは 1 回だけリクエストする必要があります。レスポンスに基づくと、この line item に対する変更イベントは 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"
          ]
        }
      ]
    }

分析レスポンスを見ると、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,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 ページを参照してください。同期型エンドポイントとは異なり、レート制限は特定のアカウントに対して同時に実行できるジョブ数に基づきます。言い換えると、ある時点で処理中にできるジョブの数に基づきます。これは広告アカウント単位でカウントされます。

使用方法

非同期アナリティクスのエンドポイントを使ってキャンペーン指標を取得するには、複数のステップを踏む必要があります。ジョブを作成し、そのジョブの処理が完了したかどうかを確認し、最後にデータをダウンロードします。データファイルは解凍する必要があります。具体的な 4 つのステップは以下のとおりです。

POST stats/jobs/accounts/:account_id エンドポイントを使用してジョブを作成します。
ジョブの処理が完了したかどうかを判定するために、一定間隔で GET stats/jobs/accounts/:account_id エンドポイントにリクエストを送信します。
ジョブの処理が完了したら、データファイルをダウンロードします。
データファイルを解凍します。

データファイル内で返される response オブジェクトは、同期アナリティクスエンドポイントのレスポンスと同じ JSON スキーマを持ちます。セグメント化されたキャンペーン指標は、非同期アナリティクスエンドポイントからのみ取得できます。キャンペーン指標は、地域、性別、興味関心、キーワードなどで分割して取得できます。利用可能なオプションの完全な一覧については、指標とセグメンテーションページを参照してください。セグメント化された指標をリクエストするには、ジョブを作成する際に segmentation_type リクエストパラメータを使用します。

例

このセクションでは、非同期アナリティクスエンドポイントの使用方法を示します。まず、POST stats/jobs/accounts/:account_id エンドポイントを使用してジョブを作成します。以下の例では、特定のラインアイテムについて、1 週間分のインプレッション、いいね、クリックなどのエンゲージメント指標をリクエストしています。 (タイムスタンプが午前 0 時に設定されているため、指定した時間範囲は 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 および id_str の両方の属性として返されます。次に、前のレスポンスで返された id_str を使用して作成したジョブについて、レスポンス内に "status": "SUCCESS" が含まれており、処理が完了しているかどうかを確認します。これはデータをダウンロードできる状態になっていることを意味します。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 を渡していますが、実際には job_ids パラメータを使い、最大 200 個のジョブ ID を指定して、一度に複数のジョブのステータスを確認することをおすすめします。次に、表示されている 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
    Resolving ton.twimg.com (ton.twimg.com)... 72.21.91.70
    Connecting to ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 381 [application/gzip]
    Saving to: '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' saved [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

パラメーター

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
campaign_ids required	カンマ区切りの識別子のリストを指定することで、レスポンスを目的のキャンペーンのみに絞り込みます。最大 20 個の ID を指定できます。 Note: 最大 20 個のキャンペーン ID を指定できます。 Type: string Example: `8fgzf`
end_time required	取得するデータを、ISO 8601 で表現された指定の終了時刻までに限定します。 Note: 分と秒が 0 の「1 時間単位」で指定する必要があります。 Type: string Example: `2017-05-26T07:00:00Z`
start_time required	取得するデータを、ISO 8601 で表現された指定の開始時刻以降に限定します。 Note: 分と秒が 0 の「1 時間単位」で指定する必要があります。 Type: string Example: `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

指定した funding instrument のリーチおよび平均フリークエンシーに関する分析情報を取得します。

リソース URL

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

パラメーター

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストにおいて、通常は必須パラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
funding_instrument_ids required	カンマ区切りの識別子リストを指定することで、レスポンスを目的の資金手段のみに絞り込みます。最大 20 個の ID を指定できます。 Note: 最大 20 個の funding instrument ID を指定できます。 Type: string Example: `lygyi`
end_time required	取得するデータを、ISO 8601 で表現された指定の終了時刻に限定します。 Note: 時刻は 1 時間単位 (分および秒が 0) で指定する必要があります。 Type: string Example: `2017-05-26T07:00:00Z`
start_time required	取得するデータを、ISO 8601 で表現された指定の開始時刻に限定します。 Note: 時刻は 1 時間単位 (分および秒が 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

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
end_time required	取得するデータの範囲を、指定した終了時刻に制限します。ISO 8601 形式で指定します。 Note: 分・秒が 0 の、1 時間単位で指定する必要があります。 Type: string Example: `2017-05-26T07:00:00Z`
entity required	データを取得する対象のエンティティタイプ。 Type: enum Possible values: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `ORGANIC_TWEET`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`, `MEDIA_CREATIVE`
entity_ids required	データを取得する特定のエンティティを指定します。カンマ区切りの entity ID のリストを指定します。 Note: 最大 20 個の entity ID を指定できます。 Type: string Example: `8u94t`
granularity required	取得するデータの粒度を指定します。 Type: enum Possible values: `DAY`, `HOUR`, `TOTAL`
metric_groups required	返すメトリクスを指定します。カンマ区切りの metric group のリストを指定します。詳細については、Metrics and Segmentation を参照してください。 Note: `MOBILE_CONVERSION` データは別途リクエストする必要があります。 Type: enum Possible values: `BILLING`, `ENGAGEMENT`, `LIFE_TIME_VALUE_MOBILE_CONVERSION`, `MEDIA`, `MOBILE_CONVERSION`, `VIDEO`, `WEB_CONVERSION`
placement required	取得するデータの範囲を特定のプレースメントに制限します。 Note: リクエストごとに指定できる値は 1 つのみです。X と X Audience Platform の両方のプレースメントを持つエンティティの場合、プレースメント値ごとに 1 つずつ、個別のリクエストが必要です。 Type: enum Possible values: `ALL_ON_TWITTER`, `PUBLISHER_NETWORK`, `SPOTLIGHT`, `TREND`
start_time required	取得するデータの範囲を、指定した開始時刻に制限します。ISO 8601 形式で指定します。 Note: 分・秒が 0 の、1 時間単位で指定する必要があります。 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 の値で、クエリ対象とする 1 時間ごとのバケットを指定します。
返される data 配列には、その後のアナリティクスリクエストに含める必要がある各エンティティごとに 1 つのオブジェクトが含まれます。
重要: その後のアナリティクスリクエストで指定すべき日付は、activity_start_time および activity_end_time の値に基づいて決定してください。
- これらの値は、保存されている変更イベントが 適用される 期間を表します。これはエンティティごとに返されます。

注: 指定可能な最大の時間範囲 (end_time - start_time) は 90 日です。

リソース URL

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

パラメーター

Name	Description
account_id required	レバレッジドアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
end_time required	取得されるデータの範囲を、ISO 8601 で表現される指定の終了時刻に限定します。 Note: 分および秒が 0 の、1 時間単位で指定する必要があります。 Type: string Example: `2017-05-26T07:00:00Z`
entity required	データを取得する対象のエンティティタイプです。 Type: enum Possible values: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `MEDIA_CREATIVE`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`
start_time required	取得されるデータの範囲を、ISO 8601 で表現される指定の開始時刻に限定します。 Note: 分および秒が 0 の、1 時間単位で指定する必要があります。 Type: string Example: `2017-05-19T07:00:00Z`
campaign_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを希望するキャンペーンに関連付けられたエンティティのみに限定します。最大 200 個の ID を指定できます。 Note: `funding_instrument_ids` および `line_item_ids` と同時には指定できません。 Type: string Example: `8wku2`
funding_instrument_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを希望するファンディングインストルメントに関連付けられたエンティティのみに限定します。最大 200 個の ID を指定できます。 Note: `campaign_ids` および `line_item_ids` と同時には指定できません。 Type: string Example: `lygyi`
line_item_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを希望するラインアイテムに関連付けられたエンティティのみに限定します。最大 200 個の ID を指定できます。 Note: `campaign_ids` および `line_item_ids` と同時には指定できません。 Type: string Example: `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"
          ]
        }
      ]
    }

概要

詳細

同期処理と非同期処理

ユースケース

リクエストオプション

FAQ

ベストプラクティス

レート制限とリトライ

アナリティクス指標の概要

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

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

過去データの取得

サンプル

目的別の指標

ENGAGEMENTS

WEBSITE_CLICKS と WEBSITE_CONVERSIONS

APP_INSTALLS および APP_ENGAGEMENTS

FOLLOWERS

LEAD_GENERATION

VIDEO_VIEWS

VIDEO_VIEWS_PREROLL

メトリクスとセグメンテーション

メトリクスグループごとの利用可能なメトリクス

ENGAGEMENT

BILLING

VIDEO

MEDIA

WEB_CONVERSION

MOBILE_CONVERSION

LIFE_TIME_VALUE_MOBILE_CONVERSION

セグメンテーション

導出メトリクス

エンゲージメント

WEBSITE_CLICKS

APP_INSTALLS と APP_ENGAGEMENTS

フォロワー

リード獲得

VIDEO_VIEWS

QUALIFIED_IMPRESSIONS

CUSTOM

ガイド

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

はじめに

データ

エンドポイント

Request

レスポンス

使用方法

まとめ

頻度

アクティビティ時間

例

非同期処理ガイド

APIリファレンス

非同期アナリティクス

はじめに

使用方法

例

リーチと平均フリークエンシー

GET stats/accounts/:account_id/reach/campaigns

リソースURL

パラメーター

リクエスト例

レスポンス例

GET stats/accounts/:account_id/reach/funding_instruments

リソース URL

パラメーター

リクエスト例

レスポンス例

同期型アナリティクス

GET stats/accounts/:account_id

リソースURL

パラメーター

リクエスト例

レスポンスの例

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

GET stats/accounts/:account_id/active_entities

リソース URL

パラメーター

リクエスト例

`ENGAGEMENTS`

`WEBSITE_CLICKS` と `WEBSITE_CONVERSIONS`

`APP_INSTALLS` および `APP_ENGAGEMENTS`

`FOLLOWERS`

`LEAD_GENERATION`

`VIDEO_VIEWS`

`VIDEO_VIEWS_PREROLL`

`ENGAGEMENT`

`BILLING`

`VIDEO`

`MEDIA`

`WEB_CONVERSION`

`MOBILE_CONVERSION`

`LIFE_TIME_VALUE_MOBILE_CONVERSION`