Aaron Karp, AdWords API Team
Version 11 of the AdWords API includes a significant overhaul to the way you schedule reports and the data you are able to retrieve. In the reconfigured Report Service, you now have access to most of the report types and columns that are available through the AdWords Report Center, which means more advanced stats and breakdowns than ever before. Going forward, the API should be much more synchronized with the AdWords front end, while offering increased flexibility at the same time.
In v10 and its predecessors, you scheduled a report by creating a job of a certain type (perhaps by specifying the xsi:type attribute) and then adding some basic fields like campaigns and aggregationType. You had little control over the output, and this made scheduling reports through the API less powerful than doing so through the front end.
In v11, there is only one type of report job (the DefinedReportJob) but it is much more flexible. For example, a DefinedReportJob supports multiple aggregation types, allowing you to tally your metrics more effectively. You can also filter based on campaign, adgroup, and keyword statuses, or by keyword text, keeping your reports slim and precise.
When you schedule a report in v11, you always start with DefinedReportJob as the job type, and then specify one of seven report types (Account, Ad, Ad Group, Campaign, Keyword, Reach and Frequency, or Url) in the selectedReportType child element. Next, mix in v11's biggest strength: custom columns for any report type using the selectedColumns element. For a complete list of columns matching the different report types, see Report Rules.
Why is this better than custom reports in v10? Primarily, it gives you access to report columns that weren't available before. Also, we've hooked you directly into the AdWords reports system, which means that as new columns and report types are rolled out, they'll be available in the API much more quickly.
Here's an example of scheduling a keyword report in v11. Much of it is similar to v10, so I've highlighted the differences.
<email>test+mcc@google.com</email>
<password>myPassword</password>
<developerToken>abcdefg1234567890</developerToken>
<applicationToken>1234567890abcdefg</applicationToken>
<useragent>Testing new report service</useragent>
</header>
<body>
<scheduleReportJob xmlns='https://adwords.google.com/api/adwords/v11'>
<job xsi:type='DefinedReportJob'>
<name>Test Report1</name>
<startDay>2007-09-01</startDay>
<endDay>2007-09-30</endDay>
<campaignStatuses>Active</campaignStatuses>
<campaignStatuses>Paused</campaignStatuses>
<aggregationTypes>Summary</aggregationTypes>
<includeZeroImpression>true</includeZeroImpression>
<selectedReportType>Keyword</selectedReportType>
<selectedColumns>Campaign</selectedColumns>
<selectedColumns>AdGroup</selectedColumns>
<selectedColumns>Keyword</selectedColumns>
<selectedColumns>KeywordStatus</selectedColumns>
<selectedColumns>Impressions</selectedColumns>
<selectedColumns>Clicks</selectedColumns>
<selectedColumns>AveragePosition</selectedColumns>
</job>
</scheduleReportJob>
</body>
Objects omitted above, like language and geotargeting, haven't changed.
It's also important to know that not all column types (selectedColumns) are compatible with all report types (selectedReportType) and with one another. Prior to scheduling a job, make sure to test it with the validateReportJob method: scheduling an invalid report will cost 1000 API units, but validating only costs 1.
We know that reports are a vital part of your business, and hope you find the modifications we've made useful. We're eager to hear your feedback, so if you have any questions or requests, please post them on the AdWords API Forum where we'll be happy to address them.
