リクエスト レポート

新しい Search Ads 360 Reporting API をご利用いただけるようになりました。新しい API では、柔軟性の向上により、カスタム レポートを作成し、レポート作成のアプリケーションやプロセスにデータを統合することができます。詳しくは、新しい Search Ads 360 Reporting API への移行と使用についての記事をご覧ください。

初めてのアプリの説明に沿ってクライアント アプリを設定したら、Search Ads 360 API を使ってレポートをリクエストし、ダウンロードできます。次のいずれかのリクエストを行うことができます。

同期

必要なのは 1 つのリクエストのみで、レポートを JSON 形式のレスポンスで返します。同期リクエスト:

  • 広告主レポートとエンジン アカウント レポートのみを返すことができます
  • 検索広告 360 でレポートが生成されるまでクライアントをブロックする

大規模な広告主レポートやエンジン アカウント レポートをリクエストする場合は、非同期型の方法をおすすめします。

非同期

レポートに含めるデータを指定する最初のリクエストを送信する必要があります。その後、追加のリクエストを送信して検索広告 360 をポーリングします。検索広告 360 でレポートの生成が完了したら、レポートを 1 つ以上のファイルとしてダウンロードするためのリクエストを送信します。非同期リクエスト:

  • 任意のレポートタイプを返すことが可能
  • 非常に大きなレポートを複数のファイルにシャーディングする
  • レポートを CSV 形式または TSV 形式にする

データモデル: 行と列

検索広告 360 では、レポートのデータが行と列の形式で整理されます。 リクエストするレポートのタイプによって、返される行が決まります。たとえば、キーワード レポートをリクエストすると、各行には 1 つのキーワードに関するデータが含まれます。すべてのレポートタイプの一覧については、レポートタイプのリファレンスをご覧ください。 レポートに含める列は、レポート リクエストの各列に名前を付けます。各レポートタイプで返される列の一覧については、レポートタイプのリファレンスをご覧ください。

列の動作

列の動作は列に含まれるデータのタイプによって異なります（各列の動作については、レポートタイプのリファレンスをご覧ください）。

  • 属性列。属性列には、キャンペーン名やキーワードの入札単価など、キャンペーン内のエンティティを設定または識別するデータが含まれます。Search Ads 360 API は、リクエストで指定された日付や期間に関係なく、属性列の現在の値を返します。たとえば、前日にキーワードの入札単価を 2.00 から 1.50 に変更し、先月分のデータのレポートをリクエストした場合、レポートではキーワード入札単価に対して値 1.50 が返されます。

  • 指標の列。指標列には、キャンペーンのパフォーマンスに関するデータ（広告のクリック数、Floodlight タグで記録されたアクセス数、収益など）が含まれます。1 日の期間を指定しない限り、API は指標列の集計値を返します。たとえば、先月のデータのレポートをリクエストすると、API は先月の合計クリック数を返します。

  • 表示項目を分割します。列を使用すると、データが別々の行に分割されます。 たとえば、date は、さまざまなタイプのレポートで指定できるセグメント列です。期間に 2013-01-01 ～ 2013-01-07 を指定してキーワード レポートで date 列を指定すると、API はキーワードごとに 7 行（それぞれ 1 日に対応）を返し、その日の指標を表示します。セグメント別レポートをご覧ください。

為替

レポート リクエストでは、金額データ（dailyBudget などの属性と cost などの指標の両方）の通貨を指定する必要があります。次のいずれかを指定できます。

  • 代理店の通貨（レポートのスコープが代理店、広告主、またはエンジン アカウントに設定されている場合）。
  • 広告主の通貨（レポートの対象が広告主またはエンジン アカウントである場合）。
  • エンジン アカウントの通貨（レポートの対象がエンジン アカウントの場合）。
  • USD

通貨を指定するには、Reports.request.statisticsCurrency リクエスト プロパティを使用します。

レポート自体の Reports.statisticsCurrencyCode プロパティに通貨を指定します。

タイムゾーン

検索広告 360 の指標は、タイムゾーンのない日付で保存されます。これらの日付は、エンジンに関する指標（クリック数、インプレッション数、訪問数など）ではエンジン アカウントのタイムゾーンを、コンバージョンに関する指標（アクション、トランザクション、収益など）では、キャンペーン マネージャーのネットワークのタイムゾーンを使用します。レポート内のすべての指標が同じタイムゾーンから取得されている場合、リクエストでそのタイムゾーンが返されます。それ以外の場合、タイムゾーンは返されません。 リクエストで Reports.request.verifySingleTimeZone: true を設定すると、複数のタイムゾーンの指標を含むレポートを失敗させることができます。

レポート内のすべての指標が同じタイムゾーンのものである場合、そのタイムゾーンは Reports.statisticsTimeZoneReports で返されます。