> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# アナリティクス
export const Button = ({href, children}) => {
return ;
};
## 概要
アナリティクス指標は、パートナーや広告主が X 上でプロモーションしているコンテンツのパフォーマンスを把握するのに役立ちます。これには、インプレッション数、クリック数、動画再生数、支出額などの情報が含まれます。さらに、パートナーや広告主は、リーチしたオーディエンスのさまざまなセグメントごとの詳細な指標を取得することができます。
Ads API では、キャンペーンパフォーマンスの詳細な指標を取得する方法として、同期処理と非同期処理の 2 つをサポートしています。同期型の analytics 呼び出しでは、要求した指標がレスポンス内で返されます。非同期型の analytics エンドポイントでは、関連する「ジョブ」の処理が完了した後、ダウンロード可能な結果ファイルとして要求した指標を取得できます。同期エンドポイントは短い期間の指定をサポートしており、リアルタイムでのキャンペーン最適化に最適です。非同期エンドポイントは、はるかに長い期間をサポートしており、より大量のデータ取得を想定しているため、レポーティングや履歴データのバックフィルを行う用途に適しています。
## 詳細
### 同期処理と非同期処理
同期処理エンドポイントと非同期処理エンドポイントの違いを、次の表にまとめています。どのエンドポイント群を使用するかを開発者が選択する際の参考情報です。
| 機能 | 同期処理 | 非同期処理 |
| :----------- | :---------------------------------- | :------------------------------------ |
| レート制限 | ユーザーレベル: 15 分あたり 250 リクエスト | アカウントレベル: 同時実行ジョブ数 100 件\* |
| 期間 | 7 日間 | 90 日間 (セグメントなし)
* 任意の時点で同時に「処理中」状態になれるジョブの最大数を指します。
\*\* ジョブの処理が正常に完了すると、URL が返されます。この URL から、圧縮 (gzip) された結果ファイルをダウンロードできます。
それ以外の点では、これらのエンドポイントは同じ機能を提供します。
### ユースケース
主なアナリティクスのユースケースは 3 つあります。
1. リアルタイム最適化: パフォーマンス指標を用いて、配信中のキャンペーンを更新する
2. 同期処理: 定期的に実行されるバックグラウンド同期
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 と整合している必要があります。
1. `TOTAL`: 任意のタイムレンジを指定できます (エンドポイントの制限内)
2. `DAY`: start time と end time の両方の値は、アカウントのタイムゾーンにおける午前 0 時に揃えて指定する必要があります
3. `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](/ja/x-ads-api/analytics#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 エンドポイント](/ja/x-ads-api/analytics#active-entities-2) を使用してください。
なぜ analytics レスポンス内の値がすべて `null` なのですか？
* リクエストした期間中に、そのキャンペーンが配信されていなかった可能性が高いです。
* どのエンティティの、どの期間の analytics を取得すべきかを判断するために、[Active Entities エンドポイント](/ja/x-ads-api/analytics#active-entities-2) を使用してください。
なぜ API では `null` が表示されるのに、UI では 0 が表示されるのですか？
* UI ではこれらの値を 0 として表示していますが、値としては同等です。
X のタイムラインのような細かいプレースメントに関連するメトリクスは、どのようにリクエストできますか？
* analytics では、`ALL_ON_TWITTER`、`PUBLISHER_NETWORK`、`SPOTLIGHT`、`TREND` (つまり [X Audience Platform](/ja/x-ads-api/audiences)) というプレースメント値をサポートしています。
削除済みまたは一時停止中のエンティティについてもメトリクスを取得することはできますか？
* はい。エンティティのステータスは analytics 指標の取得可否には影響しません。
なぜセグメント別の値が非セグメントの値と一致しないのですか？
* セグメント別データは、その情報の計算方法上、非セグメントのデータと 100% 一致する集計値になることは想定されていません。
複数のディメンションでセグメント化されたデータをリクエストすることは可能ですか？
* 複数ディメンションでのセグメント化 (マルチセグメンテーション) には対応していません。
## ベストプラクティス
Ads API から[アナリティクス](/ja/x-ads-api/analytics)データを収集する際のベストプラクティスです。
### レート制限とリトライ
* レート制限が適用されたリクエスト (`HTTP 429` ステータスコードを返すもの) では、`x-rate-limit-reset` ヘッダーを確認し、指定された時刻以降にのみリトライする必要があります。
* HTTP 503 Service Unavailable ステータスコードが返されたリクエストでは、`retry-after` ヘッダーを確認し、指定された時刻以降にのみリトライする必要があります。
* 指定されたリトライ時刻を守らないアプリケーションは、予告なく Ads API へのアクセスを取り消されたり、スロットルされたりする可能性があります。
### アナリティクス指標の概要
* すべてのアナリティクス指標は、`billed_charge_local_micro` を除いて、24時間後には値が固定され、それ以降は変更されません。
* `billed_charge_local_micro` 指標は、データが返された時点から最大3日間は推定値として報告されます。
* 24時間経過後、この指標は、過剰配信 (指定した `end_time` 以降に配信された広告) に対するクレジットや、無効と判断された課金対象イベントに対するクレジットにより減少することがあります。この指標は24時間以降はごくわずかしか変化しません。
* 詳細については、[Analytics](/ja/x-ads-api/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](https://github.com/xdevplatform/ads-platform-tools) リポジトリで公開されています。
## 目的別の指標
どの指標をエンティティに適用できるかは、[キャンペーンの目的](/ja/x-ads-api/campaign-management) によって異なります。このガイドを使用して、各目的の種類ごとに取得すべき関連する指標グループと、追加の派生指標の算出方法を確認してください。
### `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](/ja/x-ads-api/analytics) から取得できるメトリクスの概要と、各メトリクスで利用可能なセグメンテーションについて説明します。
| | | | | | | | |
| :------------------- | :-------------------------- | :-------------------- | :---------------- | :---------------- | :---------------------------------- | :---------------------------------------- | :------------------------------------------------------------------------ |
| | メトリクスグループ | | | | | | |
| エンティティ | [`ENGAGEMENT`](#engagement) | [`BILLING`](#BILLING) | [`VIDEO`](#VIDEO) | [`MEDIA`](#MEDIA) | [`WEB_CONVERSION`](#WEB_CONVERSION) | [`MOBILE_CONVERSION`](#MOBILE_CONVERSION) | [`LIFE_TIME_VALUE_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 オブジェクト |
### セグメンテーション
セグメンテーションのレポートでは、特定のターゲティングタイプの値ごとに分割されたメトリックを取得できます。セグメンテーションは、追加される複雑性が大きいため、[非同期アナリティクスクエリ](/ja/x-ads-api/analytics#asynchronous-analytics) でのみ利用可能です。
セグメンテーションは、`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` | | |
## 導出メトリクス
キャンペーンメトリクスは、それぞれの[キャンペーン目的](/ja/x-ads-api/campaign-management)に依存します。このガイドでは、設定されている目的に応じて利用する導出メトリクスの算出方法を説明します。
中括弧で囲まれていない `metric` は、Ads API の [analytics](/ja/x-ads-api/analytics#synchronous-analytics) エンドポイントから返されるメトリクスです。名前が \{中括弧} で囲まれているものは、そのカテゴリにおける導出メトリクスを表します。
### エンゲージメント
| | |
| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 派生指標 | 公開指標の計算式 |
| {インプレッション} | `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |
| {CPM} | `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}` |
| {CPE} | `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
| | |
| :----------------- | :------------------------------------------------------------------------------------------------------------- |
| 導出指標 | 公開指標の計算式 |
| {Impressions} | `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |
| {CPM} | `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}` |
| {CPLC} | `billed_charge_local_micro / {Link Clicks}` |
| {Conversion} | `conversion_site_visits` |
| \{Conversion Rate} | `conversion_site_visits / {Impressions}` |
| {CPA} | `billed_charge_local_micro / conversion_site_visits` |
### APP\_INSTALLS と APP\_ENGAGEMENTS
| | |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| 派生指標 | 公開指標に基づく計算式 |
| {Impressions} | `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions` |
| {CPM} | `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}` |
| {CPAC} | `billed_charge_local_micro / {App Clicks}` |
| {CPI} | `billed_charge_local_micro / mobile_conversion_installs` |
### フォロワー
| | |
| :--------- | :------------------------------------------------------------------------------------------------------------- |
| 導出指標 | 公開指標の算出式 |
| {インプレッション} | `promoted_account_impressions` |
| {CPM} | `billed_charge_local_micro / {Impressions} / 1000` |
| {フォロワー数} | `promoted_account_follows` |
| \{フォロー率} | `promoted_account_follow_rate` |
| {CPF} | `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}` |
### リード獲得
| | |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| 派生指標 | メトリックの算出式 |
| {Impressions} | `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |
| {CPM} | `billed_charge_local_micro / {Impressions} / 1000` |
| {Leads} | `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
| | |
| :--------------- | :------------------------------------------------------------------------------------------------------------- |
| 派生メトリクス | 公開メトリクスの計算式 |
| {Impressions} | `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |
| {CPM} | `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
| | |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| 派生指標 | 公開メトリックに基づく計算 |
| {Impressions} | `promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions` |
| {CPM} | `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 エンドポイント](/ja/x-ads-api/analytics#get-stats-accounts-account-id-active-entities) は、どのキャンペーンについてアナリティクスをリクエストすればよいかを判断するための情報を提供することを目的として、[同期](/ja/x-ads-api/analytics#get-stats-accounts-account-id) および [非同期](/ja/x-ads-api/analytics#asynchronous-analytics) アナリティクスエンドポイントと組み合わせて使用するよう設計されています。広告エンティティの詳細と、そのメトリクスがいつ変化したかを返すことで、この目的を達成します。このエンドポイントを使用することで、コードおよびアナリティクス取得ロジックを大幅に簡素化できます。
このガイドでは、このエンドポイントとそのデータソースに関する情報とコンテキストを提供します。また、[利用ガイドライン](#usage) と、Active Entities をアナリティクスエンドポイントと組み合わせて使用する方法を示す一連の [リクエスト例](#example) も掲載しています。[概要セクション](#summary) では、推奨されるアプローチの概要レベルの説明を提供します。
#### データ
広告エンティティのメトリクスが変更されるたびに、その変更に関する情報を記録します。これらの変更イベントは 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](https://en.wikipedia.org/wiki/ISO_8601) 形式で指定し、どの 1 時間単位のバケットをクエリするかを示す必要があります。これらは必ず 1 時間きざみで指定しなければなりません。
このエンドポイントは、結果をフィルタリングするために使用できる 3 つのオプションのパラメータ `funding_instrument_ids`、`campaign_ids`、`line_item_ids` もサポートします。これらは広告階層のすべてのレベルおよび指定された任意の `entity` type で機能します。
### レスポンス
上記のリクエストに対する Active Entities レスポンスは以下のとおりです。
```json theme={null}
{
"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 つの点について判断する必要があります。
1. アクティブエンティティ情報をどのくらいの頻度でリクエストするか、そしてその結果としてアナリティクスをどのくらいの頻度で取得するか。
2. アクティビティの開始時刻と終了時刻をどのように使用して、アナリティクスリクエストの `start_time` および `end_time` の値を決定するか。
これらについては、以下の 2 つの小節で、概要の後にそれぞれより詳しく説明します。
### まとめ
Active Entities エンドポイントを次のように使用して、分析リクエストの実行方法を決定します。アクティブなエンティティ情報をどの程度の頻度で取得するか、つまりどの程度の頻度で分析データを取得するかを決めたあとに、以下に従ってください。
1. Active Entities リクエストを送信します。
2. レスポンスを placement ごとに分割します。`ALL_ON_TWITTER` 用に 1 グループ、`PUBLISHER_NETWORK` 用に 1 グループ、`SPOTLIGHT` 用に 1 グループ、`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](https://github.com/xdevplatform/twitter-python-ads-sdk/blob/master/examples/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
#### 例
このセクションでは、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"`
```
```json theme={null}
{
"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"`
```
```json theme={null}
{
"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"`
```
```json theme={null}
{
"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"`
```
```json theme={null}
{
"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"`
```
```json theme={null}
{
"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"`
```
```json theme={null}
{
"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"`
```
```json theme={null}
{
"request": {},
"data": []
}
```
### 非同期処理ガイド
## APIリファレンス
### 非同期アナリティクス
#### はじめに
非同期アナリティクスのエンドポイントを使用すると、パートナーや広告主は作成リクエストを送信し、サーバー側で非同期に処理される指標 (メトリクス) を取得できます (これらを非同期アナリティクスの「ジョブ」と呼びます) 。この方式では、リクエストが完了するまでクライアントの接続を開いたままにしておく必要はありません。
これらのエンドポイントは、同期型エンドポイントと同様に、パートナーや広告主がキャンペーンのパフォーマンスに関する詳細な統計情報をリクエストできるようにします。アカウント、ファンディングインストルメント、キャンペーン、ラインアイテム、プロモツイート、メディアクリエイティブに対するデータのリクエストをサポートします。同期型エンドポイントとの違いは、非同期アナリティクスのエンドポイントでは、最大 90 日までのより長い期間に加えて、セグメンテーションもサポートしている点です。両者の違いの詳細については、[Analytics Overview](/ja/x-ads-api/analytics) ページを参照してください。
同期型エンドポイントとは異なり、レート制限は特定のアカウントに対して同時に実行できるジョブ数に基づきます。言い換えると、ある時点で処理中にできるジョブの数に基づきます。これは広告アカウント単位でカウントされます。
#### 使用方法
非同期アナリティクスのエンドポイントを使ってキャンペーン指標を取得するには、複数のステップを踏む必要があります。ジョブを作成し、そのジョブの処理が完了したかどうかを確認し、最後にデータをダウンロードします。データファイルは解凍する必要があります。具体的な 4 つのステップは以下のとおりです。
1. [POST stats/jobs/accounts/:account\_id](/ja/x-ads-api/analytics#asynchronous-analytics) エンドポイントを使用してジョブを作成します。
2. ジョブの処理が完了したかどうかを判定するために、一定間隔で [GET stats/jobs/accounts/:account\_id](/ja/x-ads-api/analytics#asynchronous-analytics) エンドポイントにリクエストを送信します。
3. ジョブの処理が完了したら、データファイルをダウンロードします。
4. データファイルを解凍します。
データファイル内で返される response オブジェクトは、同期アナリティクスエンドポイントのレスポンスと同じ JSON スキーマを持ちます。
セグメント化されたキャンペーン指標は、非同期アナリティクスエンドポイントからのみ取得できます。キャンペーン指標は、地域、性別、興味関心、キーワードなどで分割して取得できます。利用可能なオプションの完全な一覧については、[指標とセグメンテーション](/ja/x-ads-api/analytics#metrics-and-segmentation) ページを参照してください。セグメント化された指標をリクエストするには、ジョブを作成する際に `segmentation_type` リクエストパラメータを使用します。
#### 例
このセクションでは、非同期アナリティクスエンドポイントの使用方法を示します。
まず、[POST stats/jobs/accounts/:account\_id](/ja/x-ads-api/analytics#asynchronous-analytics) エンドポイントを使用してジョブを作成します。以下の例では、特定のラインアイテムについて、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"
```
```json theme={null}
{
"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"
```
```json theme={null}
{
"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`
```
ファイルの内容は次のとおりです。
```json theme={null}
`$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json`
```
```json theme={null}
{
"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"
]
}
}
}
```
### リーチと平均フリークエンシー
Postman で実行
#### GET stats/accounts/:account\_id/reach/campaigns[](#get-stats-accounts-account-id-reach-campaigns "Permalink to this headline")
指定したキャンペーンのリーチおよび平均フリークエンシーに関するアナリティクスを取得します。
### リソースURL[](#resource-url "Permalink to this headline")
`https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns`
### パラメーター[](#parameters "Permalink to this headline")
| Name | Description |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id
### リクエスト例[](#example-request "Permalink to this headline")
`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`
### レスポンス例[](#example-response "Permalink to this headline")
```json theme={null}
{
"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[](#get-stats-accounts-account-id-reach-funding-instruments "Permalink to this headline")
指定した funding instrument のリーチおよび平均フリークエンシーに関する分析情報を取得します。
### リソース URL[](#resource-url "Permalink to this headline")
`https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments`
### パラメーター[](#parameters "Permalink to this headline")
| Name | Description |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id
### 同期型アナリティクス
Postman で実行
#### GET stats/accounts/:account\_id[](#get-stats-accounts-account-id "この見出しへのパーマリンク")
現在のアカウントの同期型アナリティクスを取得します。指定できる最大の時間範囲 (`end_time` - `start_time`) は7日間です。
### リソースURL[](#resource-url "Permalink to this headline")
`https://ads-api.x.com/12/stats/accounts/:account_id`
### パラメーター[](#parameters "Permalink to this headline")
| Name | Description |
| :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id
### アクティブなエンティティ
Postman で実行
#### GET stats/accounts/:account\_id/active\_entities[](#get-stats-accounts-account-id-active-entities "この見出しへのパーマリンク")
指定した期間内で、どのエンティティについてアナリティクス指標に変更があったかの詳細を取得します。
このエンドポイントは、アナリティクス系エンドポイントと併用してください。このエンドポイントの結果は、どの広告エンティティに対してアナリティクスをリクエストすべきかを示します。利用方法については [Active Entities Guide](/ja/x-ads-api/analytics#active-entities) を参照してください。
変更イベントは 1 時間ごとのバケットで提供されます。
* `start_time` と `end_time` の値で、クエリ対象とする 1 時間ごとのバケットを指定します。
* 返される `data` 配列には、その後のアナリティクスリクエストに含める必要がある各エンティティごとに 1 つのオブジェクトが含まれます。
* **重要**: その後のアナリティクスリクエストで指定すべき日付は、`activity_start_time` および `activity_end_time` の値に基づいて決定してください。
* これらの値は、保存されている変更イベントが *適用される* 期間を表します。これはエンティティごとに返されます。
**注**: 指定可能な最大の時間範囲 (`end_time` - `start_time`) は 90 日です。
### リソース URL[](#resource-url "Permalink to this headline")
`https://ads-api.x.com/12/stats/accounts/:account_id/active_entities`
### パラメーター[](#parameters "Permalink to this headline")
| Name | Description |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id