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

Understanding various status codes

In the AdWords API, entities may have different values for the same status.  For instance, when you delete a campaign the status will be set to DELETED . But when you delete an  AdGroupAd object, the status will be DISABLED.

campaign.setStatus(CampaignStatus.DELETED);
operation.setOperator(Operator.SET);
campaignService.mutate(operations);

adGroupAd.setStatus(AdGroupAdStatus.DISABLED);
operation.setOperator(Operator.SET);
adGroupAdService.mutate(operations);

The following table shows the statuses available for each type, as well as the operation needed to change the status.  (Note: Some objects have more than one status field, but in this case we are only showing the user status.)

Type	Newly Added	Enable/ Active	Paused	Delete / Deactivated
Campaign	action : mutate operation: ADD status : ACTIVE	action : mutate operation: SET status : ACTIVE	action : mutate operation: SET status: PAUSED	action : mutate operation : SET status: DELETED
AdGroup	action: mutate operation: ADD status: ENABLED	action : mutate operation: SET status : ENABLED	action: mutate operation: SET status : PAUSED	action : mutate operation: SET status: DELETED
AdGroupAd	action : mutate operation: ADD status: ENABLED	action : mutate operation : SET status : ENABLED	action : mutate operation : SET status : PAUSED	action: mutate operation : REMOVE status: DISABLED
BiddableAdGroupCriterion	action: mutate operation: ADD status: ACTIVE	action: mutate operation: SET status: ACTIVE	action: mutate operation: SET status: PAUSED	action: mutate operation: REMOVE status: DELETED
AdExtensionOverride	action: mutate operation: ADD status: ACTIVE	N/A	N/A	action: mutate operation: REMOVE status: DELETED
CampaignAdExtension	action:mutate operation: ADD status: ACTIVE	N/A	N/A	action: mutate operation: SET status: DELETED
UserList	action: mutate operation: ADD status: OPEN	N/A	N/A	action: mutate operation: SET status: CLOSED
Experiment	action: mutate operation: ADD status: ACTIVE	N/A	N/A	action: mutate operation: SET status: DELETED

You can see code examples demonstrating how to use statuses in our client libraries. If you have any questions please post them on the AdWords API forum.

- Naoki Ishihara, AdWords API Team

Discover v2010 - Campaign Targeting

AdWords supports several campaign targeting options to ensure that your ads are shown only to the target audience you choose. As a developer, you can use the CampaignTargetService of AdWords API to set your campaign targets programmatically. This blog summarizes the various targeting options available through CampaignTargetService and how you can use them in your application.

Ad Schedule Target

AdScheduleTarget allows you to specify the dates and times at which your ads will be displayed. For example, the following C# code snippet targets your ads to run only on Mondays to Fridays, 9 AM to 5 PM.

List targets = new List();
DayOfWeek[] days = {
  DayOfWeek.MONDAY,
  DayOfWeek.TUESDAY,
  DayOfWeek.WEDNESDAY,
  DayOfWeek.THURSDAY,
  DayOfWeek.FRIDAY
};
 
for (int i = 0; i < days.Length; i++) {
  AdScheduleTarget target = new AdScheduleTarget();
  target.dayOfWeek = days[i];
  target.startHour = 9;
  target.startMinute = MinuteOfHour.ZERO;
  target.endHour = 17;
  target.endMinute = MinuteOfHour.ZERO;
  target.bidMultiplier = 1.0;
  targets.Add(target);
}
AdScheduleTargetList scheduleTargetList = new AdScheduleTargetList();
scheduleTargetList.campaignId = campaignId;
scheduleTargetList.targets = targets.ToArray();
   
// Create ad schedule target set operation.
CampaignTargetOperation scheduleTargetOperation = 
    new CampaignTargetOperation();
scheduleTargetOperation.@operator = Operator.SET;
scheduleTargetOperation.operand = scheduleTargetList;
 
CampaignTargetReturnValue retVal = campaignTargetService.mutate(
    new CampaignTargetOperation[] { scheduleTargetOperation });

If you create an empty AdScheduleTargetList, then your ads are served all the time. You can also specify a bidMultiplier (a double value between 0.1 and 10) to adjust your bid during a given ad schedule.

Demographic Targeting

DemographicTarget allows you to specify the gender and age group of your ad’s audience. The following code snippet targets your ad to females of the age range 18 to 24.

AgeTarget ageTarget = new AgeTarget();
ageTarget.age = AgeTargetAge.AGE_18_24;
GenderTarget genderTarget = new GenderTarget();
genderTarget.gender = GenderTargetGender.FEMALE;
 
DemographicTargetList demographicTargetList = new DemographicTargetList();
demographicTargetList.campaignId = campaignId;
demographicTargetList.targets = new DemographicTarget[] { ageTarget,
    genderTarget };

If you create an empty DemographicTargetList, then your ads are served to audience of all demographics. You can also specify a bidModifier (0 to 500) to modify the bids for a specific demographic target as an addition percentage. The new bid will be (1 + 0.01 * bidModifier) * bid.

Geographic Targeting

GeoTarget allows you to specify the geographic regions to target or exclude for showing your ads. For example, the following code snippet targets your ad to run only in US, but excludes New York city.

CountryTarget countryTarget = new CountryTarget();
countryTarget.countryCode = "US";
CityTarget cityTarget = new CityTarget();
cityTarget.cityName = "New York";
cityTarget.countryCode = "US";
cityTarget.excluded = true;
 
GeoTargetList geoTargetList = new GeoTargetList();
geoTargetList.campaignId = campaignId;
geoTargetList.targets = new GeoTarget[] { countryTarget, cityTarget };

If you create an empty GeoTargetList, then your ads are served in all geographic regions. The list of all supported geotargeting options and their codes are available here.

Language targeting

LanguageTarget allows you to target your ads for audiences that speaks a particular language. The following code snippet targets your ads only to Chinese (Simplified) and English speaking audiences.

LanguageTarget langTarget1 = new LanguageTarget();
langTarget1.languageCode = "en";
LanguageTarget langTarget2 = new LanguageTarget();
langTarget2.languageCode = "zh_CN";
 
// Create language targets.
LanguageTargetList langTargetList = new LanguageTargetList();
langTargetList.campaignId = campaignId;
langTargetList.targets = new LanguageTarget[] { langTarget1, langTarget2 };

If you create an empty LanguageTargetList, then all languages are targeted. The list of all supported language targets and their codes are available here.

Mobile Targeting

MobileTarget allows you to target your ads for one or more mobile carriers or platforms. For example, the following code snippet targets your ads to show only on Android device, and on TMobile(US) carrier.

// Target devices - Android.
MobilePlatformTarget mobilePlatformTarget1 = new MobilePlatformTarget();
mobilePlatformTarget1.platformName = "Android";
 
// Target Carriers - T-Mobile US.
MobileCarrierTarget mobileCarrierTarget1 = new MobileCarrierTarget();
mobileCarrierTarget1.carrierName = "T-Mobile";
mobileCarrierTarget1.countryCode = "US";
 
MobileTargetList mobileTargetList = new MobileTargetList();
mobileTargetList.campaignId = campaignId;
mobileTargetList.targets = new MobileTarget[] { mobilePlatformTarget1,
    mobileCarrierTarget1 };

If you create an empty MobileTargetList, then all mobile devices and mobile networks are targeted. The list of all supported mobile devices and networks are available here and here.

Network Targets

NetworkTarget allows you to target your ads for one networks (e.g. Google Search Network, Google Display Network, etc.). For example, the following code snippet targets your ads to show only on Google Search and Search Partners.

// Specifying GOOGLE_SEARCH is necessary if you want to target SEARCH_NETWORK.
NetworkTarget networkTarget1 = new NetworkTarget();
networkTarget1.networkCoverageType = NetworkCoverageType.GOOGLE_SEARCH;
NetworkTarget networkTarget2 = new NetworkTarget();
networkTarget2.networkCoverageType = NetworkCoverageType.SEARCH_NETWORK;
 
// Create network targets.
NetworkTargetList networkTargetList = new NetworkTargetList();
networkTargetList.campaignId = campaignId;
networkTargetList.targets = new NetworkTarget[] {
    networkTarget1, networkTarget2 };

Unlike other targets, if you create an empty NetworkTargetList, then your ads won’t be served to any network.

Platform Targets

PlatformTarget allows you to specify the type of device platform (Desktop and High End Mobile) to target your ads for. The following code snippets targets your ads to run only on high end mobile devices.

PlatformTarget platformTarget = new PlatformTarget();
platformTarget.platformType = PlatformType.HIGH_END_MOBILE;
 
// Create platform targets.
PlatformTargetList platformTargetList = new PlatformTargetList();
platformTargetList.campaignId = campaignId;
platformTargetList.targets = new PlatformTarget[] { platformTarget };

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

-- Anash P. Oommen, AdWords API Team

AdWords Downtime: January 15, 10am-2pm PST

We'll be performing routine system maintenance on Saturday, January 15 from approximately 10:00am to 2:00pm PST. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Best,

- Eric Koleda, AdWords API Team

Holiday reminder about IDs

Whether you recently updated your code or just started with the AdWords API, please keep in mind that IDs of all entities are represented as xsd:long (64 bit signed integer) values. It is important to note that if your code stores ID values in a data type with lower range, the value may suffer from integer overflow.

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

-- Stan Grinberg, AdWords API Team

Dive deeper with the reference documentation sidebar

There are a wide variety of resources available for those learning about the AdWords API, but since they’re spread out across multiple sites it’s not always easy to find the information you’re looking for. While we acknowledge the need for these multiple sources, we knew we could do more to bring together our content from Blogger, YouTube, Google Code, and Twitter. We saw the official reference documentation as a good home for the information, and so we’ve added a new sidebar to the service-level pages that displays related material.

The code examples are pulled from our client libraries, and they provide concrete examples of the services in action. The blog posts are pulled from this blog, and contain deep dives into the services, explaining the behaviors and use cases they are suited for. The videos are pulled from our YouTube playlist, and feature recordings from our developer workshops across the world. The tweets are pulled from our @adwordsapi account, and often contain short tips on how to use the services more efficiently.

The sidebar uses the Google Feeds API to pull data from our multiple repositories, meaning that new content will be automatically displayed as soon as it becomes available. We hope that this sidebar leads to more efficient and effective development against the AdWords API, and if you have feedback or further ideas please reach out to us on the forum.

- Eric Koleda, AdWords API Team

Even more dynamic ads: Announcing Ad parameters enhancements

After we launched version v2009 of the AdWords API we announced the addition of a new feature called Ad parameters. Since then, many of you have used Ad parameters to insert dynamic numeric values into your text ads while retaining the ads’ historical performance information. We’ve heard feedback from you about functionality you’d like to see included in Ad parameters so we've released some enhancements to the feature.

Here’s what’s new:

• You can now dynamically insert the percent sign (%) for values that include percentage discounts such as “Mobile Phone Accessories Now 20% Off”
• We’ve added support for additional currency symbols and codes so you can include the currency symbol in the dynamic parameter to create ad text like “Flights to London Starting at €250”
• You’re now able to use the forward slash character (/) for dynamic replacements with fraction discounts like “1/2 Off Our Entire Inventory Only This Weekend”
• The plus (+) and minus (-) signs are now supported so you can advertise “NASDAQ +20 Points Today, Speak With a Broker Now.”

We hope these enhancements enable you to create even more dynamic ads with Ad parameters. Please continue to share your feedback and questions with us on the developer forum.

--Jason Shafton, Product Marketing Manager