Update to reporting service in AdWords API v201101

Last week we announced AdWords API v201101, which included support for My Client Center (MCC) cross-client reports.

This feature did not go live as expected, so is currently only available to a limited set of developers. We hope to make it generally available in the coming weeks.

Please note that ReportDefinitionService will continue to work for non-cross-client reports as it did before.

If you have any questions please post them on the AdWords API forum.

Posted by Katie Wasilenko, AdWords API Team

New demo launch: AdWords Command Line Interface (AWCLI)

Today we’re releasing a new AdWords API sample application: AWCLI (AdWords Command Line Interface) intended to demonstrate a way for using the API. It’s a tool for AdWords interaction which was designed for power users and administrators to be able to inspect AdWords objects from a command line. It could also be used in various scripts and cron jobs.

The current code is work in progress. We’re sharing this code as open source to provide a starting point for new developers and to demonstrate some of the core functionality in the API.

AWCLI features

• Shell-like command line interface with tab-completion.
• Ability to list (ls), navigate (cd), retrieve (cat), edit (edit) and delete (rm) AdWords objects (campaigns, ad groups etc).
• Search (find) function.
• Local objects cache for easy referencing.
• Environment (env), history (history) and other utility functions.

Getting AWCLI

AWCLI is available from the Google Code page and is part of AdWords Java API project. It can be obtained from the downloads page: http://code.google.com/p/google-api-adwords-java/downloads/. You can find installation and running instructions as well as usage examples on the project wiki page.

Please join us to discuss the tool and report any bugs on the project page or forum.


Danial Klimkin, AdWords API Team.

AdWords API v201101 launch -- providing enhanced reporting, generic selectors, support for filtering and more

We’re pleased to announce the launch of AdWords API v201101, which allow you to more efficiently run reports, as well as implement campaign experiments and other recently released advertising features at scale. Through the AdWords API forum and developer events we’ve heard frequent requests for the newly available services. We’ve highlighted some of the new features below. A complete list of changes is available in the v201101 release notes.

v201101 highlights:

• Easily run reports across clients: ReportDefinitionService now supports My Client Center (MCC) cross-client reports, which are fetched asynchronously. The ReportDefinition type has two new fields with which you specify retrieval of a cross-client report, and all report types have new fields for use in cross-client reporting. In addition, the following new reports have been added: Geo Performance, Demographic Performance, Ad Extensions Performance,  Destination URL and Creative Conversion. See Report Types for more information.

• Greater data control and filtering with a single generic selector: The get operations for a number of services now use a single generic selector, rather than service-specific selectors. The generic selector provides more control over the data returned, lets you filter on almost any field, and specify sorting and paging. For information about migrating your code, see the Selector Migration Reference.

• Try out campaign experiments: A campaign can now try out sets of ads experimentally by using the ExperimentData in the AdGroupAd type. A new set of report fields provide information about how an advertiser experiment performed. The Ad Group Performance, Campaign Performance, Keywords Performance, and Managed Placements Performance reports each have a field that lets you segment on the control arm or experiment arm. In addition, a report field for each statistic indicates the significance in the change of that statistic in the experiment arm. For more information about campaign experiments, see the AdWords Campaign Experiments overview.

• Differentiate locations for desired targeting: A new setting for the Campaign type --  GeoTargetTypeSetting -- lets you specify how to apply geo targeting. The setting lets you differentiate between the user’s physical location and the location that’s targeted in the search. 

• Run interest-based advertising at scale (coming soon): Adwords API will fully support interest-based advertising via the ConversionTrackerService, which enables you to create a new conversion event and get the Javascript tag to create new lists. This service will be released in the coming weeks.

Deprecation timeline for previous versions
With the release of equivalent functionality in v201101, the following versions and services will be deprecated:

• API versions v13 (ReportService and TrafficEstimatorService only), v200909, v201003, v201008
• BidLandscapeService (being moved to the DataService)

We will be sunsetting these versions and services in August 2011.

As with every new version of the AdWords API, we encourage you to review the resources in the AdWords API client libraries. If you have any questions please post them on the AdWords API forum.

Posted by Katie Wasilenko, AdWords API Team

Announcing the next AdWords API Workshops in March

You may remember a series of AdWords API Workshops the Google Developer Relations team have hosted in the past. These workshops focused on new and upcoming features in the AdWords API and provided detailed code walkthroughs on how to use these new features (see videos).

We invite you to join us for our next AdWords API Workshops which we plan to host in the following cities:

• London, March 7th
• Amsterdam, March 9th
• San Francisco, March 9th
• Hamburg, March 11th
• New York City, March 15th

In addition to having our team on-hand to answer all your API-related questions, we will also be presenting technical deep-dives on the following topics:

• The new Report Service - including cross-client reporting
• Generic Selectors - a new and more efficient selection mechanism
• Remarketing - now fully accessible through the API
• AdWords Campaign Experiments - now with full access

All events will have the same agenda, and will run from approximately 10:00AM - 3:00PM (local time). These workshops are geared towards software engineers and developers who are already somewhat familiar with the AdWords API.

For more information and to register, visit: http://sites.google.com/site/awapiworkshops/home.

-- Sumit Chandel, AdWords API Team

Authentication changes with 2-step verification

We recently announced an advanced opt-in 2-step verification process to help make your Google Accounts significantly more secure. 2-step verification adds an extra layer of security to your Google Account by requiring unique “verification codes” in addition to your username and password at sign-in. This means that if your password is stolen, you still have an extra line of defense against a potential hijacker.

Enabling 2-step verification on a Google Account associated with an AdWords Account may lead to an authentication issue when using the AdWords API, which uses ClientLogin. ClientLogin provides the authentication functionality used by the AdWords API, and is not designed to ask for the verification codes in addition to the password. Therefore, APIs accessing this interface must instead use a special password called an application-specific password.

For 2-step verification users, the ClientLogin API will return an error indicating that the user needs to use an application-specific password if the user tries to login with his regular account password.  When this happens the response will contain an extra field that indicates that the error was due to a missing 2-step verification code, and not incorrect credentials.

Error=BadAuthentication
Info=InvalidSecondFactor

We recommend that your application detect this error and remind the user to use an application-specific password. The ClientLogin API doesn’t accept verification codes, but application-specific passwords can be created for an account that allow authentication without a verification code.  These can be used in the ClientLogin API just like regular passwords, and they do not expire.  To obtain an application-specific password, the user needs to log in to their Google Account and click on "Authorizing applications & sites."

Under the application-specific passwords section, they should provide the name of the tool or application they wish to generate a password for.  The generated password will only be displayed once, and although it can’t be recovered later it can be revoked at any time.

Here’s what the generated password looks like:

These changes to authentication only apply to applications that authenticate directly against a 2-step enabled account.  Applications that authenticate as an MCC account and specify a client account through the clientEmail or clientCustomerId header of the request need not to worry if 2-step verification is enabled the client account.

To learn more about application-specific passwords, visit the Google Accounts Help Center. Please visit the Official Google Blog for the complete announcement.

As always, please post any questions to the AdWords API Forum.

Posted by Katie Wasilenko, AdWords API Team

New Regions and Cities Now Available for Targeting

This week, we’ve expanded city-level location targeting to more countries. Starting today and over the coming weeks, we will be introducing new cities and regions in the following countries for targeting via the AdWords API.

Argentina (regions only)
Austria
Brazil
China (coming soon)
Colombia
Czech Republic
Finland (coming soon)
Hungary (coming soon)
Malaysia
Mexico
Morocco
New Zealand
Nigeria
Norway
Poland
South Korea
Switzerland
Ukraine

You can see the full list of new cities and regions that are supported now in the API Reference Guide. In order to target these locations, be sure to update your application so the new locations are available in your user interface.

As always, please post any questions to the AdWords API Forum.

Posted by Katie Wasilenko, AdWords API Team

Discover v201008: Product ads and criteria

We’ve recently released additional product advertising options in Google AdWords, and have exposed features in AdWords API v201008 to enable you to leverage these new ad formats. Product extensions enhance your existing text ads with relevant production information, while product listing ads expose your entire product catalog with minimal setup and maintenance. You can read further about the differences between these ad formats here.

In this post we’ll discuss how product ads can be created using the API. Note: both features require that you first link your Google Merchant Center account to your AdWords account. This is done through the Google Merchant Center web interface using these instructions.

Product extensions

Like other extensions, product extensions are represented as CampaignAdExtensions using the type ProductExtension. The CampaignAdExtensionService can be used to retrieve or delete product extensions, but at this time they can only be created through the AdWords web interface. Once they have been created they will be automatically applied to all text ads in the campaign, and utilize existing keyword targeting.

Product listing ads

The API type ProductAd corresponds to a product listing ad, and can be manipulated using the AdGroupAdService. Unlike other ad types, a majority of the information displayed in the ad is not stored in the AdWords system but is pulled from the Google Merchant Center when the ad is served. For this reason the ad is very simple, introducing only an optional promotionLine field. Additionally, the fields url and displayUrl aren’t supported for product listing ads, as these values are populated based on the product that is being shown.

The Product criterion (known as a “product target” in the web interface) is what allows you to control which products are eligible to be shown with a product listing ad and what the bid should be for those products. This criterion contains conditional rules used to filter your product catalog, limited to the following product attributes: product_type, brand, adwords_grouping, condition, and adwords_labels. It’s worth noting that a single Product criterion usually corresponds to multiple different products in the catalog.

Let’s take the example of a merchant that wants to advertise their line of store-made premium chocolates for Valentine’s day. Using the PHP client library they would first add the product listing ad to the ad group, with a promotional message for the holiday.

// Create product listing ad.
$productAd = new ProductAd();
$productAd->promotionLine = 'Order some sweets for your sweet!';

// Create ad group ad.
$adGroupAd = new AdGroupAd();
$adGroupAd->adGroupId = $adGroupId;
$adGroupAd->ad = $productAd;

// Create operation.
$operation = new AdGroupAdOperation();
$operation->operand = $adGroupAd;
$operation->operator = 'ADD';
$operations = array($operation);

// Add ad.
$result = $adGroupAdService->mutate($operations);

They would then add a product criterion to the ad group, filtering for products that are chocolates in their premium brand.

// Create product conditions.
$productTypeCondition = new ProductCondition('Chocolate',
new ProductConditionOperand('product_type'));
$brandCondition = new ProductCondition('Acme Premium',
new ProductConditionOperand('brand'));

// Create product criterion.
$product = new Product();
$product->conditions = array($productTypeCondition, $brandCondition);

// Create biddable ad group criterion.
$adGroupCriterion = new BiddableAdGroupCriterion();
$adGroupCriterion->adGroupId = $adGroupId;
$adGroupCriterion->criterion = $product;

// Create operation.
$operation = new AdGroupCriterionOperation();
$operation->operand = $adGroupCriterion;
$operation->operator = 'ADD';
$operations = array($operation);

// Add ad group criteria.
$result = $adGroupCriterionService->mutate($operations);

Using only this single ad and criterion all of their premium chocolates are ready to be advertised.

Additional information on how you can set up your campaigns to use product listing ads is available here. If you have any question about how to use product ad features in the API you can reach us on the forum.

Best,
- Eric Koleda, AdWords API Team