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