We have added support for AdWords API v201509 reports in AdWords scripts.

Changes to conversion columns

This release includes several changes that coincide with the recent announcement on conversion columns. Several reporting columns were removed and new columns were added. See the AdWords API release notes for more details.

Video and multi-channel reporting

We are now including statistics and metrics for AdWords for video and TrueView video campaigns in several reports. This includes a new Video Performance Report. Note that reports will only include data for newly created video campaigns in AdWords campaign management or campaigns that were migrated from AdWords for video.

We have also added new reporting columns that help multi-channel advertisers more easily manage reporting for specific campaign types like Search, Shopping, Display, and Video.

See Video and multi-channel reporting changes for more details.

Miscellaneous reporting changes

• All columns that have a List or Map return type now return data in JSON format.
• Shared set type is now returned as an ENUM instead of an Integer in SHARED_SET_REPORT and CAMPAIGN_SHARED_SET_REPORT.
• Several new columns have been added to existing reports.
• A few duplicate columns in existing reports were removed.
• MatchType and MatchTypeWithVariant columns were renamed to QueryMatchType and QueryMatchTypeWithVariant in PAID_ORGANIC_QUERY_REPORT and SEARCH_QUERY_PERFORMANCE_REPORT.

See Miscellaneous reporting changes for more details.

If you use API versioning in your reports, you need to modify your code to use v201509 as shown below. If you don’t use API versioning, no code changes are required.

var report = AdWordsApp.report(query, {
   apiVersion: 'v201509'
});

If you have any questions about these changes or AdWords scripts in general, you can post them on our developer forum.

- Anash P. Oommen, AdWords API Team

We have added support for AdWords API v201506 reports in AdWords Scripts. This version adds support for FINAL_URL_REPORT, the Upgraded URLs-compatible replacement for the DESTINATION_URL_REPORT.

This version also introduces several changes to the reporting columns

• Gmail Sponsored Promotion ad stats are now available in multiple reports in the following columns: GmailForwards, GmailSaves, GmailSecondaryClicks.
• The DURING clause is now optional in AWQL report definitions when not segmenting by Date or Week.
• The following new columns have been added to the existing reports:
  
  

  Column	Reports
  AdGroupStatus	PLACEHOLDER_FEED_ITEM_REPORT
  CampaignName	CAMPAIGN_NEGATIVE_KEYWORDS_PERFORMANCE_REPORT CAMPAIGN_NEGATIVE_LOCATIONS_REPORT CAMPAIGN_NEGATIVE_PLACEMENTS_PERFORMANCE_REPORT
  CampaignStatus	CAMPAIGN_NEGATIVE_KEYWORDS_PERFORMANCE_REPORT CAMPAIGN_NEGATIVE_LOCATIONS_REPORT CAMPAIGN_NEGATIVE_PLACEMENTS_PERFORMANCE_REPORT CAMPAIGN_SHARED_SET_REPORT PLACEHOLDER_FEED_ITEM_REPORT
  EndDate	CAMPAIGN_PERFORMANCE_REPORT
  FinalUrl	SEARCH_QUERY_PERFORMANCE_REPORT
  StartDate	CAMPAIGN_PERFORMANCE_REPORT

If you use API versioning in your reports, then you need to modify your code to use v201506 as shown below. If you don’t use API versioning, no code changes are required.

var report = AdWordsApp.report(query, {
   apiVersion: 'v201506'
});

If you have any questions about this feature or AdWords scripts in general, you can post them on our developer forum.

Anash P. Oommen, AdWords Scripts Team

After our last round of spring cleaning, we've gone back to the drawing board to take another look at how we could make reporting better. There currently is an abundance of Dimensions, DimensionAttributes, and Columns (and more coming with each release), so in an effort to simplify the list of fields, we will be sunsetting the following reconciliation-related dimension attributes / columns in all versions. This will happen on September 1, 2015.

Columns with equivalent replacements:

• RECONCILIATION_LAST_DATE_TIME replaced by dimension attribute: PROPOSAL_LINE_ITEM_LAST_RECONCILIATION_DATE_TIME and LINE_ITEM_LAST_RECONCILIATION_DATE_TIME
• RECONCILIATION_RECONCILIATION_STATUS replaced by dimension attribute: PROPOSAL_LINE_ITEM_RECONCILIATION_STATUS and LINE_ITEM_RECONCILIATION_STATUS

Columns without equivalent replacements:

• LINE_ITEM_RECONCILED_RATE (in <= v201502)
• CONTRACTED_REVENUE_CONTRACTED_PLACEMENT_NET_REVENUE (in <= v201411)
• CONTRACTED_REVENUE_CONTRACTED_PLACEMENT_GROSS_REVENUE (in <= v201411)
• DISCOUNT_BREAKDOWN_ADDITIONAL_ADJUSTMENT (in <= v201411)

While the first two have equivalent replacements, the latter ones are not being replaced, as they don’t exist in core product reporting either.

This means that usage of these columns / dimension attributes will begin throwing errors in all versions starting September 1st. If your network is actively using any of these, please update your reports to switch to the supported fields or remove them entirely. If you have any questions, comments, or concerns about this, you know where to reach us!

 - Nicholas Chen, DFP API Team

We are updating the Paid and Organic report to include only text ad statistics. Impressions and clicks for mobile app install ads and Product Listing Ads will be excluded from this report starting July 13, 2015.

These formats serve in places other than on search results, so we are excluding them to provide you a better comparison across paid and organic listings at the query level. If you use data from the Paid and Organic report in any of your AdWords API or Scripts applications, then make sure you update them to adjust for this data change. Historic stats for mobile app install ads and Product Listing Ads will continue to be available from this report type up to the following report dates:

• Product Listing Ads - up to and including March 23, 2015
• Mobile app install ads - up to and including July 13, 2015

If you have any further questions about this change, let us know via the API or scripts forum, or Google+ page.

Anash P. Oommen, AdWords API Team

We have added the following new features in AdWords scripts.

Ad customizers
AdWords scripts now support ad customizers, a more advanced version of ad params. Ad customizers adapt your text ads to the full context of a search or the webpage someone's viewing, by inserting a customized parameter within the ad. Ad customizers let you customize your ads for each query without having to create a separate ad for each variation.

AdWords scripts allow you to create ad customizer sources, add or update items in the sources, and create parameterized ads. You can also target an ad customizer item to a specific campaign, ad group or keyword, and track the performance of ad customizers using the PLACEHOLDER_FEED_ITEM_REPORT.

To learn more about ad customizers, refer to our code snippets and guide. Also, check out the brand new ad customizers solution that shows how to use this new feature in your account.

v201409 reports
We now support AdWords API v201409 reports in AdWords scripts. See blog post for more details.

Product ads
You can now retrieve your product ads using the ads() method of the ShoppingAdGroup. You can create new product ads using the newAdBuilder() method of ShoppingAdGroup.

We hope you enjoy these new features. If you have any questions about these features or AdWords scripts in general, you can post them on the developer forum.

Anash P. Oommen, AdWords Scripts Team

We are announcing support for AdWords API v201406 reports in AdWords scripts. This version introduces several changes to the reporting columns.

Columns and fields cleanup

We've removed duplicates and changed column and display names in some reports:

Column Name	Change	Comments
ValuePerConvManyPerClick	Removed	Use ValuePerConversionManyPerClick instead.
ValuePerConv	Removed	Use ValuePerConversion instead.
TotalConvValue	Removed	Use ConversionValue instead.
PrimaryUserLogin	Removed
AccountId	Removed	Use ExternalCustomerId as unique account ID instead.
TargetingSetting	Removed	This column is now called IsRestrict and returns a proper boolean value.
NonDeletedAdGroupCount	Removed	New column name is NonRemovedAdGroupCount.
NonDeletedAdGroupCriteriaCount	Removed	New column name is NonRemovedAdGroupCriteriaCount.
NonDeletedCampaignCount	Removed	New column name is NonRemovedCampaignCount.

We also made changes to some enumerations for relevance and consistency:

• Status value for an enabled object is now ENABLED across all reports. Before, it was ACTIVE for some objects.
• Removed objects now have a status of REMOVED instead of DELETED.
• The PRODUCT_LISTING_AD_CLICKS display name has changed from Offer to Product listing ad.

If your scripts use these fields in reports, make sure you fix the AWQL when migrating to the new version of the reporting API. Keep in mind that if you don’t use API versioning in your reports, then your code will now be using reports API version v201406 by default.

New report fields

Several new report fields were introduced:

Report Name	New columns
Campaign Performance Report	ServingStatus
Click Performance Report	UserListId
Product Partition Report	date fields, CampaignName, AdGroupName
Multiple reports	ExternalCustomerId, IsRestrict, BiddingStrategyType
Campaign, AdGroup, Ad, and Keyword Performance Reports	Labels

You can refer to https://developers.google.com/adwords/api/docs/appendix/reports for the list of supported reports and columns.

If you have any questions about this feature or the AdWords scripts in general, you can post them on our developer forum.

Anash P. Oommen, AdWords Scripts Team

We are making a minor change to the values returned in the ClickType column in AdWords API reports. Starting the week of May 26th, 2014, AdWords API reports will return "Product listing ad" instead of "Offer" as the display value for click types corresponding to Product Listing Ads.

If you depend on the ClickType field, verify that your applications won't be negatively affected by the change in value.

If you have questions or feedback about this change, let us know on our forum or via the Google Ads Developers Google+ page.

Anash P. Oommen, AdWords API Team

As previously announced, AdWords API v201309 and AdWords scripts will start enforcing a limit of 10,000 matching values as arguments for the IN and NOT_IN operators starting March 31, 2014. This limit is currently enforced in AdWords API v201402.

You may be affected by this change if you construct large AWQL queries or selector predicates that have thousands of matching values using these operators in one of these use cases:

• AdWords API
  • Retrieving items using the query or get method
  • Requesting AdWords API reports using either AdWords Query Language (AWQL) or report definitions.
• AdWords scripts
  • Retrieving items using the get method
  • Requesting reports using the report method

To make sure your applications and scripts work properly, check any code that constructs queries for reports or retrieve items using get or query methods and add necessary limit checks before March 31, 2014.

If you have any questions about this change, you can post them on AdWords API or Scripts developer forums. Anash P. Oommen, AdWords API Team

To ensure reliable performance for all developers and advertisers, AdWords API and AdWords scripts will start enforcing a limit of 10,000 matching values as arguments for the IN and NOT_IN operators starting March 31, 2014.

You may be affected by this change if you construct large queries that have thousands of matching values using these operators in one of these use cases:

• AdWords API
  • Retrieving items using the query method
  • Requesting AdWords API reports using either AdWords Query Language (AWQL) or report definitions
• AdWords scripts
  • Retrieving items using the get method
  • Requesting reports using the report method

Once this change goes into effect, our servers will start throwing a SelectorError if your queries contains more than 10,000 matching values for IN and NOT_IN operators. For AdWords API v201309, the error reason would be set to SELECTOR_ERROR. In newer versions, the error reason would be set to TOO_MANY_PREDICATE_VALUES.

To make sure your applications and scripts work properly, check any code that constructs queries for reports and AWQL and add necessary limit checks before March 31, 2014.

If you have any questions about this change, you can post them on AdWords API or Scripts developer forums.

Anash P. Oommen, AdWords API Team

We are glad to announce the following new features in AdWords scripts.

1. Ad Rotation settings

AdWords supports an ad rotation setting that determines which ad in your ad group should show when you have multiple ads in your campaign. You can now access and modify this setting through the getAdRotationType and setAdRotationType methods of the Campaign object. When setting the adRotationType, you can use the string values OPTIMIZE, CONVERSION_OPTIMIZE, ROTATE, or ROTATE_FOREVER.

2. Support for identifying entity types

We now support a getEntityType method on all the AdWords entity classes like Campaign, AdGroup, etc. This method will return the name of the type, and can be used to identify the type of the object. E.g.

var campaign = AdWordsApp.getCampaignByName(
    "My campaign").get().next();
Logger.log(campaign.getEntityType()); // prints "Campaign"

3. Retrieve deleted objects

You may now retrieve deleted objects and their stats by explicitly requesting them in your AWQL. E.g. The following code snippet retrieves all deleted campaigns.

var deletedCampaigns = AdWordsApp.campaigns()
    .withCondition("Status='DELETED'").get();

Note that for backward compatibility purposes, we do not return deleted objects by default.

We hope you enjoy these new features. If you have questions or feedback, please visit us on our official forum.

Anash P. Oommen, AdWords Scripts Team

We recently exposed the Device column in the Click Performance Report. The Device column can have TABLET, HIGH_END_MOBILE or DESKTOP as its valid values. This is a segmentation column, so requesting it will prevent zero impression rows from being returned. If you have migrated to Enhanced Campaigns, then this column can be useful in finding out how your ads performed on various platforms, and adjusting your mobile bid modifier accordingly.

If you face any issues with the above changes or have any questions about this feature, you can ask us on our developer forum, or at the upcoming GDL Office Hours with the Developer Relations team.

 - Anash P. Oommen, AdWords API Team

In an effort to continue to improve report download functionality in the AdWords API, we’ve made some changes in v201209 to improve error handling and debugging for developers. In a future release, we also plan to separate API downloads from UI downloads to make the downloaded reports easier to work with for developers.

In v201209 we’ve introduced a new XML format for report download errors. Currently, we return a text string with the error message embedded within it. For example, if you mispelled the field Date as Datee:

!!!2|||-1|||ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT @ ; trigger:'Datee'???

In v201209, this error will be returned in this XML format (HTTP response codes will remain unchanged):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportDownloadError>
<ApiError>
<type>ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT</type>
<trigger>Datee</trigger>
<fieldPath/>
</ApiError>
</reportDownloadError>

The new error reporting format will make it easier to handle report download failures. If you’d like to preview these changes, you can pass this special HTTP header when downloading reports for versions prior to v201209:

apiMode: true

Support for this new XML error format will be added to client libraries for v201209. We’ve also published an XSD including this new report download error XML at:

https://adwords.google.com/api/adwords/reportdownload/vYYYYMM/reportDownloadError.xsd

For v201209, you can see it here. Some other things to keep in mind with these new changes:

• Remember to make sure you provide the version in the report download URL. With the next major release (and when specifying this new HTTP header), version will be required when downloading reports.
• AdHoc reports must be used - it will no longer be possible to download by reportDefinitionId.

If you have any questions about this new XML format or the AdWords API in general, please post on the forum. Follow our Google+ page for updates about the AdWords API.

 - Kevin Winter, AdWords API Team

To prepare for the introduction of new mobile capabilities in the AdWords API, we are making changes to the URL Performance Report and the Automatic Placements Performance Report in v201109 and v201109_1.

In the URL Performance Report:

• The Url field format is changing from
  {mobile-app-id}.adsenseformobileapps.com/{publisher-id} to
  {mobile-app-id}.adsenseformobileapps.com. 
• We are removing the {publisher-id} from the Url since the {mobile-app-id} rarely gets associated to more than one {publisher-id}. 

In the Automatic Placement Performance Report:

• Statistics for all mobile applications that have been grouped under the adsenseformobileapps.com Domain will now be broken out by mobile application. 
• The statistics for each mobile app will be at a Domain of the form
  {mobile-app-id}.adsenseformobileapps.com. 

These changes take effect on Monday, July 9th.

If you have any questions or concerns about this change, please post on the forum or attend one of the AdWords API Office Hours Hangouts.

 - David Torres, AdWords API Team

Recently the Ad Performance Report and AdGroupAdService of the AdWords API were returning incomplete data from Dynamic Search Ads. The report and API service were not prepared to support this type of Ad, which resulted in the report returning an undocumented “Website Ad” type, and the service returning AdGroupAd objects with no set ad property. This issue was fixed as of March 20th. We apologize for any inconvenience this change might have caused.

Note that even though Dynamic Search Ads are no longer returned in the Ad Performance Report, their performance data (i.e. impressions, clicks, conversions) is rolled up in reports such as the Account, Campaign and Ad Group performance reports.

If you have any questions about this change please reach out to us in the forum or during one of our office hours hangouts.

- The AdWords API Team

In the v201201 version of the API, we’ve added the ability to perform PQL filtering in reports. As an example of what you can do with this feature, you can now limit the report to only orders and line items you want to see. This will help shorten the report job processing time and reduces the size of the report generated. The following Java code snippet creates a report job to pull all the line items belonging to an order in your network:

Long orderId = Long.parseLong("INSERT_ORDER_ID_HERE");
// Create statement to filter for an order.
Statement filterStatement = new StatementBuilder(
    "WHERE ORDER_ID = :id").putValue("id", orderId).toStatement();

// Create report job.
ReportJob reportJob = new ReportJob();

// Create report query.
ReportQuery reportQuery = new ReportQuery();
reportQuery.setStatement(filterStatement);
reportQuery.setDateRangeType(DateRangeType.LAST_MONTH);
reportQuery.setDimensions(new Dimension[] {Dimension.LINE_ITEM});
reportQuery.setDimensionAttributes(new DimensionAttribute[] {
DimensionAttribute.ORDER_TRAFFICKER});
reportQuery.setColumns(
    new Column[] {Column.AD_SERVER_IMPRESSIONS, Column.AD_SERVER_REVENUE});
reportJob.setReportQuery(reportQuery);

The ‘ORDER_ID’ field in the WHERE clause is a dimension enumeration name. A full breakdown of the supported filter enumerations can be found in the documentation. We encourage the use of bind variables to build reusable filter statements, much like other services in the API where PQL is used. Whenever possible, try to filter on IDs rather than names (i.e. use CITY_CRITERIA_ID over CITY_NAME) since matching by name is case sensitive.

If you also specify the dateRangeType and dimensionFilters fields on the ReportQuery object, the filter statement will be applied in conjunction (in a logical AND) so that each entry in the report will match all of the filter criteria. You can check out a full working example in Java or language equivalent in our client libraries.

This is the first post in the Discover DFP API in v201201 series; our next post will cover syncing objects with the new lastModifiedDateTime field. Leave us a comment on the forum with any feedback you have for the API or topics you would like to see in the discover series.

 - Jeffrey Sham, DFP API Team

In this installment of the Discover DFP API v201111 series, we present new features we’ve added to reports in the API. In addition to merged ad server columns, which helps upgraded publishers reports on both DART and DFP ad servers, you can now use dimension attributes for greater control in reporting.

Dimension Attributes

Dimension attributes let you break down your report by additional fields associated with the dimension. For example, you can now add the trafficker, external ID, and order start date as dimension attributes associated to your order dimension in a delivery report. This is useful if you would like to see how each of your orders is doing and which trafficker was responsible for that order.

In the past, you would get this information by running a report for orders and then looking up the orders with Order Service to inspect the attributes. Now, it’s as simple as adding values to the dimensionAttributes field on your ReportQuery object and the corresponding fields will be integrated into the report. The following code snippet shows you how to create a report job with dimension attributes:

// Create report job.
ReportJob reportJob = new ReportJob();

// Create report query.
ReportQuery reportQuery = new ReportQuery();
reportQuery.setDateRangeType(DateRangeType.LAST_MONTH);
reportQuery.setDimensions(new Dimension[] {Dimension.ORDER});

// Set dimension attributes for order dimension.
reportQuery.setDimensionAttributes(new DimensionAttribute[] {
    DimensionAttribute.ORDER_TRAFFICKER,
    DimensionAttribute.ORDER_START_DATE_TIME,
    DimensionAttribute.ORDER_END_DATE_TIME});

// Set columns to report on.
reportQuery.setColumns(new Column[] {
    Column.AD_SERVER_IMPRESSIONS,
    Column.AD_SERVER_CLICKS});

reportJob.setReportQuery(reportQuery);

You can check out the full example in the RunDeliveryReportExample in the Java client library. Notice that you can only add dimension attributes for dimensions that you have in the report. For example, if you tried to add LINE_ITEM_EXTERNAL_ID, and you only have order (but not line item) as a dimension, you will get the following error:

ReportError.ATTRIBUTES_NOT_SUPPORTED_FOR_REQUEST

Be sure to check out our updated reporting examples in the client libraries and take a look at our documentation for a full mapping of supported dimension attributes and the fields they represent.

We are always looking for ways to improve the API and we’d love to get your feedback. Let us know what you’d like to see in the API or discussed in a blog post by posting on our forum. We’re also more than happy to chat during one of our office hours hangouts.

 - Jeffrey Sham, DFP API Team