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.
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.
- Takeshi Hagikura, AdWords API Team
