Monday, October 21, 2013

AdWords API: How to migrate from Stats object to AdHoc reports

Starting with v201309 you’ll need to run AdHoc reports in order to retrieve stats.. If you try to retrieve “Impressions”, “Cost” and “Ctr” fields in CampaignService, for example, INVALID_FIELD_NAME will be returned. Instead, you need to retrieve “Impressions”, “Cost” and “Ctr” fields using Campaign Performance Report.

If you're not yet familiar with AdHoc reports, here are some basic facts:
  • All fields that were available with Stats objects before v201309 are available with AdHoc reports
  • You can still use the same predicates and date ranges.
    (AdHoc reports support more fields that can be included in predicates)
The table below shows you equivalent AdHoc reports for each stats object.

Stats objects Equivalent reports
AdGroupAdService.AdStats Ad Performance Report
AdGroupCriterionService.Stats Keywords for Search : Keywords Performance Report
Keywords for Display : Display Keyword Performance Report
Placements : Placement Performance Report
Topics : Display Topics Performance Report
Interests & Remarketing : Audience Performance Report
Gender : Gender Performance Report
Age Range : Age Range Performance Report

Note : It also can be retrieved with Criteria Performance Report, but it’s single attribution
AdGroupService.Stats Ad Group Performance Report
CampaignAdExtensionService.CampaignAdExtensionStats Ad Extensions Performance Report
CampaignService.CampaignStats Campaign Performance Report
FeedItemService Placeholder Feed Item Report

Note : It’s a reference. FeedItemService doesn’t have Stats object.


Also keep in mind there are differences between services and AdHoc reports as following:
  • There is no limit how many results can be retrieved with AdHoc reports. As previously announced, the AdWords API does not allow you to retrieve data with a large start index in services.
  • With AdHoc reports, stats can be segmented in a more flexible way. Please see the segmentation guide for more details.
  • Download Format options (such as CSV, XML, TSV) are available with AdHoc reports. Choose gzip enabled options (GZIPPED_CSV, GZIPPED_XML) to save network bandwidth.
  • Enumeration values for DateRange (such as YESTERDAY, LAST_7_DAYS, LAST_MONTH) are available with AdHoc reports, which lets you easily select common date ranges. You can still choose a custom date range with DateRangeType.CUSTOM_DATE.
  • Paging and OrderBy are not supported by AdHoc reports. If you require the same functionality, you need to retrieve the data using AdHoc reports first and process it locally.
Here is a Java code comparison showing the retrieval of some performance stats over the last 7 days.

AdWords API v201306 with Stats objects
// Create selector.
Selector selector = new Selector();
selector.setFields(new String[] {
  "Id", "Name", "Impressions", "Clicks", "Cost", "Ctr"});
selector.setPredicates(new Predicate[] {new Predicate("Impressions", PredicateOperator.GREATER_THAN, new String[] {"0"})});
String oneWeekAgo = new DateTime().minusDays(7).toString("yyyyMMdd");
String yesterday = new DateTime().minusDays(1).toString("yyyyMMdd");
selector.setDateRange(new DateRange(oneWeekAgo, yesterday));
Retrieving the same stats using AdHoc reports
// Create selector.
Selector selector = new Selector();
List<String> fields = selector.getFields().addAll(Lists.newArrayList(
    "Id", "Name", "Impressions", "Clicks", "Cost", "Ctr");

// Create report definition.
ReportDefinition reportDefinition = new ReportDefinition();
reportDefinition.setReportName(
    "Campaign performance report #" + System.currentTimeMillis());
reportDefinition.setDateRangeType(
    ReportDefinitionDateRangeType.LAST_7_DAYS);
reportDefinition.setReportType(
    ReportDefinitionReportType.CAMPAIGN_PERFORMANCE_REPORT);
reportDefinition.setDownloadFormat(DownloadFormat.CSV);
reportDefinition.setIncludeZeroImpressions(false);
reportDefinition.setSelector(selector);
Using AWQL you can do the same much simpler
String query = "SELECT Id, Name, Impressions, Clicks, Cost, Ctr" 
    + "FROM CAMPAIGN_PERFORMANCE_REPORT “ 
    + “WHERE Impressions > 0 DURING LAST_7_DAYS";
As always, please feel free to ask any questions on the AdWords API forum or our Google+ page.