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

​
はじめに

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

​
詳細

​
同期処理と非同期処理

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

​
ユースケース

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

​
リクエストオプション

Analytics リクエストは広告アカウント単位でスコープされるため、リソースパスにアカウント ID が必要です。以下のリクエストオプションは query パラメータとして指定します。必要な値の種類は次のとおりです。
  • Entities: エンティティの種類と、Analytics を取得したい最大 20 個のエンティティの id
  • Time range: ISO 8601 で表現された開始時刻と終了時刻
    • Note: 時刻は 1 時間単位（ちょうどの時刻）で指定する必要があります
  • Metric groups: 関連する metrics の 1 つ以上のセット（各 metric group に含まれる metrics の一覧は「Metrics and Segmentation」を参照）
  • Granularity: metrics を返す集計レベルを指定
  • Placement: X のオンサイト配信かオフサイト配信か、どちらの広告について metrics を取得するかを指定
    • Note: リクエストごとに指定できる placement は 1 つのみです
start_time と end_time リクエストパラメータで時間範囲を指定します。これらの値は、次のとおり指定した granularity に合わせる必要があります。
  1. TOTAL: 任意の時間範囲を指定可能（endpoint の制限内）
  2. DAY: 開始時刻・終了時刻の双方を、アカウントのタイムゾーンの真夜中（00:00）に揃える必要があります
  3. HOUR: 任意の時間範囲を指定可能（endpoint の制限内）
終了時刻は排他的です。例: start_time=2019-01-01T00:00:00Z と end_time=2019-01-02T00:00:00Z を指定した場合、この時間範囲は 24 時間のみをカバーするため、返される analytics の metrics は 1 日分（2 日分ではありません）になります。 Segmentation 非同期の analytics endpoint でのみ利用可能な segmentation により、パートナーや広告主は特定のターゲティング値ごとに分解された metrics を取得できます。セグメント化された metrics を取得するには、segmentation_type リクエストパラメータを使用してください。segmentation のオプションの詳細は、Metrics and Segmentation を参照してください。

​
よくある質問

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

​
ベストプラクティス

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

​
レートリミットと再試行

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

​
分析用metricsの概要

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

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

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

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

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

​
過去データの取得

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

​
サンプル

これらのベストプラクティスの一部を示すサンプルスクリプト（fetch_stats）は、当社の ads-platform-tools GitHub リポジトリでご覧いただけます。

​
目的別メトリクス

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

​
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
視聴単価billed_charge_local_micro/video_total_views

​
VIDEO_VIEWS_PREROLL

該当メトリクスグループ: ENGAGEMENT、BILLING、VIDEO
派生メトリクス公開メトリクスの算出方法
CPMbilled_charge_local_micro/impressions/1000
ビデオレートvideo_total_views/impressions
視聴単価（CPV）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 セクションを参照してください。

​
metrics グループごとの利用可能な metrics

​
ENGAGEMENT

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

​
BILLING

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

​
VIDEO

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

​
MEDIA

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

​
WEB_CONVERSION

指標説明セグメンテーションの可否データ型
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_CREDIT タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_installsINSTALL タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_content_viewsCONTENT_VIEW タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_add_to_wishlistsADD_TO_WISHLIST タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_checkouts_initiatedCHECKOUT_INITIATED タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_reservationsRESERVATION タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_tutorials_completedTUTORIAL_COMPLETED タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_achievements_unlockedACHIEVEMENT_UNLOCKED タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_searchesSEARCH タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_add_to_cartsADD_TO_CART タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_payment_info_additionsPAYMENT_INFO_ADDITION タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_re_engagesRE_ENGAGE タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_sharesSHARE タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_ratesRATE タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_loginsLOGIN タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_updatesUPDATE タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_levels_achievedLEVEL_ACHIEVED タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_invitesINVITE タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_key_page_viewsKEY_PAGE_VIEW タイプのモバイルコンバージョンの内訳（post_view と post_engagement 別）✔JSON オブジェクト
mobile_conversion_downloadsDOWNLOAD タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_purchasesPURCHASE タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_sign_upsSIGN_UP タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト
mobile_conversion_site_visitsSITE_VISIT タイプのモバイルコンバージョンの内訳（post_view、post_engagement、assisted、order_quantity、sale_amount 別）✔JSON オブジェクト

​
LIFE_TIME_VALUE_MOBILE_CONVERSION

MACT が有効化された広告主アカウントでのみ、ライフタイムのモバイルコンバージョン統計を利用できます。
Metric説明セグメンテーションの可否データ型
mobile_conversion_lifetime_value_purchasestype が PURCHASE のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_sign_upstype が SIGN_UP のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_updatestype が UPDATE のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_tutorials_completedtype が TUTORIAL_COMPLETED のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_reservationstype が RESERVATION のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_add_to_cartstype が ADD_TO_CART のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_add_to_wishliststype が ADD_TO_WISHLIST のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_checkouts_initiatedtype が CHECKOUT_INITIATED のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_levels_achievedtype が LEVEL_ACHIEVED のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_achievements_unlockedtype が ACHIEVEMENT_UNLOCKED のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_sharestype が SHARE のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_invitestype が INVITE のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_payment_info_additionstype が PAYMENT_INFO_ADDITION のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_spent_creditstype が SPENT_CREDIT のモバイルコンバージョンの内訳JSON オブジェクト
mobile_conversion_lifetime_value_ratestype が RATE のモバイルコンバージョンの内訳JSON オブジェクト

​
セグメンテーション

セグメンテーションレポートでは、特定のターゲティングtypeの各値ごとに分割したmetricsを取得できます。セグメンテーションは追加の複雑性が大きいため、非同期アナリティクスクエリでのみ利用可能です。 MEDIA_CREATIVE および ORGANIC_TWEET エンティティではセグメンテーションはサポートされません。 一部のセグメンテーションtypeでは、追加パラメータの指定が必要です。詳細は以下をご確認ください。 CITIES または POSTAL_CODES でセグメント化する場合、APIはターゲティングされたロケーションのみを返します。Region および Metro のセグメンテーションでは、ターゲティング済み・未ターゲティングの両方のロケーションが返されます。
セグメンテーションタイプ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

​
派生metrics

キャンペーンのmetricsは、キャンペーンの目的に依存します。本ガイドでは、設定されている目的に基づいて使用する派生metricsの計算方法を示します。 波かっこが付いていないmetricは、X Ads API のanalytics endpointから返されるものです。名前が{波かっこ}で囲まれている場合は、そのカテゴリの派生metricを示します。

​
エンゲージメント

派生指標公開指標の計算方法
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Total Engagements}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
{Engagement Rate}{Total Engagements} / {Impressions}
billed_charge_local_micro / {Total Engagements}
{Media Views}promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}{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
{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 目標を参照してください。その他のすべてのプレースメントについては、対応する派生metricsについて ENGAGEMENTS を参照してください。

​
ガイド

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

​
はじめに

Active Entities endpoint は、どのキャンペーンについて分析をリクエストすべきかを特定するための情報を提供するもので、当社の同期および非同期の分析用 endpoint と併用することを前提に設計されています。広告エンティティの詳細と、その metrics がいつ変化したかを返すことでこれを実現します。この endpoint を利用することで、コードおよび分析取得ロジックを大幅に簡素化できます。 本ガイドでは、当該 endpoint とその data ソースに関する情報と context を提供します。また、使用ガイドラインや一連のリクエスト例を示し、分析用 endpoint と組み合わせて Active Entities を活用する方法を解説します。概要セクションでは、推奨アプローチの要点を高レベルで説明します。

​
データ

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

​
endpoint

​
リクエスト

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。これは、当社の分析用 endpoint がサポートするエンティティ種別を反映しています。 start_time と end_time の値は ISO 8601 で表記し、どの1時間単位のバケットを query するかを指定する必要があります。これらは1時間単位のちょうどの時刻で指定する必要があります。 この endpoint は、結果をフィルタリングするために使用できる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 配列には、後続のアナリティクスリクエストに含める必要がある各エンティティに対応するオブジェクトが含まれます。このセットに含まれない ID についてアナリティクスをリクエストしてはいけません。 各オブジェクトには 4 つの fields が含まれます: entity_id、activity_start_time、activity_end_time、および placements。アクティビティの開始時刻と終了時刻は、関連するエンティティの変更イベントが適用される時間範囲を表しており、これに基づいて後続のアナリティクスリクエストで指定すべき日付が決まります。placements 配列には、ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND を含めることができます。これは、指定されたエンティティ ID に対してどの配置をリクエストすべきかを示します。

​
使用方法

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

​
概要

分析リクエストの行い方を定義するため、Active Entities の endpoint を以下の手順で使用します。アクティブなエンティティ情報をどの頻度で取得し、それに伴い分析をどの頻度で実行するかを決めたうえで、以下に従ってください。
  1. Active Entities へのリクエストを送信します。
  2. レスポンスを placement ごとに分割します。ALL_ON_TWITTER、PUBLISHER_NETWORK、SPOTLIGHT、TREND のそれぞれで1グループずつ作成します。
  3. 各 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 と一致するように時間範囲を選択してください。
注: 各時間ウィンドウは一度だけリクエストしてください。同じ時間ウィンドウを複数回リクエストすると、不要な分析リクエストが発生します（下記の例外を除く）。
現在の時間内に、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時間バケットに対して query を実行します。これはこのユースケースでは必要です。ただし、現在の時間を過ぎた後は、この1時間バケットに対しては query を実行しないでください。

​
アクティビティ時刻

アクティビティの開始時刻と終了時刻の扱い方として、次の方法を推奨します。Active Entities のレスポンス内のすべてのオブジェクトから、最小の activity_start_time と最大の activity_end_time を特定します。これらの値は、最小の開始時刻を切り下げ、最大の終了時刻を切り上げる形で調整します。具体的には、両方のタイムスタンプの時分秒を 00 にし、終了時刻に 1 日を加えます。以下の表のとおりです。これらが、以降のアナリティクスリクエストで指定すべき開始時刻・終了時刻となります。
最小・最大のアクティビティ時刻導出時刻
2019-03-04T20:55:20Z

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

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

​
例

このセクションでは、Active Entities を同期型の analytics endpoint と併用する方法を説明します。（可読性のため、レスポンスは一部調整しています。）この例では、Active Entities endpoint を各時刻のちょうど00分に呼び出し、各リクエストでは直前の1時間を対象とします。レスポンスの内容によって、同期型の analytics endpoint の使用方法が決まります。 最初の Active Entities リクエストは 03:00:00 に実行されます。レスポンスは、line item dvcz7 の metrics に変更があり、その変更イベントが 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 に設定されます。以下の metrics 配列では、各配列の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回だけリクエストしてください。レスポンスによれば、このラインアイテムの変更イベントは 02:00:00 と 03:00:00 の両方に適用されます。続くアナリティクスリクエストでは、両方の時間帯の変更が確認できるはずです。 
`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 に非ゼロの metrics が確認できるだけでなく、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 の1時間にのみ適用されることが示されています。続くリクエストでの analytics metrics の変化はその内容を反映しています。 
`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 の時間帯の metrics のみが変更されていることが示されています。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 時点で追加の変更イベントがないことが確認できます。注: ただし、これはこのラインアイテムの metrics が今後変更されないことを意味するわけではありません。 
`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 リファレンス

​
非同期分析

​
はじめに

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

​
使用方法

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

​
例

このセクションでは、非同期分析のendpointの使い方を説明します。 まず、POST stats/jobs/accounts/:account_id endpoint を使ってジョブを作成します。以下の例では、特定のラインアイテムについて、1週間の期間にわたり、impressions、like、クリックなどのエンゲージメントmetricsをリクエストしています。（指定した期間は、タイムスタンプが午前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"
        ]
      }
    }
このレスポンスはラインアイテムのmetricsを返しません。作成したジョブに関する情報のみを提供します。ジョブのステータスを確認するにはジョブ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
    サイズ: 381 [application/gzip]
    保存先: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

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

    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

​
Parameters

NameDescription
account_id
必須		レバレッジドアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
campaign_ids
必須		カンマ区切りの識別子リストを指定して、レスポンスを対象のキャンペーンのみに絞り込みます。最大 20 個の ID を指定できます。

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

Type: string

Example: 8fgzf
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/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

​
Parameters

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

Type: string

Example: 18ce54d4x5t
funding_instrument_ids
必須		識別子をカンマ区切りで指定し、対象の資金手段のみにレスポンスを絞り込みます。最大 20 個の ID を指定できます。

注: 資金手段 ID は最大 20 個まで指定可能です。

Type: string

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

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

Type: string

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

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

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
必須		取得対象の data を、ISO 8601 で表現された指定の終了時刻に限定します。

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

Type: string

Example: 2017-05-26T07:00:00Z
entity
必須		data を取得する対象のエンティティ種別。

Type: enum

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

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

Type: string

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

Type: enum

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

注: MOBILE_CONVERSION の data は別途リクエストしてください。

Type: enum

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

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

Type: enum

Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time
必須		取得対象の data を、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

指定した期間に、どのエンティティの分析用 metrics に変更があったかの詳細を取得します。 この endpoint は、当社の分析用 endpoint と併用してください。本 endpoint の結果は、分析を取得すべき広告エンティティを示します。使用ガイドラインは Active Entities Guide を参照してください。 変更イベントは1時間ごとのバケットで提供されます。
  • start_time と end_time の値は、どの1時間バケットを query するかを指定します。
  • 返される 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 リクエストで一般的に必須のパラメーターです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。

Type: string

Example: 18ce54d4x5t
end_time
必須		取得対象の data を、指定した終了時刻までに限定します。時刻は ISO 8601 で表現します。

Note: 分・秒が 0 の「時」単位で指定する必要があります。

Type: string

Example: 2017-05-26T07:00:00Z
entity
必須		data を取得する対象のエンティティ種別。

Type: enum

Possible values: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time
必須		取得対象の data を、指定した開始時刻以降に限定します。時刻は ISO 8601 で表現します。

Note: 分・秒が 0 の「時」単位で指定する必要があります。

Type: string

Example: 2017-05-19T07:00:00Z
campaign_ids
任意		識別子をカンマ区切りで指定することで、目的のキャンペーンに関連付けられたエンティティのみにレスポンスを限定します。最大 200 個の ID を指定できます。

Note: funding_instrument_ids および line_item_ids と同時には指定できません。

Type: string

Example: 8wku2
funding_instrument_ids
任意		識別子をカンマ区切りで指定することで、目的のファンディングインストゥルメントに関連付けられたエンティティのみにレスポンスを限定します。最大 200 個の ID を指定できます。

Note: campaign_ids および line_item_ids と同時には指定できません。

Type: string

Example: lygyi
line_item_ids
任意		識別子をカンマ区切りで指定することで、目的のラインアイテムに関連付けられたエンティティのみにレスポンスを限定します。最大 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": "プロモーション済み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": [
            "Xのすべての面",
          ]
        },
        {
          "entity_id": "2mvb29",
          "activity_start_time": "2019-02-27T11:30:07Z",
          "activity_end_time": "2019-03-01T07:42:50Z",
          "placements": [
            "Xのすべての面",
            "パブリッシャー・ネットワーク",
          ]
        },
        {
          "entity_id": "2mvfan",
          "activity_start_time": "2019-02-27T09:00:05Z",
          "activity_end_time": "2019-03-01T06:06:36Z",
          "placements": [
            "パブリッシャー・ネットワーク",
          ]
        },
        {
          "entity_id": "2n17dx",
          "activity_start_time": "2019-02-28T02:02:26Z",
          "activity_end_time": "2019-03-01T07:52:44Z",
          "placements": [
            "Xのすべての面",
            "パブリッシャー・ネットワーク"
          ]
        }
      ]
    }
⌘I