概要
アナリティクス指標は、パートナーや広告主が X 上でプロモーションしているコンテンツのパフォーマンスを把握するのに役立ちます。これには、インプレッション数、クリック数、動画再生数、支出額などの情報が含まれます。さらに、パートナーや広告主は、リーチしたオーディエンスのさまざまなセグメントごとの詳細な指標を取得することができます。 Ads API では、キャンペーンパフォーマンスの詳細な指標を取得する方法として、同期処理と非同期処理の 2 つをサポートしています。同期型の analytics 呼び出しでは、要求した指標がレスポンス内で返されます。非同期型の analytics エンドポイントでは、関連する「ジョブ」の処理が完了した後、ダウンロード可能な結果ファイルとして要求した指標を取得できます。同期エンドポイントは短い期間の指定をサポートしており、リアルタイムでのキャンペーン最適化に最適です。非同期エンドポイントは、はるかに長い期間をサポートしており、より大量のデータ取得を想定しているため、レポーティングや履歴データのバックフィルを行う用途に適しています。詳細
同期処理と非同期処理
| 機能 | 同期処理 | 非同期処理 |
|---|---|---|
| レート制限 | ユーザーレベル: 15 分あたり 250 リクエスト | アカウントレベル: 同時実行ジョブ数 100 件* |
| 期間 | 7 日間 | 90 日間 (セグメントなし) 45 日間 (セグメントあり) |
| セグメンテーション | なし | あり |
| レスポンスで返される内容 | メトリクスデータ | ジョブの処理状態** |
| 推奨ユースケース | リアルタイム最適化 ユーザーインターフェースからのリクエスト | 定期的な同期処理 過去データのバックフィル |
- 任意の時点で同時に「処理中」状態になれるジョブの最大数を指します。
ユースケース
- リアルタイム最適化: パフォーマンス指標を用いて、配信中のキャンペーンを更新する
- 同期処理: 定期的に実行されるバックグラウンド同期
- 新規アカウントのオンボーディング: 過去データの補完
リクエストオプション
- 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: 任意のタイムレンジを指定できます (エンドポイントの制限内)
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
ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TRENDのすべてのプレースメントについてデータをリクエストしていることを確認してください。- Ads API における終了時刻は「排他的」ですが、Ads UI では「包括的」であることを忘れないでください。
- レポート用指標が利用可能になり次第、取得できるようになります。これらはほぼリアルタイムで利用可能です。ただし、これらの初期結果は推定値であり、その結果として変動することが想定されています。支出データを除き、指標は 24 時間後に確定します。
- 支出に関する指標は、一般的にイベント発生から 3 日以内に確定します。ただし、請求データは (スパムフィルタリングなどの理由により) イベント発生日から最大 14 日間にわたって処理されます。
- Active Entities エンドポイント を使用してください。
null なのですか？
- リクエストした期間中に、そのキャンペーンが配信されていなかった可能性が高いです。
- どのエンティティの、どの期間の analytics を取得すべきかを判断するために、Active Entities エンドポイント を使用してください。
null が表示されるのに、UI では 0 が表示されるのですか？
- UI ではこれらの値を 0 として表示していますが、値としては同等です。
- analytics では、
ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND(つまり X Audience Platform) というプレースメント値をサポートしています。
- はい。エンティティのステータスは analytics 指標の取得可否には影響しません。
- セグメント別データは、その情報の計算方法上、非セグメントのデータと 100% 一致する集計値になることは想定されていません。
- 複数ディメンションでのセグメント化 (マルチセグメンテーション) には対応していません。
ベストプラクティス
レート制限とリトライ
- レート制限が適用されたリクエスト (
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 |
メトリクスとセグメンテーション
| メトリクスグループ | |||||||
| エンティティ | 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
| 指標 | 説明 | セグメント化の可否 | データ型 |
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
| 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 を参照してください。
ガイド
アクティブなエンティティ
はじめに
データ
エンドポイント
Request
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 で機能します。
レスポンス
data 配列には、後続のアナリティクスリクエストに含める必要がある各エンティティごとに 1 つのオブジェクトが含まれます。この集合に含まれない ID については、アナリティクスをリクエストしないでください。
各オブジェクトには、entity_id、activity_start_time、activity_end_time、placements の 4 つのフィールドが含まれます。アクティビティの開始時刻と終了時刻は、関連するエンティティの変更イベントが適用される時間範囲を表しており、その結果として、後続のアナリティクスリクエストで指定すべき日付を決定します。placements 配列には、ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND の値を含めることができます。これは、対象のエンティティ ID について、どのプレースメントをリクエストすべきかを示します。
使用方法
- アクティブエンティティ情報をどのくらいの頻度でリクエストするか、そしてその結果としてアナリティクスをどのくらいの頻度で取得するか。
- アクティビティの開始時刻と終了時刻をどのように使用して、アナリティクスリクエストの
start_timeおよびend_timeの値を決定するか。
まとめ
- Active Entities リクエストを送信します。
- レスポンスを placement ごとに分割します。
ALL_ON_TWITTER用に 1 グループ、PUBLISHER_NETWORK用に 1 グループ、SPOTLIGHT用に 1 グループ、TREND用に 1 グループ作成します。 - 各 placement グループに対して、次を実行します。
- エンティティ ID を抽出します。
- 分析用の
start_timeとend_timeの値を決定します。- 最小の
activity_start_timeを取得し、この値を下方向に丸めます。 - 最大の
activity_end_timeを取得し、この値を上方向に丸めます。
- 最小の
- 分析リクエストを送信します。
- エンティティ ID を 20 件ずつのバッチにまとめます。
- 3b で求めた
start_timeとend_timeの値を使用します。 - 適切な
placementの値を指定します。
- データストアに書き込みます。
頻度
start_time が直前のリクエストの end_time と等しくなるように時間範囲を選択する必要があります。
Note: 同じ時間ウィンドウは 1 回だけリクエストしてください。同じ時間ウィンドウを複数回リクエストすると、不要なアナリティクスリクエストが発生します (下記の例外を除きます) 。
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 |
アクティビティ時間
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 |
DAY 粒度を指定した場合、このような時間範囲は受け付けられません。)
例
start_time および end_time の値はそれぞれ 2019-02-11T00:00:00Z と 2019-02-12T00:00:00Z に設定されます。以下の各メトリクス配列では 3 番目の要素がゼロ以外の値になっており、これはアクティブなエンティティ情報に基づいた期待どおりの結果です。
非同期処理ガイド
APIリファレンス
非同期アナリティクス
はじめに
使用方法
- POST stats/jobs/accounts/:account_id エンドポイントを使用してジョブを作成します。
- ジョブの処理が完了したかどうかを判定するために、一定間隔で GET stats/jobs/accounts/:account_id エンドポイントにリクエストを送信します。
- ジョブの処理が完了したら、データファイルをダウンロードします。
- データファイルを解凍します。
segmentation_type リクエストパラメータを使用します。
例
id および id_str の両方の属性として返されます。
次に、前のレスポンスで返された id_str を使用して作成したジョブについて、レスポンス内に "status": "SUCCESS" が含まれており、処理が完了しているかどうかを確認します。これはデータをダウンロードできる状態になっていることを意味します。url フィールドにはダウンロード用のリンクが含まれています。
job_ids パラメータを使い、最大 200 個のジョブ ID を指定して、一度に複数のジョブのステータスを確認することをおすすめします。
次に、表示されている url の値を使ってデータファイルをダウンロードします。
リーチと平均フリークエンシー
リソース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
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 |
リクエスト例
レスポンス例
同期型アナリティクス
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 |
リクエスト例
レスポンスの例
アクティブなエンティティ
start_timeとend_timeの値で、クエリ対象とする 1 時間ごとのバケットを指定します。- 返される
data配列には、その後のアナリティクスリクエストに含める必要がある各エンティティごとに 1 つのオブジェクトが含まれます。 - 重要: その後のアナリティクスリクエストで指定すべき日付は、
activity_start_timeおよびactivity_end_timeの値に基づいて決定してください。- これらの値は、保存されている変更イベントが 適用される 期間を表します。これはエンティティごとに返されます。
end_time - start_time) は 90 日です。
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