Understanding various status codes

Thursday, January 27, 2011



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
action : mutate
operation: ADD
status : ACTIVE
action : mutate
operation: SET
status : ACTIVE
action : mutate
operation: SET
status: PAUSED
action : mutate
operation : SET
status: DELETED
action: mutate
operation: ADD
status: ENABLED
action : mutate
operation: SET
status : ENABLED
action: mutate
operation: SET
status : PAUSED
action : mutate
operation: SET
status: DELETED
action : mutate
operation: ADD
status: ENABLED
action : mutate
operation : SET
status : ENABLED
action : mutate
operation : SET
status : PAUSED
action: mutate
operation : REMOVE
status: DISABLED
action: mutate
operation: ADD
status: ACTIVE
action: mutate
operation: SET
status: ACTIVE
action: mutate
operation: SET
status: PAUSED
action: mutate
operation: REMOVE
status: DELETED
action: mutate
operation: ADD
status: ACTIVE
N/A
N/A
action: mutate
operation: REMOVE
status: DELETED
action:mutate
operation: ADD
status: ACTIVE
N/A
N/A
action: mutate
operation: SET
status: DELETED
action: mutate
operation: ADD
status: OPEN
N/A
N/A
action: mutate
operation: SET
status: CLOSED
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

Tuesday, January 25, 2011


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

Tuesday, January 11, 2011


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