Report Rules (AdWords API Developer's Guide)

Report Rules

Sections on this page

This topic describes how to construct a valid DefinedReportJob object. For general information on the report service, see the ReportService overview.

The report interface introduced in v11 eliminates all report-specific types, such as KeywordReportJob, and replaces them with one flexible generalized type: DefinedReportJob. This new type also replaces the older, less powerful CustomReportJob. With DefinedReportJob, you first specify the report type (for example, Campaign) in the selectedReportType field. You then choose a custom set of aggregation types and columns to include in your report.

Because DefinedReportJob provides so much flexibility, it's possible to accidentally include columns or aggregation types that conflict with the report type. Scheduling such a report will cause the report service to throw an exception. Because of the dependencies that exist between report type, aggregation types, and columns, you should specify fields in the following order:

Choose the report type by specifying selectedReportType.
Select aggregation types by specifying aggregationTypes. The aggregation types you can use depend on the report type.
Select which columns to include by specifying selectedColumns. The required and optional columns you can include depend on the report type and aggregation types.

Here are some tips to help you schedule a valid report:

Consult the type-specific rules for each report. Make sure you choose appropriate columns and aggregation types.
Use the AdWords Report Center, located on the AdWords website, to create a report with the same aggregation types and columns as the one you want to schedule using the API. If you can create the report using the user interface, you can assume that an identical report from the API is also valid.
Before scheduling a report job, you should use validateReportJob to test its validity. Scheduling an invalid report costs substantially more than validating it.

Rules for Constructing Reports

The following links provide report-specific aggregation type and column rules.

Account - Account Performance
AdGroup - Ad Group Performance
Campaign - Campaign Performance
Creative - Ad Performance
ContentPlacement - Placement Performance
Keyword - Placement / Keyword Performance
ReachAndFrequency - Reach and Frequency Performance
Stucture - Account Structure
Url - URL Performance

Example Request

The following example shows a SOAP message that schedules a keyword report using the DefinedReportJob type. The highlighted fields are new to the v11 report interface.

<soapenv:Envelope
      xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <soapenv:Header>
    <email>myaccount@google.com</email>
    <password>******</password>
    <developerToken>AGYKJI1pFzXPqMEi5qq2NQ</developerToken>
    <applicationToken>SUwrvgFDeAc521uk80GNMQ</applicationToken>
    <useragent>Testing new report interface</useragent>
  </soapenv:Header>

  <soapenv:Body>
    <scheduleReportJob
        xmlns="https://adwords.google.com/api/adwords/v11">
      <job xsi:type="DefinedReportJob">
        <selectedReportType>Keyword</selectedReportType>
        <aggregationTypes>Summary</aggregationTypes>
        <selectedColumns>Campaign</selectedColumns>
        <selectedColumns>AdGroup</selectedColumns>
        <selectedColumns>Keyword</selectedColumns>
        <selectedColumns>KeywordStatus</selectedColumns>
        <selectedColumns>KeywordMinCPC</selectedColumns>
        <selectedColumns>KeywordDestUrlDisplay</selectedColumns>
        <selectedColumns>Impressions</selectedColumns>
        <selectedColumns>Clicks</selectedColumns>
        <selectedColumns>CTR</selectedColumns>
        <selectedColumns>AveragePosition</selectedColumns>
        <crossClient>true</crossClient>
        <endDay>2007-10-03</endDay>
        <startDay>2007-10-03</startDay>
        <adGroupStatuses>Enabled</adGroupStatuses>
        <adWordsType>ContentOnly</adWordsType>
        <campaignStatuses>Active</campaignStatuses>
        <campaignStatuses>Deleted</campaignStatuses>
        <includeZeroImpression>true</includeZeroImpression>
        <keywordStatuses>Active</keywordStatuses>
        <keywordType>Broad</keywordType>
      </job>
    </scheduleReportJob>
  </soapenv:Body>
</soapenv:Envelope>