Thursday, October 18, 2007

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 ajobof a certain type (perhaps by specifying thexsi:typeattribute) and then adding some basic fields likecampaignsandaggregationType.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 (theDefinedReportJob) but it is much more flexible. For example, aDefinedReportJobsupports 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 withDefinedReportJobas the job type, and then specify one of seven report types (Account, Ad, Ad Group, Campaign, Keyword, Reach and Frequency, or Url) in theselectedReportTypechild element. Next, mix in v11's biggest strength: custom columns for any report type using theselectedColumnselement. 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.

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 thevalidateReportJobmethod: 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.