レポートの基礎

ほとんどの AdWords API アプリケーションで欠かせないのが、掲載結果データのレポート機能です。AdWords API の柔軟なレポート機能を使えば、キャンペーン全体の掲載結果データのレポートを取得したり、広告が表示されるきっかけとなった検索語句などに絞ってデータを取得したりできます。

このガイドでは、レポート リクエストを作成して AdWords サーバーに送信する手順を説明します。また、データの分割表示やデータ形式、アトリビューションなど高度なレポートのコンセプトも紹介します。

AdWords API で利用できるすべてのレポートタイプのリストについては、レポートタイプのリファレンス ページをご覧ください。

概要

API からレポートを生成する手順は、大きく次の 2 つに分かれます。

  1. レポート定義を作成します。レポート定義とは、レポートのパラメータを定義する XML か AWQL のフラグメントです。ここでレポート名、レポートに含める情報の種類、ダウンロード形式などレポートのパラメータを指定します。
  2. レポート定義を HTTP POST リクエストに格納し、AdWords サーバーに送信します。

この 2 つの手順について、以降で詳しく説明します。

レポート定義を作成する

レポート定義はリクエストの構成を決めるもので、レポートに含める要素を指定します。

レポート定義は XML か AWQL(AdWords クエリ言語)で作成します。

次以降のセクションでは、XML ベースのレポート定義について説明します。XML ではなく AWQL を使う必要がある場合は、AWQL ガイドのレポートに関するページをご覧ください。

以下に、XML レポート定義の例を示します。その下の表で、レポート定義の各要素について説明します。

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
<fields>CampaignId</fields>
<fields>AdGroupId</fields>
<fields>Impressions</fields>
<fields>Clicks</fields>
<fields>Cost</fields>
<predicates>
  <field>AdGroupStatus</field>
  <operator>IN</operator>
  <values>ENABLED</values>
  <values>PAUSED</values>
</predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT
WHERE AdGroupStatus IN [ENABLED, PAUSED]
DURING LAST_7_DAYS
レポート定義の要素 説明
<reportDefinition> レポート定義のヘッダーです。リクエストで指定する URL と同じ URL を使い、API の正しいバージョンを必ず記載してください。
<selector> selector セクションでは、レポートに含めたいデータ要素の fields を指定します。ここで指定できる 値の詳細については、レポートタイプに関するページを ご覧ください。指定する reportType によっては、フィールド リストを利用できます。

また、プログラムで ReportDefinitionService.getReportFields() メソッドを使って、使用できるフィールドのリストを取得することもできます。

<predicates> predicate は AdWords 管理画面でのフィルタに相当する機能です。predicate は レポート フィールド、演算子、値で構成されます。predicate は包括(AND)条件として扱われます。
<reportType> リクエストするレポートのタイプを指定します。すべてのレポートタイプのリストなど、詳しい情報についてはレポートタイプに関するページをご覧ください。
<dateRangeType> レポートに含めるデータの期間です。詳しくは期間をご覧ください。
<downloadFormat> ダウンロードするレポートの形式です。詳しくは、サポートされるダウンロード形式をご覧ください。

XML スキーマ定義

reportDefinition の構造を定義する XML スキーマ定義(XSD)は次の URL で発行されます。

https://adwords.google.com/api/adwords/reportdownload/v201609/reportDefinition.xsd

application/x-www-form-urlencodedmultipart/form-data の両方のコンテンツ タイプを利用できますが、前者の場合は送信された XML を URL エンコードする必要があります。

期間

レポートの期間を指定するには、ReportDefinition.DateRangeType を使用します。これはレポート定義 XSD に含まれます。

有効な DateRange のタイプ レポートの対象期間
TODAY 本日のみ。
YESTERDAY 昨日のみ。
LAST_7_DAYS 過去 7 日間(本日を除く)。
LAST_WEEK 前の月曜日から始まる 7 日間。
LAST_BUSINESS_WEEK 前の営業週の月曜日から金曜日までの 5 営業日。
THIS_MONTH 今月のすべての日。
LAST_MONTH 先月のすべての日。
ALL_TIME データが存在するすべての期間。
CUSTOM_DATE カスタム期間。詳しくは下記のカスタム期間を参照してください。
LAST_14_DAYS 過去 14 日間(本日を除く)。
LAST_30_DAYS 過去 30 日間(本日を除く)。
THIS_WEEK_SUN_TODAY 前の日曜日から今日までの期間。
THIS_WEEK_MON_TODAY 前の月曜日から今日までの期間
LAST_WEEK_SUN_SAT 前の日曜日から始まる 7 日間。

すべての ReportDefinition.DateRangeTypeCUSTOM_DATE を除く)で dateRangeType のみ必須となります。

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
    ...
  <dateRangeType>LAST_7_DAYS</dateRangeType>
</reportDefinition>

カスタム期間

カスタム期間を指定する場合は、次の手順が必要になります。

  1. dateRangeTypeCUSTOM_DATE を指定します。
  2. selectordateRange を含めて、minmaxYYYYMMDD 形式で指定します。

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
...
<dateRange>
  <min>20150201</min>
  <max>20150301</max>
</dateRange>
  </selector>
  <dateRangeType>CUSTOM_DATE</dateRangeType>
</reportDefinition>

AWQL

...
DURING 20150201,20150301

データの更新

レポートで取得される掲載結果には、絶えず集計されているものと 1 日に 1 回集計されるものがあり、これには AdWords でのデータ更新の仕組みが関係しています。レポート機能を有効活用するには、データ更新に関するドキュメントをご覧ください。

リクエストを作成する

レポート定義を作成すると、HTTP POST リクエストを準備できるようになります。

同期型のシンプルな HTTP リクエストを AdWords サーバーに直接送信する方法は、オーバーヘッドが小さいため、特に複数のスレッド(推奨は 10 件から)を使って大量のレポートを生成する場合に適しています。この HTTP リクエストは、レポートデータがダウンロード可能な状態になるまで呼び出しで事実上ブロックされるため、同期的に実行されます。

サーバーのオープン接続数の制限を超える前に、1 秒あたりのクエリ数(QPS)の制限(RateExceededError)に達する可能性があります。レポート リクエストは 1 日あたりのオペレーション数にカウントされませんが、1 日あたりのレポート ダウンロード数に制限があります

XML レポート定義の場合、使用する XML レポート定義を指定するために、POST リクエストの本文に「__rdxml」という名前のパラメータを含める必要があります。

リクエストのヘッダー

レポートをダウンロードする際は、通常の HTTP ヘッダー値を使用します。

HTTP ヘッダー 説明
Authorization: Bearer OAUTH2_ACCESS_TOKEN レポートをダウンロードするための承認です。SOAP リクエスト ヘッダーで使用するものと同じ accessToken を使用します。
developerToken: DEVELOPER_TOKEN 開発者トークンです。1a2B3c4D5e_-6v7w8x9y0z のような一意の文字列となります。
clientCustomerId: CLIENT_CUSTOMER_ID クライアント アカウントのお客様 ID です。

必要に応じて以下の HTTP ヘッダーを設定して、レポートにヘッダー行や集計行を含めるかどうかを指定できます。

任意指定の HTTP ヘッダー 説明
skipReportHeader: true|false true の場合、レポート名と期間を含むヘッダー行がレポート出力に含まれなくなります。false または未指定の場合、レポート出力にヘッダー行が含まれます。
skipColumnHeader: true|false true の場合、フィールド名を含むヘッダー行がレポート出力に含まれなくなります。false または未指定の場合、レポート出力にフィールド名が含まれます。
skipReportSummary: true|false true の場合、レポートの合計値を含む集計行がレポート出力に含まれなくなります。false または未指定の場合、レポート出力に集計行が含まれます。
useRawEnumValues: true|false 実際の列挙値が返されるようにするには true に設定します。たとえば「Image ad」ではなく、「IMAGE_AD」の形式を希望する場合です。表示値を返してほしい場合は false に設定するか、このヘッダーを省略します。
includeZeroImpressions: true|false true の場合、指定されたすべての指標フィールドが 0 である行がレポート出力に含まれるようになります(そのフィールドと predicate がゼロ インプレッションに対応していることが条件となります)。false の場合、レポート出力にそのような行は含まれません。そのためこのヘッダーが false、行の Impressions が 0 回であっても、指定された指標フィールドのいずれかの値が 0 でなければこの行は返されます。未指定の場合は、ゼロ インプレッションに関するガイドで説明されているデフォルトの動作でレポートが作成されます。

HTTP リクエストの URL

リクエストは、次の URL の AdWords サーバーに対する HTTP POST となります。

https://adwords.google.com/api/adwords/reportdownload/v201609

サンプルコードの全文

以下に、HTTP POST リクエストに格納されるレポート定義のサンプルコードの全文を示します。

XML

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: /
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 784
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559

Parameters:
__rdxml: &lt;?xml version="1.0" encoding="UTF-8"?&gt;
<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
    <fields>CampaignId</fields>
    <fields>AdGroupId</fields>
    <fields>Impressions</fields>
    <fields>Clicks</fields>
    <fields>Cost</fields>
    <predicates>
      <field>AdGroupStatus</field>
      <operator>IN</operator>
      <values>ENABLED</values>
      <values>PAUSED</values>
    </predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: */*
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 182
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559
 
Parameters:
__fmt: CSV
__rdquery: SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost \
FROM ADGROUP_PERFORMANCE_REPORT \
WHERE AdGroupStatus IN [ENABLED, PAUSED] DURING LAST_7_DAYS

応答コード

レポート リクエストが正常に処理されると、サーバーは応答コード 200 を返します。

応答コード 400 は API エラーを示しています。レポート定義の XML に問題がないかどうか確かめてください。

応答コード 500 は通常、サーバーで一時的な問題が発生していることを示します。このエラーが発生した場合は、しばらく待ってからリクエストを再試行してください。

複数アカウントのレポート

1 つのレポート リクエストに含めることができるのは、1 つの AdWords アカウントのデータのみです。複数のアカウントのレポートデータを収集する必要がある場合、上の説明に従って clientCustomerId ヘッダーを設定し、アカウントごとに別々にレポート リクエストを送信してください。

タイムアウト

データセットのサイズが極端に大きい場合、レポートのダウンロード リクエストがタイムアウトになることがあります。データサイズの上限は特にありませんが、レポートが大きすぎると、さまざまな原因でエラーが返される可能性があります。

タイムアウトやエラーが発生した場合は、期間を短くするか、predicate を利用してレポート リクエストを小さいリクエストに分割してください。たとえば、すべてのキャンペーンを対象に 1 つのレポートを実行するのではなく、一部のキャンペーン ID のみに絞ったリクエストを複数作成して送信します。

サポートされるダウンロード形式

形式 説明
CSVFOREXCEL Excel 用の形式です。Unicode 形式ですが、その先頭に Unicode であることを Excel に伝える BOM(バイト オーダー マーカー)が付与されます。Unicode を使用する場合、Excel ではデフォルトの区切り文字としてタブが使われます。カンマ(,) が使用されている場合、デフォルトで各行のすべてのデータが 1 つの列に 配置されます。
CSV csv(カンマ区切り)出力形式です。
TSV tsv(タブ区切り)出力形式です。
XML xml 出力形式です。
GZIPPED_CSV gzip 圧縮された csv(カンマ区切り)出力形式です。
GZIPPED_XML gzip 圧縮された xml 出力形式です。

適切なレポートを選択する

AdWords API では多様なレポートを利用できるため、特定のニーズに合った適切なレポートを選ぶことに手間取る場合もあります。

次の図で最も適したレポートを特定し、レポートタイプのページでそのレポートの詳細を確認してください。

セグメント分割

データをセグメントごとに分割すると、掲載結果をより詳細に把握できます。たとえば Google 検索ネットワークの表示回数と Google ディスプレイ ネットワークの表示回数を区別して確認するには、レポートをネットワークごとに分割して表示します。

セグメント分割は管理画面のメニューから実施できますが、API でもレポートに適切なフィールドを追加するだけで対応できます。たとえば AdNetworkType1 というフィールドを広告グループの掲載結果レポートに追加した場合、レポートには広告グループとネットワークの組み合わせごとに行が追加され、掲載結果の値(表示回数、クリック数、コンバージョン数など)がそれぞれに分割して表示されます。管理画面では 1 つのセグメントしか表示できませんが、API を使用すると同一レポート内で複数のセグメントを組み合わせることができます。ただし、レポートにフィールドを追加するたびに行数が飛躍的に増加するので注意が必要です。

暗黙的セグメント分割

各レポートはそれぞれ独自のキーによりセグメント分割されます。たとえばキーワードの掲載結果レポートは、たとえセレクタ フィールドに含まれていなくても、IdAdGroupId により暗黙的にセグメント分割されます。キーワードはそもそも IdAdGroupId の両方で識別されるからです。

Keyword,MatchType,Impressions
Keyword1,Exact,3
Keyword2,Exact,10
Keyword3,Exact,5
Keyword4,Broad,4

単一アトリビューションと複数アトリビューション

ディスプレイ ネットワークでインプレッションが発生した場合、その発生時に適用される条件は、単一アトリビューションと複数アトリビューションのいずれかとして記録されます。

単一アトリビューション

単一アトリビューションでは、特定のインプレッションに対してトリガー条件(場所、年齢、キーワードなど)が 1 つだけ記録されます。インプレッションは複数の条件から発生することもありますが、単一アトリビューション レポートではそのインプレッションと関連するすべての統計データが 1 つの条件だけに関連付けられます。

各インプレッションは(1 つの条件下で)1 回と数えられ、すべての条件を加算すると、複数アトリビューションのレポートの合計値となります。

条件の掲載結果キーワードの掲載結果の両レポートでこのモデルが使用されます。

レポートの例

下記は、キャンペーンのターゲットをディスプレイ ネットワークのみに設定し、業種と場所のみを条件とした場合に、条件の掲載結果レポート(単一アトリビューション)を実行した例です。このレポートでは、合計 10 回のインプレッションが 5 行に表示されていて、インプレッションをトリガーした 3 つの場所と 2 つの業種についてそれぞれ 1 行ずつ使用されています。各行ではそれぞれ 2 回のインプレッションが含まれています。

Keyword / Placement,Impressions
www.example.com,2
www.example.ca,2
www.example.net,2
Computers & Electronics,2
Sports,2

複数アトリビューション

複数アトリビューションの場合、インプレッションをトリガーした各ディメンションについて最大で 1 つの条件が記録されます。複数アトリビューション レポートは「特定の条件タイプに絞ったレポート」と考えることができます。各行がさまざまな条件タイプに対応する単一アトリビューション レポートと違い、複数アトリビューション レポートは 1 つの条件タイプしか受け入れることができません。

たとえば性別の掲載結果レポートでは性別でインプレッションが分割され、年齢層別の掲載結果レポートでは年齢層でインプレッションが分割されます。ディスプレイ ネットワークのトピックの掲載結果レポートやプレースメントでの掲載結果レポートもこの方式に則っています。

単一アトリビューションと違い、複数アトリビューション レポートは 1 つにまとめないようにしてください。インプレッションやクリックが二重カウントされる可能性があります。

Topic,Impressions
Computers & Electronics,6
Sports,4

Placement,Impressions
www.example.com,4
www.example.ca,3
www.example.net,3

業種(トピック)と場所のみを使用してディスプレイ ネットワークをターゲットに設定し、ディスプレイ ネットワークのトピックに関するレポートを実行した場合、インプレッションをトリガーした業種(トピック)ごとに 1 行が出力されます。同様に、場所の掲載結果レポートでは各インプレッションにつき 1 行が返されます。最大で 1 つの業種と 1 つの場所の両方が各インプレッションに対するアトリビューションとして記録されるため、これらのレポートには同じインプレッションが含まれます。

KeywordId=3000000

単一アトリビューションのレポートでは、ディスプレイ ネットワークでインプレッションをトリガーしたすべてのキーワードは、ID が Content に指定された特殊キーワード(テキスト: 3000000)として表されます。

Keyword ID,Impressions
23458623485,2
23655322314,2
23953456345,2
3000000,4

ディスプレイ ネットワークのみでキーワードと場所をターゲットに設定して広告の掲載結果レポートを実行すると、広告の場所とそれをトリガーした条件の組み合わせごとに 1 行が出力され、その後に広告と 3000000 の ID を示す 1 行が出力されます。この行は、ディスプレイ ネットワークで広告をトリガーしたすべてのキーワードを表しています(単一アトリビューションの場合は、場所ではなくキーワードが選択されます)。

KeywordId=3000004

3000004 の条件 ID はかつて使用されていた機能で、現在は AdWords から削除されています。

KeywordId=3000006

条件 ID「3000006」はディスプレイ キャンペーン オプティマイザーに関連するステータスであることを表しています。

各種フィールドの書式

レポートで返されるすべてのフィールドには Type がありますが、実際に返される値はこの値と必ずしも一致しません。予想される値の書式に関する追加情報が Notes 列に含まれていることがあるので、この列を必ず確認してください。たとえば ConversionRate の Notes 列には「Percentage returned as "x.xx%"」と記載されます。

レポートの金額フィールド

Money タイプのフィールドは細かい通貨単位(マイクロ)で返されますが、「auto:」が先頭に付けられる場合があり、自動入札機能を使用している場合は文字列「auto」だけになることもあります。たとえば 1.23 ドルは 1230000(1.23×1,000,000)となります。マイクロで示される金額は必ずアカウントの地域通貨で表示されます。

金額フィールドでフィルタをかけるには、値をマイクロで指定する必要があります。たとえば WHERE AverageCpc > 1000000 と指定すると、AverageCpc が 1 ドル(アカウントの通貨単位)を超える行が返されます。

レポートの品質スコア

品質スコアはキーワードの掲載結果レポートや条件の掲載結果レポートに 1(最低)から 10(最高)の間で表示されます。

v201607 より前は、表示回数やクリック数が品質スコアの算出に必要な数に達していないキーワード(新しいキーワードや、長い間使われていない古いキーワードなど)については品質スコアとして 6 を返し、削除済みのキーワードや品質スコアを判定できないディスプレイ ネットワークのキーワードでは品質スコア 0 を返していました。v201607 からは、キーワードの品質スコアを表示できない場合は 2 連続ダッシュ(--)を使うようになっています。v201605 では HasQualityScore という新しい列も追加され、品質スコアが表示されないキーワードを容易に除外できるようになりました。たとえば次の AWQL クエリでは、有効な品質スコアを保持しているキーワードが選択されます。

SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, QualityScore FROM
    CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] and
    HasQualityScore='TRUE'

2 連続ダッシュ

セルに値が含まれていない場合は、2 連続ダッシュ(--)がそのセルの値として使用されます。

リストとマップ

リストの項目は JSON を使用してエスケープ処理されます。たとえば PLACEHOLDER_FEED_ITEM_REPORT 値の Scheduling は次のような文字列の配列となります。

["Monday, 6:00PM - 9:00PM","Tuesday, 6:00PM - 9:00PM","Wednesday,6:00PM - 9:00PM",
"Thursday, 6:00PM - 9:00PM","Friday, 6:00PM - 9:00PM"]

同様に、マップ(UrlCustomParameters など)の場合は次のようになります。

{"param0":"value0","param1":"value1"}

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。